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 Wizamart 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 vendor/admin API authentication pattern
• Enables consistent token_vendor_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/vendor/js/ to app/modules/{module}/static/vendor/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/vendor.py
• Moved customer management routes from legacy location

Commit: 0a82c84 - Remove legacy route files, fully self-contained

• Deleted app/api/v1/vendor/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 vendor_products to module auto-discovery

• Moved product routes to app/modules/catalog/routes/api/
• Moved vendor product routes to catalog module
• Deleted legacy app/api/v1/vendor/products.py

Commit: e2cecff - Migrate vendor billing, invoices, payments to module auto-discovery

• Created app/modules/billing/routes/api/vendor_checkout.py
• Created app/modules/billing/routes/api/vendor_addons.py
• Deleted legacy billing routes from app/api/v1/vendor/

Phase 6: Remaining Vendor Routes (2026-01-31)

Current Changes - Migrate analytics, usage, onboarding

• Deleted: app/api/v1/vendor/analytics.py (duplicate - analytics module already auto-discovered)
• Created: app/modules/billing/routes/api/vendor_usage.py (usage limits/upgrades)
• Created: app/modules/marketplace/routes/api/vendor_onboarding.py (onboarding wizard)
• Deleted: app/api/v1/vendor/usage.py (migrated to billing)
• Deleted: app/api/v1/vendor/onboarding.py (migrated to marketplace)

Current State

Migrated to Modules (Auto-Discovered)

Module	Routes	Services	Models	Schemas	Tasks
analytics	API	Stats	Report	Stats	-
billing	API	Billing, Subscription	Tier, Subscription, Invoice	Billing	Subscription
catalog	API	Product	Product, Category	Product	-
cart	API	Cart	Cart, CartItem	Cart	Cleanup
checkout	API	Checkout	-	Checkout	-
cms	API, Pages	ContentPage	ContentPage, Section	CMS	-
customers	API	Customer	Customer	Customer	-
inventory	API	Inventory	Stock, Location	Inventory	-
marketplace	API	Import, Export, Sync	ImportJob	Marketplace	Import, Export
messaging	API	Message	Message	Message	-
orders	API	Order	Order, OrderItem	Order	-
payments	API	Payment, Stripe	Payment	Payment	-

Still in Legacy Locations (Need Migration)

Vendor Routes (app/api/v1/vendor/)

• auth.py - Authentication (belongs in core/tenancy)
• dashboard.py - Dashboard (belongs in core)
• email_settings.py - Email settings (belongs in messaging)
• email_templates.py - Email templates (belongs in messaging)
• info.py - Vendor info (belongs in tenancy)
• media.py - Media library (belongs in cms)
• messages.py - Messages (belongs in messaging)
• notifications.py - Notifications (belongs in messaging)
• profile.py - Profile (belongs in core/tenancy)
• settings.py - Settings (belongs in core)
• team.py - Team management (belongs in tenancy)

Admin Routes (app/api/v1/admin/)

• Most files still in legacy location
• Target: Move to respective modules or tenancy module

Services (app/services/)

• 61 files still in legacy location
• Many 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/{vendor,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/

Next Steps

1. Migrate remaining vendor routes to appropriate modules
2. Migrate admin routes to modules
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_architecture.py

Check for legacy location violations:

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