orion/docs/development/migration/module-autodiscovery-migration.md

# Module Auto-Discovery Migration History

This document tracks the migration of legacy code to the self-contained module architecture with auto-discovery.

## Overview

The Orion platform has been migrating from a monolithic structure with code in centralized locations (`app/api/v1/`, `app/services/`, `models/`) to a fully modular architecture where each module owns all its entities (routes, services, models, schemas, tasks).

## Migration Goals

1. **Self-Contained Modules**: Each module in `app/modules/{module}/` owns all its code
2. **Auto-Discovery**: All entities are automatically discovered - no manual registration
3. **No Legacy Dependencies**: Modules should not import from legacy locations
4. **Zero Framework Changes**: Adding/removing modules requires no changes to core framework

## Migration Timeline

### Phase 1: Foundation (2026-01-28)

#### Commit: `1ef5089` - Migrate schemas to canonical module locations
- Moved Pydantic schemas from `models/schema/` to `app/modules/{module}/schemas/`
- Established schema auto-discovery pattern

#### Commit: `b9f08b8` - Clean up legacy models and migrate remaining schemas
- Removed duplicate schema definitions
- Consolidated schema exports in module `__init__.py`

#### Commit: `0f9b80c` - Migrate Feature to billing module and split ProductMedia to catalog
- Moved `Feature` model to `app/modules/billing/models/`
- Moved `ProductMedia` to `app/modules/catalog/models/`

#### Commit: `d7de723` - Remove legacy feature.py re-export
- Removed `app/services/feature.py` re-export file
- Direct imports from module now required

### Phase 2: API Dependencies (2026-01-29)

#### Commit: `cad862f` - Introduce UserContext schema for API dependency injection
- Created `models/schema/auth.py` with `UserContext` schema
- Standardized store/admin API authentication pattern
- Enables consistent `token_store_id` access across routes

### Phase 3: Module Structure Enforcement (2026-01-29)

#### Commit: `434db15` - Add module exceptions, locales, and fix architecture warnings
- Added `exceptions.py` to all self-contained modules
- Created locale files for i18n support
- Fixed architecture validation warnings

#### Commit: `0b4291d` - Migrate JavaScript files to module directories
- Moved JS files from `static/store/js/` to `app/modules/{module}/static/store/js/`
- Module static files now auto-mounted at `/static/modules/{module}/`

### Phase 4: Customer Module (2026-01-30)

#### Commit: `e0b69f5` - Migrate customers routes to module with auto-discovery
- Created `app/modules/customers/routes/api/store.py`
- Moved customer management routes from legacy location

#### Commit: `0a82c84` - Remove legacy route files, fully self-contained
- Deleted `app/api/v1/store/customers.py`
- Customers module now fully self-contained

### Phase 5: Full Route Auto-Discovery (2026-01-31)

#### Commit: `db56b34` - Switch to full auto-discovery for module API routes
- Updated `app/modules/routes.py` with route auto-discovery
- Modules with `is_self_contained=True` have routes auto-registered
- No manual `include_router()` calls needed

#### Commit: `6f27813` - Migrate products and store_products to module auto-discovery
- Moved product routes to `app/modules/catalog/routes/api/`
- Moved store product routes to catalog module
- Deleted legacy `app/api/v1/store/products.py`

#### Commit: `e2cecff` - Migrate store billing, invoices, payments to module auto-discovery
- Created `app/modules/billing/routes/api/store_checkout.py`
- Created `app/modules/billing/routes/api/store_addons.py`
- Deleted legacy billing routes from `app/api/v1/store/`

### Phase 6: Store Routes Migration (2026-01-31)

- **Deleted**: `app/api/v1/store/analytics.py` (duplicate - analytics module already auto-discovered)
- **Created**: `app/modules/billing/routes/api/store_usage.py` (usage limits/upgrades)
- **Created**: `app/modules/marketplace/routes/api/store_onboarding.py` (onboarding wizard)
- **Deleted**: `app/api/v1/store/usage.py` (migrated to billing)
- **Deleted**: `app/api/v1/store/onboarding.py` (migrated to marketplace)
- Migrated remaining store routes to respective modules

### Phase 7: Admin Routes Migration (2026-01-31)

Major admin route migration to modules.

### Phase 8: Storefront Routes Auto-Discovery (2026-01-31)

- Updated `app/modules/routes.py` to discover `storefront.py` files
- Added `get_storefront_api_routes()` function
- Updated `app/api/v1/storefront/__init__.py` to use auto-discovery
- 37 storefront routes now auto-discovered from 7 modules:
  - cart, catalog, checkout, cms, customers, messaging, orders

**Admin routes migrated to modules:**

**Tenancy Module** (auth, users, merchants, platforms, stores):
- `admin_auth.py`, `admin_users.py`, `admin_admin_users.py`
- `admin_merchants.py`, `admin_platforms.py`, `admin_stores.py`
- `admin_store_domains.py`

**Core Module** (dashboard, settings):
- `admin_dashboard.py`, `admin_settings.py`

**Messaging Module** (messages, notifications, email templates):
- `admin_messages.py`, `admin_notifications.py`, `admin_email_templates.py`

**Monitoring Module** (logs, tasks, tests, code quality, audit, platform health):
- `admin_logs.py`, `admin_tasks.py`, `admin_tests.py`
- `admin_code_quality.py`, `admin_audit.py`, `admin_platform_health.py`

**CMS Module** (content pages, images, media, store themes):
- `admin_content_pages.py`, `admin_images.py`
- `admin_media.py`, `admin_store_themes.py`

