sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add plan for self-contained module routes migration

Browse Source 
Comprehensive plan to:
- Migrate 28 API route files to their respective modules
- Remove all legacy re-export files
- Migrate page routes to modules
- Keep 18 platform core routes in legacy location

Modules affected: billing, catalog, cms, messaging, monitoring,
dev_tools, marketplace, analytics, payments, orders, inventory

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2026-01-30 23:31:49 +01:00
parent 0a82c846ce
commit 9fb3588030
1 changed files with 257 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
docs/proposals/SESSION_NOTE_2026-01-30_self-contained-module-routes.md Normal file
View File

@@ -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