orion/docs/proposals/SESSION_NOTE_2026-01-30_self-contained-module-routes.md

Self-Contained Module Routes Migration Plan

Date: 2026-01-30 Goal: Migrate all routes to self-contained modules, remove all legacy route files

Current State

Modules (17 total)

analytics, billing, cart, catalog, checkout, cms, customers, dev_tools,
inventory, loyalty, marketplace, messaging, monitoring, orders, payments

Legacy Route Files to Migrate

Admin API Routes (34 files in app/api/v1/admin/)

File	Target Module	Status
admin_users.py	PLATFORM CORE	Keep in legacy
audit.py	PLATFORM CORE	Keep in legacy
auth.py	PLATFORM CORE	Keep in legacy
background_tasks.py	monitoring	Migrate
code_quality.py	dev_tools	Migrate
companies.py	PLATFORM CORE	Keep in legacy
dashboard.py	PLATFORM CORE	Keep in legacy
email_templates.py	messaging	Migrate
features.py	billing	Migrate
images.py	cms	Migrate
inventory.py	inventory	Already migrated (re-export)
letzshop.py	marketplace	Already migrated (re-export)
logs.py	monitoring	Migrate
marketplace.py	marketplace	Already migrated (re-export)
media.py	cms	Migrate
menu_config.py	PLATFORM CORE	Keep in legacy
messages.py	messaging	Migrate
module_config.py	PLATFORM CORE	Keep in legacy
modules.py	PLATFORM CORE	Keep in legacy
monitoring.py	monitoring	Migrate
notifications.py	messaging	Migrate
order_item_exceptions.py	orders	Already migrated (re-export)
orders.py	orders	Already migrated (re-export)
platform_health.py	monitoring	Migrate
platforms.py	PLATFORM CORE	Keep in legacy
products.py	catalog	Migrate
settings.py	PLATFORM CORE	Keep in legacy
subscriptions.py	billing	Already migrated (re-export)
tests.py	dev_tools	Migrate
users.py	PLATFORM CORE	Keep in legacy
vendor_domains.py	PLATFORM CORE	Keep in legacy
vendor_products.py	catalog	Migrate
vendors.py	PLATFORM CORE	Keep in legacy
vendor_themes.py	cms	Migrate

Vendor API Routes (24 files in app/api/v1/vendor/)

File	Target Module	Status
analytics.py	analytics	Migrate
auth.py	PLATFORM CORE	Keep in legacy
billing.py	billing	Already migrated (re-export)
dashboard.py	PLATFORM CORE	Keep in legacy
email_settings.py	messaging	Migrate
email_templates.py	messaging	Migrate
features.py	billing	Migrate
info.py	PLATFORM CORE	Keep in legacy
inventory.py	inventory	Already migrated (re-export)
invoices.py	billing	Migrate
letzshop.py	marketplace	Already migrated (re-export)
marketplace.py	marketplace	Already migrated (re-export)
media.py	cms	Migrate
messages.py	messaging	Migrate
notifications.py	messaging	Migrate
onboarding.py	marketplace	Migrate
order_item_exceptions.py	orders	Already migrated (re-export)
orders.py	orders	Already migrated (re-export)
payments.py	payments	Migrate
products.py	catalog	Migrate
profile.py	PLATFORM CORE	Keep in legacy
settings.py	PLATFORM CORE	Keep in legacy
team.py	PLATFORM CORE	Keep in legacy
usage.py	billing	Migrate

Page Routes (4 files in app/routes/)

File	Target Module	Status
admin_pages.py	Split across modules	Migrate page by page
vendor_pages.py	Split across modules	Migrate page by page
storefront_pages.py	Split across modules	Migrate page by page
platform_pages.py	PLATFORM CORE	Keep in legacy

Migration Summary

Files to Migrate (by module)

1. billing (5 routes)

• app/api/v1/admin/features.py
• app/api/v1/vendor/features.py
• app/api/v1/vendor/invoices.py
• app/api/v1/vendor/usage.py
• Remove re-exports: subscriptions.py, billing.py

2. catalog (3 routes)

• app/api/v1/admin/products.py
• app/api/v1/admin/vendor_products.py
• app/api/v1/vendor/products.py

3. cms (4 routes)

• app/api/v1/admin/images.py
• app/api/v1/admin/media.py
• app/api/v1/admin/vendor_themes.py
• app/api/v1/vendor/media.py

4. messaging (7 routes)

