refactor: migrate remaining routes to modules and enforce auto-discovery
MIGRATION: - Delete app/api/v1/vendor/analytics.py (duplicate - analytics module already auto-discovered) - Move usage routes from app/api/v1/vendor/usage.py to billing module - Move onboarding routes from app/api/v1/vendor/onboarding.py to marketplace module - Move features routes to billing module (admin + vendor) - Move inventory routes to inventory module (admin + vendor) - Move marketplace/letzshop routes to marketplace module - Move orders routes to orders module - Delete legacy letzshop service files (moved to marketplace module) DOCUMENTATION: - Add docs/development/migration/module-autodiscovery-migration.md with full migration history - Update docs/architecture/module-system.md with Entity Auto-Discovery Reference section - Add detailed sections for each entity type: routes, services, models, schemas, tasks, exceptions, templates, static files, locales, configuration ARCHITECTURE VALIDATION: - Add MOD-016: Routes must be in modules, not app/api/v1/ - Add MOD-017: Services must be in modules, not app/services/ - Add MOD-018: Tasks must be in modules, not app/tasks/ - Add MOD-019: Schemas must be in modules, not models/schema/ - Update scripts/validate_architecture.py with _validate_legacy_locations method - Update .architecture-rules/module.yaml with legacy location rules These rules enforce that all entities must be in self-contained modules. Legacy locations now trigger ERROR severity violations. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
170
docs/development/migration/module-autodiscovery-migration.md
Normal file
170
docs/development/migration/module-autodiscovery-migration.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
python scripts/validate_architecture.py
|
||||
```
|
||||
|
||||
Check for legacy location violations:
|
||||
|
||||
```bash
|
||||
python scripts/validate_architecture.py -d app/api/v1/vendor
|
||||
python scripts/validate_architecture.py -d app/services
|
||||
```
|
||||
Reference in New Issue
Block a user