**Billing Module** (subscriptions, invoices, payments, features):
- `admin_subscriptions.py`, `admin_invoices.py`, `admin_features.py`

**Inventory Module** (stock management):
- `admin.py` (inventory admin routes)

**Orders Module** (order management, exceptions):
- `admin_orders.py`, `admin_order_item_exceptions.py`

**Marketplace Module** (letzshop integration):
- `admin_letzshop.py`, `admin_marketplace.py`

## Current State

### ✅ Fully Migrated to Modules (Auto-Discovered)

| Module | Admin Routes | Store Routes | Services | Models | Schemas | Tasks |
|--------|--------------|---------------|----------|--------|---------|-------|
| analytics | - | ✅ API | Stats | Report | Stats | - |
| billing | ✅ subscriptions, invoices, features | ✅ checkout, addons, usage | Billing, Subscription | Tier, Subscription, Invoice | Billing | Subscription |
| catalog | ✅ products | ✅ products | Product | Product, Category | Product | - |
| cart | - | ✅ API | Cart | Cart, CartItem | Cart | Cleanup |
| checkout | - | ✅ API | Checkout | - | Checkout | - |
| cms | ✅ content-pages, images, media, store-themes | ✅ content-pages, media | ContentPage | ContentPage, Section | CMS | - |
| core | ✅ dashboard, settings | ✅ dashboard, settings | - | - | - | - |
| customers | - | ✅ API | Customer | Customer | Customer | - |
| inventory | ✅ stock | ✅ stock | Inventory | Stock, Location | Inventory | - |
| marketplace | ✅ letzshop, marketplace | ✅ onboarding, letzshop | Import, Export, Sync | ImportJob | Marketplace | Import, Export |
| messaging | ✅ messages, notifications, email-templates | ✅ messages, notifications, email | Message | Message | Message | - |
| monitoring | ✅ logs, tasks, tests, code-quality, audit, platform-health | - | - | TestRun, CodeQuality | - | - |
| orders | ✅ orders, exceptions | ✅ orders | Order | Order, OrderItem | Order | - |
| payments | - | ✅ API | Payment, Stripe | Payment | Payment | - |
| tenancy | ✅ auth, users, admin-users, merchants, platforms, stores | ✅ auth, profile, team, info | - | - | - | - |

### 🔒 Legacy Routes (Super Admin Only - Intentionally Kept)

These files remain in `app/api/v1/admin/` as they are super-admin framework configuration:

| File | Purpose | Why Legacy |
|------|---------|------------|
| `menu_config.py` | Navigation configuration | Framework-level config |
| `module_config.py` | Module settings | Framework-level config |
| `modules.py` | Module management | Framework-level config |

**Note:** These are intentionally kept in legacy location as they configure the module system itself.

### Still in Legacy Locations (Need Migration)

#### Services (`app/services/`)
- Many files still in legacy location
- Some are re-exports from modules
- Target: Move actual code to modules, delete re-exports

#### Tasks (`app/tasks/`)
- `letzshop_tasks.py` - Belongs in marketplace module
- `subscription_tasks.py` - Belongs in billing module
- Others need evaluation

## Architecture Rules

The following rules enforce the module-first architecture:

| Rule | Severity | Description |
|------|----------|-------------|
| MOD-016 | ERROR | Routes must be in modules, not `app/api/v1/{store,admin}/` |
| MOD-017 | ERROR | Services must be in modules, not `app/services/` |
| MOD-018 | ERROR | Tasks must be in modules, not `app/tasks/` |
| MOD-019 | WARNING | Schemas should be in modules, not `models/schema/` |

## Route Auto-Discovery Pattern

### Admin Routes Structure

Each module aggregates its admin routes in `routes/api/admin.py`:

```python
# app/modules/{module}/routes/api/admin.py
from fastapi import APIRouter, Depends
from app.api.deps import require_module_access

from .admin_feature1 import admin_feature1_router
from .admin_feature2 import admin_feature2_router

admin_router = APIRouter(
    dependencies=[Depends(require_module_access("{module}"))],
)

admin_router.include_router(admin_feature1_router, tags=["admin-feature1"])
admin_router.include_router(admin_feature2_router, tags=["admin-feature2"])
```

### Store Routes Structure

Similar pattern for store routes in `routes/api/store.py`:

```python
# app/modules/{module}/routes/api/store.py
from fastapi import APIRouter, Depends
from app.api.deps import require_module_access

from .store_feature1 import store_feature1_router

store_router = APIRouter(
    dependencies=[Depends(require_module_access("{module}"))],
)

store_router.include_router(store_feature1_router, tags=["store-feature1"])
```

## Next Steps

1. ✅ ~~Migrate remaining store routes~~ - COMPLETE
2. ✅ ~~Migrate admin routes~~ - COMPLETE (except super-admin framework config)
3. **Move services** from `app/services/` to module `services/`
4. **Move tasks** from `app/tasks/` to module `tasks/`
5. **Clean up re-exports** once all code is in modules

## Verification

Run architecture validation to check compliance:

```bash
python scripts/validate/validate_architecture.py
```

Check for legacy location violations:

```bash
python scripts/validate/validate_architecture.py -d app/api/v1/store
python scripts/validate/validate_architecture.py -d app/services
```

Verify route count:

```bash
python -c "
from main import app
routes = [r for r in app.routes if hasattr(r, 'path')]
print(f'Total routes: {len(routes)}')
admin = [r for r in routes if '/admin/' in r.path]
store = [r for r in routes if '/store/' in r.path]
print(f'Admin routes: {len(admin)}')
print(f'Store routes: {len(store)}')
"
```