• app/api/v1/admin/email_templates.py
• app/api/v1/admin/messages.py
• app/api/v1/admin/notifications.py
• app/api/v1/vendor/email_settings.py
• app/api/v1/vendor/email_templates.py
• app/api/v1/vendor/messages.py
• app/api/v1/vendor/notifications.py

5. monitoring (4 routes)

• app/api/v1/admin/background_tasks.py
• app/api/v1/admin/logs.py
• app/api/v1/admin/monitoring.py
• app/api/v1/admin/platform_health.py

6. dev_tools (2 routes)

• app/api/v1/admin/code_quality.py
• app/api/v1/admin/tests.py

7. marketplace (1 route)

• app/api/v1/vendor/onboarding.py
• Remove re-exports: letzshop.py, marketplace.py

8. analytics (1 route)

• app/api/v1/vendor/analytics.py

9. payments (1 route)

• app/api/v1/vendor/payments.py

10. orders (cleanup)

• Remove re-exports: orders.py, order_item_exceptions.py

11. inventory (cleanup)

• Remove re-exports: inventory.py

Files to Keep in Platform Core (12 admin + 6 vendor = 18 files)

Admin:

• admin_users.py - Admin user management (super admin only)
• audit.py - Platform audit logs
• auth.py - Admin authentication
• companies.py - Company management
• dashboard.py - Admin dashboard
• menu_config.py - Menu configuration
• module_config.py - Module configuration
• modules.py - Module management
• platforms.py - Platform management
• settings.py - Platform settings
• users.py - Platform user management
• vendor_domains.py - Vendor domain management
• vendors.py - Vendor management

Vendor:

• auth.py - Vendor authentication
• dashboard.py - Vendor dashboard
• info.py - Vendor info endpoint
• profile.py - Vendor profile
• settings.py - Vendor settings
• team.py - Vendor team management

Execution Plan

Phase 1: API Routes (Priority Order)

1. messaging (7 files) - Largest module, get it done first
2. billing (5 files) - Already partially migrated
3. monitoring (4 files) - Self-contained
4. cms (4 files) - Already partially migrated
5. catalog (3 files) - Product management
6. dev_tools (2 files) - Testing tools
7. marketplace (1 file) - Just onboarding
8. analytics (1 file) - Simple
9. payments (1 file) - Simple
10. Cleanup - Remove all re-export files for orders, inventory

Phase 2: Page Routes

Each module that has admin/vendor pages needs:

1. Create app/modules/{module}/routes/pages/admin.py
2. Create app/modules/{module}/routes/pages/vendor.py
3. Move relevant page handlers from legacy files
4. Update admin_pages.py / vendor_pages.py to import from modules

Phase 3: Storefront Routes

1. cart module - Cart pages
2. catalog module - Product listing, detail pages
3. checkout module - Checkout flow
4. customers module - Customer account pages

Pattern Reference (from customers module)

Module Route Structure

app/modules/{module}/
├── routes/
│   ├── __init__.py      # Lazy exports
│   ├── admin.py         # Admin API routes with admin_router
│   ├── vendor.py        # Vendor API routes with vendor_router
│   ├── api/             # Optional: Split API routes
│   │   ├── admin.py
│   │   ├── vendor.py
│   │   └── storefront.py
│   └── pages/           # HTML page routes
│       ├── admin.py
│       └── vendor.py
└── definition.py        # Module definition with router getters

Module Definition Pattern

def _get_admin_router():
    from app.modules.{module}.routes.admin import admin_router
    return admin_router

def _get_vendor_router():
    from app.modules.{module}.routes.vendor import vendor_router
    return vendor_router

# In get_{module}_module_with_routers():
{module}_module.admin_router = _get_admin_router()
{module}_module.vendor_router = _get_vendor_router()

Router Registration in app/api/v1/{admin,vendor}/__init__.py

# Import module router
from app.modules.{module}.routes.admin import admin_router as {module}_admin_router

# Include with module access control
router.include_router({module}_admin_router, tags=["admin-{module}"])
# Legacy: router.include_router({module}.router, tags=["admin-{module}"])

Validation

After each module migration:

1. Run python scripts/validate_architecture.py
2. Test affected endpoints manually
3. Verify imports work: python -c "from app.api.v1.admin import router"

Estimated Effort

• API Routes: ~28 files to migrate across 9 modules
• Page Routes: ~15-20 page handlers to move
• Total: 1-2 sessions depending on complexity