Add new validation rules MOD-020 to MOD-023 for module definition
completeness and standardize permissions across all modules.
Changes:
- Add MOD-020: Module definitions must have required attributes
- Add MOD-021: Modules with menus should have features
- Add MOD-022: Feature modules should have permissions
- Add MOD-023: Modules with routers should use get_*_with_routers pattern
Module permissions added:
- analytics: view, export, manage_dashboards
- billing: view_tiers, manage_tiers, view_subscriptions, manage_subscriptions, view_invoices
- cart: view, manage
- checkout: view_settings, manage_settings
- cms: view_pages, manage_pages, view_media, manage_media, manage_themes
- loyalty: view_programs, manage_programs, view_rewards, manage_rewards
- marketplace: view_integration, manage_integration, sync_products
- messaging: view_messages, send_messages, manage_templates
- payments: view_gateways, manage_gateways, view_transactions
Module improvements:
- Complete cart module with features and permissions
- Complete checkout module with features and permissions
- Add features to catalog module
- Add version to cms module
- Fix loyalty platform_router attachment
- Add path definitions to payments module
- Remove empty scheduled_tasks from dev_tools module
Documentation:
- Update module-system.md with new validation rules
- Update architecture-rules.md with MOD-020 to MOD-023
Tests:
- Add unit tests for module definition completeness
- Add tests for permission structure validation
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Delete app/core/permissions.py (VendorPermissions enum, PermissionGroups)
- Update all code to use permission_discovery_service directly:
- app/api/deps.py: get_user_permissions() uses discovery service
- app/modules/tenancy/models/vendor.py: get_all_permissions() uses discovery
- app/modules/tenancy/routes/api/vendor_team.py: use string literals
- app/modules/tenancy/services/vendor_team_service.py: use discovery service
- scripts/init_production.py: use discovery service for presets
Permissions are now fully module-driven:
- Each module defines permissions in definition.py
- PermissionDiscoveryService aggregates all permissions
- Role presets reference permission IDs directly
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
File Relocations:
- Delete app/config/ folder (empty after menu_registry removal)
- Move feature_gate.py → app/modules/billing/dependencies/
- Move theme_presets.py → app/modules/cms/services/
Module-Driven Permissions System:
- Add PermissionDefinition dataclass to app/modules/base.py
- Create PermissionDiscoveryService in tenancy module
- Update module definitions to declare their own permissions:
- core: dashboard.view, settings.*
- catalog: products.*
- orders: orders.*
- inventory: stock.*
- customers: customers.*
- tenancy: team.*
- Update app/core/permissions.py to use discovery service
- Role presets (owner, manager, staff, etc.) now use module permissions
This follows the same pattern as module-driven menus:
- Each module defines its permissions in definition.py
- PermissionDiscoveryService aggregates all permissions at runtime
- Tenancy module handles role-to-permission assignment
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Delete app/config/menu_registry.py (centralized menu definitions)
- Update app/config/__init__.py to remove menu_registry exports
- Migrate menu_service.py to use menu_discovery_service exclusively
- Add helper methods to menu_discovery_service.py:
- get_all_menu_item_ids() - get all item IDs for a frontend type
- get_menu_item() - get specific menu item by ID
- is_super_admin_only_item() - check if item is super-admin only
- get_menu_item_module() - get module code for a menu item
Menu items are now defined in each module's definition.py file and
aggregated by MenuDiscoveryService at runtime, enabling true
module-driven architecture.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
JavaScript improvements:
- Add try/catch error handling to all async init() functions
- Move initialization guards before try/catch blocks (JS-005)
- Use centralized logger in i18n.js with silent fallback (JS-001)
- Add loading state to icons-page.js (JS-007)
Payments module structure:
- Add templates/, static/, and locales/ directories (MOD-005)
- Add locale files for en, de, fr, lb (MOD-006)
Architecture validation now passes with 0 errors, 0 warnings, 0 info.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit completes the migration to a fully module-driven architecture:
## Models Migration
- Moved all domain models from models/database/ to their respective modules:
- tenancy: User, Admin, Vendor, Company, Platform, VendorDomain, etc.
- cms: MediaFile, VendorTheme
- messaging: Email, VendorEmailSettings, VendorEmailTemplate
- core: AdminMenuConfig
- models/database/ now only contains Base and TimestampMixin (infrastructure)
## Schemas Migration
- Moved all domain schemas from models/schema/ to their respective modules:
- tenancy: company, vendor, admin, team, vendor_domain
- cms: media, image, vendor_theme
- messaging: email
- models/schema/ now only contains base.py and auth.py (infrastructure)
## Routes Migration
- Moved admin routes from app/api/v1/admin/ to modules:
- menu_config.py -> core module
- modules.py -> tenancy module
- module_config.py -> tenancy module
- app/api/v1/admin/ now only aggregates auto-discovered module routes
## Menu System
- Implemented module-driven menu system with MenuDiscoveryService
- Extended FrontendType enum: PLATFORM, ADMIN, VENDOR, STOREFRONT
- Added MenuItemDefinition and MenuSectionDefinition dataclasses
- Each module now defines its own menu items in definition.py
- MenuService integrates with MenuDiscoveryService for template rendering
## Documentation
- Updated docs/architecture/models-structure.md
- Updated docs/architecture/menu-management.md
- Updated architecture validation rules for new exceptions
## Architecture Validation
- Updated MOD-019 rule to allow base.py in models/schema/
- Created core module exceptions.py and schemas/ directory
- All validation errors resolved (only warnings remain)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The circular import occurred because:
1. app.modules.base imported FrontendType from models.database.admin_menu_config
2. This triggered models/database/__init__.py which runs model discovery
3. Model discovery imported module definitions
4. Module definitions imported from app.modules.base (still initializing)
Solution: Move FrontendType and MANDATORY_MENU_ITEMS to a new
app/modules/enums.py file. The models file re-exports them for
backward compatibility with existing imports.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The dev_tools API routes were moved to the monitoring module, but several
files still tried to import the non-existent admin_router. This caused
warnings during app startup.
Changes:
- Remove _get_admin_router() from definition.py
- Clear routes/__init__.py and routes/api/__init__.py of broken imports
- Update exceptions.py to import from monitoring.exceptions
- Update code_quality_service.py to import from monitoring.exceptions
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
MIGRATION:
- Move app/api/v1/vendor/info.py to app/modules/tenancy/routes/api/vendor.py
- Change endpoint path from GET /{vendor_code} to GET /info/{vendor_code}
- Remove catch-all route ordering dependency
TENANCY MODULE SETUP:
- Mark tenancy module as is_self_contained=True
- Add routes/api/vendor.py with vendor_router
- Add exceptions.py with TenancyException hierarchy
- Add placeholder __init__.py files for services, models, schemas
FRONTEND UPDATES:
- Update static/vendor/js/login.js to use new /vendor/info/{vendor_code} path
- Update static/vendor/js/init-alpine.js to use new /vendor/info/{vendor_code} path
The new path is more explicit and eliminates the need for catch-all route
ordering in the vendor router aggregation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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>
- Move admin/products.py to marketplace module as admin_products.py
(marketplace product catalog browsing)
- Move admin/vendor_products.py to catalog module as admin.py
(vendor catalog management)
- Move vendor/products.py to catalog module as vendor.py
(vendor's own product catalog)
- Update marketplace admin router to include products routes
- Update catalog module routes/api/__init__.py with lazy imports
- Remove legacy imports from admin and vendor API init files
All product routes now auto-discovered via module system.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Enhanced route discovery system with ROUTE_CONFIG support for custom
prefix, tags, and priority
- Added get_admin_api_routes() and get_vendor_api_routes() helpers that
return routes sorted by priority
- Added fallback discovery for routes/{frontend}.py when routes/api/
doesn't exist
- Updated CMS module with ROUTE_CONFIG (prefix: /content-pages,
priority: 100) to register last for catch-all routes
- Moved customers routes from routes/ to routes/api/ directory
- Updated orders module to aggregate exception routers into main routers
- Removed manual module router imports from admin and vendor API init
files, replaced with auto-discovery loop
Modules now auto-discovered: billing, inventory, orders, marketplace,
cms, customers, analytics, loyalty, messaging, monitoring, dev-tools
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Delete app/api/v1/admin/customers.py (no backward compatibility)
- Delete app/api/v1/vendor/customers.py (no backward compatibility)
- Remove legacy router aliases from module routes
- Routes now fully self-contained in app/modules/customers/routes/
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move customer route implementations to app/modules/customers/routes/
- Convert legacy app/api/v1/{admin,vendor}/customers.py to re-exports
- Update router registrations to use module routers with access control
- Fix CustomerListResponse pagination (page/per_page/total_pages)
- Update URL routing docs to use storefront consistently
- Fix mkdocs.yml nav references (shop -> storefront)
- Fix broken doc links in logging.md and cdn-fallback-strategy.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Media library management is part of content management (CMS).
This matches the Python pattern where:
- Core media service (upload, storage) stays in platform
- Media library UI (browsing, organizing) goes to CMS module
- Media picker component stays shared (used by products, CMS, etc.)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
components.js is a UI components library reference for developers,
so it belongs in dev_tools alongside icons-page.js, testing-*.js,
and code-quality-*.js.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
icons-page.js is a dev tool for browsing available icons, so it
belongs in dev_tools alongside testing-*.js and code-quality-*.js.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
users.js, user-detail.js, user-edit.js, user-create.js are for
managing platform/vendor users, not shop customers. Move them
back to static/admin/js/ where other platform admin files reside.
The customers module retains customers.js which manages actual
shop customers (people who buy from vendors).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move Feature model from models/database/ to app/modules/billing/models/
(tightly coupled to SubscriptionTier for tier-based access control)
- Move ProductMedia from models/database/media.py to app/modules/catalog/models/
(product-specific media associations belong with catalog)
- Keep MediaFile as CORE in models/database/media.py (cross-cutting file storage)
- Convert legacy feature.py to re-export for backwards compatibility
- Update all imports to use canonical module locations
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix cart to import from app.modules.base instead of non-existent
app.modules.core.module_registry
- Change 'dependencies' to 'requires' (correct attribute name)
- Remove invalid 'provides_*' attributes that don't exist in
ModuleDefinition dataclass
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Update models/database/__init__.py to import from module locations
- Update models/schema/__init__.py to remove deleted modules
- Update models/__init__.py to import Inventory from module
- Remove duplicate AdminNotification from models/database/admin.py
- Fix monitoring module to import AdminNotification from messaging
- Update stats schema imports in admin/vendor API
- Update notification schema imports
- Add order_item_exception.py schema to orders module
- Fix app/api/v1/__init__.py to use storefront instead of shop
- Add cms_admin_pages import to main.py
- Fix password_reset_token imports
- Fix AdminNotification test imports
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update all module files to import from canonical module locations
instead of legacy re-export files:
- checkout, orders, customers routes: use module schemas
- catalog, marketplace schemas: use inventory module schemas
- marketplace, customers, inventory, analytics services: use module models
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 5 of storefront restructure plan - fix direct model imports in
API routes by using schemas for dependency injection.
Created CustomerContext schema:
- Lightweight Pydantic model for customer data in API routes
- Populated from Customer DB model in auth dependency
- Contains all fields needed by storefront routes
- Includes from_db_model() factory method
Updated app/api/deps.py:
- _validate_customer_token now returns CustomerContext instead of Customer
- Updated docstrings for all customer auth functions
Updated module storefront routes:
- customers: Uses CustomerContext for profile/address endpoints
- orders: Uses CustomerContext for order history endpoints
- checkout: Uses CustomerContext for order placement
- messaging: Uses CustomerContext for messaging endpoints
This enforces the layered architecture (Routes → Services → Models)
by ensuring API routes never import database models directly.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 4 of storefront restructure plan - move API routes from legacy
app/api/v1/storefront/ to their respective modules:
- customers: auth, profile, addresses routes combined into storefront.py
- orders: order history viewing routes
- checkout: order placement (place_order endpoint)
- messaging: customer messaging routes
Updated app/api/v1/storefront/__init__.py to import from modules:
- cart_router from app.modules.cart
- catalog_router from app.modules.catalog
- checkout_router from app.modules.checkout
- customers_router from app.modules.customers
- orders_router from app.modules.orders
- messaging_router from app.modules.messaging
Legacy route files in app/api/v1/storefront/ can now be deleted
in Phase 6.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 3 of storefront restructure plan - create dedicated modules for
e-commerce functionality:
- cart: Shopping cart management with storefront API routes
- CartItem model with cents-based pricing
- CartService for cart operations
- Storefront routes for cart CRUD operations
- catalog: Product catalog browsing for customers
- CatalogService for public product queries
- Storefront routes for product listing/search/details
- checkout: Order creation from cart (placeholder)
- CheckoutService stub for future cart-to-order conversion
- Schemas for checkout flow
These modules separate e-commerce concerns from core platform
concerns (customer auth), enabling non-commerce platforms.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Rename "shop" to "storefront" as not all platforms sell items -
storefront is a more accurate term for the customer-facing interface.
Changes:
- Rename app/api/v1/shop/ → app/api/v1/storefront/
- Rename app/routes/shop_pages.py → app/routes/storefront_pages.py
- Rename app/modules/cms/routes/api/shop.py → storefront.py
- Rename tests/integration/api/v1/shop/ → storefront/
- Update API prefix from /api/v1/shop to /api/v1/storefront
- Update route tags from shop-* to storefront-*
- Rename get_shop_context() → get_storefront_context()
- Update architecture rules to reference storefront paths
- Update all test API endpoint paths
This is Phase 2 of the storefront module restructure plan.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add architecture rule that detects when API routes import database
models directly, enforcing Routes → Services → Models pattern.
Changes:
- Add API-007 rule to .architecture-rules/api.yaml
- Add _check_no_model_imports() validation to validator script
- Update customer imports to use canonical module location
- Add storefront module restructure implementation plan
The validator now detects 81 violations across 67 API files where
database models are imported directly instead of going through
services. This is Phase 1 of the storefront restructure plan.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- app/modules/registry.py: Use auto-discovery from discovery.py
- main.py: Integrate module route auto-discovery
- app/routes/vendor_pages.py: Remove routes now handled by modules
The registry now dynamically discovers modules from definition.py
files instead of hardcoded imports.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add self-contained configuration and migrations support for modules:
Config auto-discovery (app/modules/config.py):
- Modules can have config.py with Pydantic Settings
- Environment variables prefixed with MODULE_NAME_
- Auto-discovered via get_module_config()
Migrations auto-discovery:
- Each module has migrations/versions/ directory
- Alembic discovers module migrations automatically
- Naming convention: {module}_{seq}_{description}.py
New architecture rules (MOD-013 to MOD-015):
- MOD-013: config.py should export config/config_class
- MOD-014: Migrations must follow naming convention
- MOD-015: Migrations directory must have __init__.py
Created for all 11 self-contained modules:
- config.py placeholder files
- migrations/ directories with __init__.py files
Added core and tenancy module definitions for completeness.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 4 of module migration plan:
- Add ScheduledTask dataclass for declaring Celery Beat tasks
- Add tasks_path and scheduled_tasks fields to ModuleDefinition
- Create ModuleTask base class with database session management
- Create task discovery utilities (discover_module_tasks, build_beat_schedule)
- Update celery_config.py to discover and register module tasks
- Maintain backward compatibility with legacy task modules
Modules can now define tasks in their tasks/ directory and scheduled
tasks in their definition. The infrastructure supports gradual migration
of existing tasks from app/tasks/ to their respective modules.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
