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:

# 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:

# 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:

python scripts/validate/validate_architecture.py

Check for legacy location violations:

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

Verify route count:

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)}')
"