diff --git a/docs/proposals/SESSION_NOTE_2026-01-30_self-contained-module-routes.md b/docs/proposals/SESSION_NOTE_2026-01-30_self-contained-module-routes.md
new file mode 100644
index 00000000..3ceafd53
--- /dev/null
+++ b/docs/proposals/SESSION_NOTE_2026-01-30_self-contained-module-routes.md
@@ -0,0 +1,257 @@
+# 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
+```python
+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`
+```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_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