# 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 |
| `merchants.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 |
| `store_domains.py` | **PLATFORM CORE** | Keep in legacy |
| `store_products.py` | catalog | Migrate |
| `stores.py` | **PLATFORM CORE** | Keep in legacy |
| `store_themes.py` | cms | Migrate |

#### Store API Routes (24 files in `app/api/v1/store/`)
| 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 |
| `store_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/store/features.py`
- `app/api/v1/store/invoices.py`
- `app/api/v1/store/usage.py`
- Remove re-exports: `subscriptions.py`, `billing.py`

#### 2. catalog (3 routes)
- `app/api/v1/admin/products.py`
- `app/api/v1/admin/store_products.py`
- `app/api/v1/store/products.py`

#### 3. cms (4 routes)
- `app/api/v1/admin/images.py`
- `app/api/v1/admin/media.py`
- `app/api/v1/admin/store_themes.py`
- `app/api/v1/store/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/store/email_settings.py`
- `app/api/v1/store/email_templates.py`
- `app/api/v1/store/messages.py`
- `app/api/v1/store/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/store/onboarding.py`
- Remove re-exports: `letzshop.py`, `marketplace.py`

#### 8. analytics (1 route)
- `app/api/v1/store/analytics.py`

#### 9. payments (1 route)
- `app/api/v1/store/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 store = 18 files)

**Admin:**
- `admin_users.py` - Admin user management (super admin only)
- `audit.py` - Platform audit logs
- `auth.py` - Admin authentication
- `merchants.py` - Merchant 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
- `store_domains.py` - Store domain management
- `stores.py` - Store management

**Store:**
- `auth.py` - Store authentication
- `dashboard.py` - Store dashboard
- `info.py` - Store info endpoint
- `profile.py` - Store profile
- `settings.py` - Store settings
- `team.py` - Store 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/store pages needs:
1. Create `app/modules/{module}/routes/pages/admin.py`
2. Create `app/modules/{module}/routes/pages/store.py`
3. Move relevant page handlers from legacy files
4. Update `admin_pages.py` / `store_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
│   ├── store.py        # Store API routes with store_router
│   ├── api/             # Optional: Split API routes
│   │   ├── admin.py
│   │   ├── store.py
│   │   └── storefront.py
│   └── pages/           # HTML page routes
│       ├── admin.py
│       └── store.py
└── definition.py        # Module definition with router getters
```

### Module Definition Pattern
```python
def _get_admin_router():
    from app.modules.{module}.routes.admin import admin_router
    return admin_router

def _get_store_router():
    from app.modules.{module}.routes.store import store_router
    return store_router

# In get_{module}_module_with_routers():
{module}_module.admin_router = _get_admin_router()
{module}_module.store_router = _get_store_router()
```

### Router Registration in `app/api/v1/{admin,store}/__init__.py`
```python
# 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/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