orion/docs/architecture/module-system.md

Module System Architecture

The Wizamart platform uses a plug-and-play modular architecture where modules are fully self-contained and automatically discovered. Simply create a module directory with the required structure, and the framework handles registration, routing, and resource loading automatically.

Key Features

• Auto-Discovery: Modules are automatically discovered from app/modules/*/definition.py
• Zero Configuration: No changes to main.py, registry.py, or other framework files needed
• Self-Contained: Each module owns its routes, services, models, templates, and translations
• Hot-Pluggable: Add or remove modules by simply adding/removing directories

Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        FRAMEWORK LAYER                               │
│  (Infrastructure that modules depend on - not modules themselves)    │
│                                                                      │
│  Config │ Database │ Auth │ Permissions │ Observability │ Celery    │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    AUTO-DISCOVERED MODULE LAYER                      │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │              CORE MODULES (Always Enabled)                   │    │
│  │     core  │  tenancy  │  cms  │  customers                  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │           OPTIONAL MODULES (Per-Platform)                    │    │
│  │  payments │ billing │ inventory │ orders │ marketplace │ ...│    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │            INTERNAL MODULES (Admin Only)                     │    │
│  │              dev-tools  │  monitoring                        │    │
│  └─────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘

Auto-Discovery System

All module components are automatically discovered by the framework:

Component	Discovery Location	Auto-Loaded By
Registry	*/definition.py	app/modules/discovery.py
Configuration	*/config.py	app/modules/config.py
API Routes	*/routes/api/*.py	app/modules/routes.py
Page Routes	*/routes/pages/*.py	app/modules/routes.py
Tasks	*/tasks/__init__.py	app/modules/tasks.py
Templates	*/templates/	app/templates_config.py
Static Files	*/static/	main.py
Locales	*/locales/*.json	app/utils/i18n.py
Migrations	*/migrations/versions/	app/modules/migrations.py

Creating a New Module (Zero Framework Changes)

# 1. Create module directory
mkdir -p app/modules/mymodule/{routes/{api,pages},services,models,schemas,templates/mymodule/vendor,static/vendor/js,locales,tasks}

# 2. Create required files
touch app/modules/mymodule/__init__.py
touch app/modules/mymodule/definition.py
touch app/modules/mymodule/exceptions.py

# 3. That's it! The framework auto-discovers and registers everything.

Three-Tier Classification

Core Modules (4)

Core modules are always enabled and cannot be disabled. They provide fundamental platform functionality.

Module	Description	Key Features
core	Dashboard, settings, profile	Basic platform operation
tenancy	Platform, company, vendor, admin user management	Multi-tenant infrastructure
cms	Content pages, media library, themes	Content management
customers	Customer database, profiles, segmentation	Customer data management

Optional Modules (10)

Optional modules can be enabled or disabled per platform. They provide additional functionality that may not be needed by all platforms.

Module	Dependencies	Description
cart	-	Shopping cart management, session-based carts
catalog	-	Customer-facing product browsing
checkout	cart, orders, payments	Cart-to-order conversion, checkout flow
payments	-	Payment gateway integrations (Stripe, PayPal, etc.)
billing	payments	Platform subscriptions, vendor invoices
inventory	-	Stock management, locations
orders	payments	Order management, customer checkout
marketplace	inventory	Letzshop integration
analytics	-	Reports, dashboards
messaging	-	Messages, notifications

Internal Modules (2)

Internal modules are admin-only tools not exposed to customers or vendors.

Module	Description
dev-tools	Component library, icon browser
monitoring	Logs, background tasks, Flower, Grafana integration

Self-Contained Module Structure

Every module follows this standardized structure:

app/modules/analytics/
├── __init__.py              # Module package marker
├── definition.py            # ModuleDefinition (REQUIRED for auto-discovery)
├── config.py                # Environment config (auto-discovered)
├── exceptions.py            # Module-specific exceptions
├── routes/
│   ├── __init__.py
│   ├── api/                 # API endpoints (auto-discovered)
│   │   ├── __init__.py
│   │   ├── admin.py         # Must export: router = APIRouter()
│   │   └── vendor.py        # Must export: router = APIRouter()
│   └── pages/               # HTML page routes (auto-discovered)
│       ├── __init__.py
│       └── vendor.py        # Must export: router = APIRouter()
├── services/
│   ├── __init__.py
│   └── stats_service.py
├── models/
│   ├── __init__.py
│   └── report.py
├── schemas/
│   ├── __init__.py
│   └── stats.py
├── templates/               # Auto-discovered by Jinja2
│   └── analytics/
│       └── vendor/
│           └── analytics.html
├── static/                  # Auto-mounted at /static/modules/analytics/
│   ├── admin/js/            # Admin-facing JS for this module
│   ├── vendor/js/           # Vendor-facing JS for this module
│   │   └── analytics.js
│   └── shared/js/           # Shared JS (used by both admin and vendor)
├── locales/                 # Auto-loaded translations
│   ├── en.json
│   ├── de.json
│   ├── fr.json
│   └── lu.json
├── tasks/                   # Auto-discovered by Celery
│   ├── __init__.py          # REQUIRED for Celery discovery
│   └── reports.py
└── migrations/              # Auto-discovered by Alembic
    ├── __init__.py          # REQUIRED for discovery
    └── versions/
        ├── __init__.py      # REQUIRED for discovery
        └── analytics_001_create_reports.py

Module Definition

Each module must have a definition.py with a ModuleDefinition instance:

# app/modules/analytics/definition.py
from app.modules.base import ModuleDefinition
from models.database.admin_menu_config import FrontendType

analytics_module = ModuleDefinition(
    # Identity
    code="analytics",
    name="Analytics & Reporting",
    description="Dashboard analytics, custom reports, and data exports.",
    version="1.0.0",

    # Classification (determines tier)
    is_core=False,      # Set True for core modules
    is_internal=False,  # Set True for admin-only modules

    # Dependencies
    requires=[],  # List other module codes this depends on

    # Features (for tier-based gating)
    features=[
        "basic_reports",
        "analytics_dashboard",
        "custom_reports",
    ],

    # Menu items per frontend
    menu_items={
        FrontendType.ADMIN: [],  # Analytics uses dashboard
        FrontendType.VENDOR: ["analytics"],
    },

    # Self-contained module configuration
    is_self_contained=True,
    services_path="app.modules.analytics.services",
    models_path="app.modules.analytics.models",
    schemas_path="app.modules.analytics.schemas",
    exceptions_path="app.modules.analytics.exceptions",
    templates_path="templates",
    locales_path="locales",
)

ModuleDefinition Fields

Field	Type	Description
code	str	Unique identifier (e.g., "billing")
name	str	Display name
description	str	What the module provides
version	str	Semantic version (default: "1.0.0")
requires	list[str]	Module codes this depends on
features	list[str]	Feature codes for tier gating
menu_items	dict	Menu items per frontend type
is_core	bool	Cannot be disabled if True
is_internal	bool	Admin-only if True
is_self_contained	bool	Uses self-contained structure

Route Auto-Discovery

Routes in routes/api/ and routes/pages/ are automatically discovered and registered.

API Routes (routes/api/vendor.py)

# app/modules/analytics/routes/api/vendor.py
from fastapi import APIRouter, Depends
from app.api.deps import get_current_vendor_api, get_db

router = APIRouter()  # MUST be named 'router' for auto-discovery

@router.get("")
def get_analytics(
    current_user = Depends(get_current_vendor_api),
    db = Depends(get_db),
):
    """Get vendor analytics."""
    pass

Auto-registered at: /api/v1/vendor/analytics

Page Routes (routes/pages/vendor.py)

# app/modules/analytics/routes/pages/vendor.py
from fastapi import APIRouter, Depends, Request
from fastapi.responses import HTMLResponse

router = APIRouter()  # MUST be named 'router' for auto-discovery

@router.get("/{vendor_code}/analytics", response_class=HTMLResponse)
async def analytics_page(request: Request, vendor_code: str):
    """Render analytics page."""
    pass

Auto-registered at: /vendor/{vendor_code}/analytics

Framework Layer

The Framework Layer provides infrastructure that modules depend on. These are not modules - they're always available and cannot be disabled.

Component	Location	Purpose
Config	app/core/config.py	Settings management
Database	app/core/database.py	SQLAlchemy sessions
Logging	app/core/logging.py	Structured logging
Permissions	app/core/permissions.py	RBAC definitions
Feature Gate	app/core/feature_gate.py	Tier-based access
Celery	app/core/celery_config.py	Task queue
Observability	app/core/observability.py	Health checks, metrics, Sentry
Auth Middleware	middleware/auth.py	JWT authentication
Context Middleware	middleware/platform_context.py	Multi-tenancy
Dependencies	app/api/deps.py	FastAPI DI
Base Exceptions	app/exceptions/base.py	Exception hierarchy

Module Dependencies

Modules can depend on other modules. When enabling a module, its dependencies are automatically enabled.

                         payments
                        ↙        ↘
                   billing        orders ←──┐
                                     ↑      │
              inventory              │      │
                  ↓                cart     │
             marketplace               ↘    │
                                      checkout

Dependency Rules:

1. Core modules cannot depend on optional modules
2. Enabling a module auto-enables its dependencies
3. Disabling a module auto-disables modules that depend on it
4. Circular dependencies are not allowed

Module Registry

The registry auto-discovers all modules:

from app.modules.registry import (
    MODULES,           # All modules (auto-discovered)
    CORE_MODULES,      # Core only
    OPTIONAL_MODULES,  # Optional only
    INTERNAL_MODULES,  # Internal only
    get_module,
    get_core_module_codes,
    get_module_tier,
)

# Get a specific module
billing = get_module("billing")

# Check module tier
tier = get_module_tier("billing")  # Returns "optional"

# Get all core module codes
core_codes = get_core_module_codes()  # {"core", "tenancy", "cms", "customers"}

Module Service

The ModuleService manages module enablement per platform:

from app.modules.service import module_service

# Check if module is enabled
if module_service.is_module_enabled(db, platform_id, "billing"):
    pass

# Get all enabled modules for a platform
modules = module_service.get_platform_modules(db, platform_id)

# Enable a module (auto-enables dependencies)
module_service.enable_module(db, platform_id, "billing", user_id=current_user.id)

# Disable a module (auto-disables dependents)
module_service.disable_module(db, platform_id, "billing", user_id=current_user.id)

Module Static Files

Each module can have its own static assets (JavaScript, CSS, images) in the static/ directory. These are automatically mounted at /static/modules/{module_name}/.

Static File Structure

app/modules/{module}/static/
├── admin/js/           # Admin pages for this module
├── vendor/js/          # Vendor pages for this module
├── shared/js/          # Shared across admin/vendor (e.g., feature-store.js)
└── shop/js/            # Shop pages (if module has storefront UI)

Referencing in Templates

Use the {module}_static URL name:

<!-- Module-specific JS -->
<script src="{{ url_for('orders_static', path='vendor/js/orders.js') }}"></script>
<script src="{{ url_for('billing_static', path='shared/js/feature-store.js') }}"></script>

Module vs. Platform Static Files

Put in Module	Put in Platform (static/)
Module-specific features	Platform-level admin (dashboard, login, platforms, vendors)
Order management → orders module	Vendor core (profile, settings, team)
Product catalog → catalog module	Shared utilities (api-client, utils, icons)
Billing/subscriptions → billing module	Admin user management
Analytics dashboards → analytics module	Platform user management

Key distinction: Platform users (admin-users.js, users.js) manage internal platform access. Shop customers (customers.js in customers module) are end-users who purchase from vendors.

See Frontend Structure for detailed JS file organization.

Module Configuration

Modules can have environment-based configuration using Pydantic Settings. The config.py file is auto-discovered by app/modules/config.py.

# app/modules/marketplace/config.py
from pydantic import Field
from pydantic_settings import BaseSettings

class MarketplaceConfig(BaseSettings):
    """Configuration for marketplace module."""

    # Settings loaded from env vars with MARKETPLACE_ prefix
    api_timeout: int = Field(default=30, description="API timeout in seconds")
    batch_size: int = Field(default=100, description="Import batch size")
    max_retries: int = Field(default=3, description="Max retry attempts")

    model_config = {"env_prefix": "MARKETPLACE_"}

# Export for auto-discovery
config_class = MarketplaceConfig
config = MarketplaceConfig()

Usage:

# Direct import
from app.modules.marketplace.config import config
timeout = config.api_timeout

# Via discovery
from app.modules.config import get_module_config
config = get_module_config("marketplace")

Environment variables:

MARKETPLACE_API_TIMEOUT=60
MARKETPLACE_BATCH_SIZE=500

Module Migrations

Each module owns its database migrations in the migrations/versions/ directory. Alembic auto-discovers these via app/modules/migrations.py.

Migration Structure

app/modules/cms/migrations/
├── __init__.py           # REQUIRED for discovery
└── versions/
    ├── __init__.py       # REQUIRED for discovery
    ├── cms_001_create_content_pages.py
    ├── cms_002_add_sections.py
    └── cms_003_add_media_library.py

Naming Convention

{module_code}_{sequence}_{description}.py

Migration Template

# app/modules/cms/migrations/versions/cms_001_create_content_pages.py
"""Create content_pages table.

Revision ID: cms_001
Create Date: 2026-01-28
"""
from alembic import op
import sqlalchemy as sa

revision = "cms_001"
down_revision = None
branch_labels = ("cms",)  # Module-specific branch

def upgrade() -> None:
    op.create_table(
        "content_pages",
        sa.Column("id", sa.Integer(), primary_key=True),
        sa.Column("vendor_id", sa.Integer(), sa.ForeignKey("vendors.id")),
        sa.Column("slug", sa.String(100), nullable=False),
        sa.Column("title", sa.String(200), nullable=False),
    )

def downgrade() -> None:
    op.drop_table("content_pages")

Running Migrations

Module migrations are automatically discovered:

# Run all migrations (core + modules)
alembic upgrade head

# View migration history
alembic history

Current State

Currently, all migrations reside in central alembic/versions/. The module-specific directories are in place for:

• New modules: Should create migrations in their own migrations/versions/
• Future reorganization: Existing migrations will be moved to modules pre-production

Entity Auto-Discovery Reference

This section details the auto-discovery requirements for each entity type. All entities must be in modules - legacy locations are deprecated and will trigger architecture validation errors.

Routes

Routes define API and page endpoints. They are auto-discovered from module directories.

Type	Location	Discovery	Router Name
Admin API	routes/api/admin.py	app/modules/routes.py	admin_router
Vendor API	routes/api/vendor.py	app/modules/routes.py	vendor_router
Storefront API	routes/api/storefront.py	app/modules/routes.py	router
Admin Pages	routes/pages/admin.py	app/modules/routes.py	admin_router
Vendor Pages	routes/pages/vendor.py	app/modules/routes.py	vendor_router

Structure:

app/modules/{module}/routes/
├── __init__.py
├── api/
│   ├── __init__.py
│   ├── admin.py           # Must export admin_router
│   ├── vendor.py          # Must export vendor_router
│   ├── storefront.py      # Must export router (public storefront)
│   └── admin_{feature}.py # Sub-routers aggregated in admin.py
└── pages/
    ├── __init__.py
    └── vendor.py          # Must export vendor_router

Example - Aggregating Sub-Routers:

# app/modules/billing/routes/api/vendor.py
from fastapi import APIRouter, Depends
from app.api.deps import require_module_access

vendor_router = APIRouter(
    prefix="/billing",
    dependencies=[Depends(require_module_access("billing"))],
)

# Aggregate sub-routers
from .vendor_checkout import vendor_checkout_router
from .vendor_usage import vendor_usage_router

vendor_router.include_router(vendor_checkout_router)
vendor_router.include_router(vendor_usage_router)

Legacy Locations (DEPRECATED - will cause errors):

• app/api/v1/vendor/*.py - Move to module routes/api/vendor.py
• app/api/v1/admin/*.py - Move to module routes/api/admin.py

---

Services

Services contain business logic. They are not auto-discovered but should be in modules for organization.

Location	Import Pattern
services/*.py	from app.modules.{module}.services import service_name
services/__init__.py	Re-exports all public services

Structure:

app/modules/{module}/services/
├── __init__.py             # Re-exports: from .order_service import order_service
├── order_service.py        # OrderService class + order_service singleton
└── fulfillment_service.py  # Related services

Example:

# app/modules/orders/services/order_service.py
from sqlalchemy.orm import Session
from app.modules.orders.models import Order

class OrderService:
    def get_order(self, db: Session, order_id: int) -> Order:
        return db.query(Order).filter(Order.id == order_id).first()

order_service = OrderService()

# app/modules/orders/services/__init__.py
from .order_service import order_service, OrderService

__all__ = ["order_service", "OrderService"]

Legacy Locations (DEPRECATED - will cause errors):

• app/services/*.py - Move to module services/
• app/services/{module}/ - Move to app/modules/{module}/services/

---

Models

Database models (SQLAlchemy). Currently in models/database/, migrating to modules.

Location	Base Class	Discovery
models/*.py	Base from models.base	Alembic autogenerate

Structure:

app/modules/{module}/models/
├── __init__.py          # Re-exports: from .order import Order, OrderItem
├── order.py             # Order model
└── order_item.py        # Related models

Example:

# app/modules/orders/models/order.py
from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship
from models.base import Base, TimestampMixin

class Order(Base, TimestampMixin):
    __tablename__ = "orders"

    id = Column(Integer, primary_key=True)
    vendor_id = Column(Integer, ForeignKey("vendors.id"), nullable=False)
    status = Column(String(50), default="pending")
    items = relationship("OrderItem", back_populates="order")

Legacy Locations (being migrated):

• models/database/*.py - Core models remain here, domain models move to modules

---

Schemas

Pydantic schemas for request/response validation.

Location	Base Class	Usage
schemas/*.py	BaseModel from Pydantic	API routes, validation

Structure:

app/modules/{module}/schemas/
├── __init__.py           # Re-exports all schemas
├── order.py              # Order request/response schemas
└── order_item.py         # Related schemas

Example:

# app/modules/orders/schemas/order.py
from pydantic import BaseModel
from datetime import datetime

class OrderResponse(BaseModel):
    id: int
    vendor_id: int
    status: str
    created_at: datetime

    class Config:
        from_attributes = True

class OrderCreateRequest(BaseModel):
    customer_id: int
    items: list[OrderItemRequest]

Legacy Locations (DEPRECATED - will cause errors):

• models/schema/*.py - Move to module schemas/

---

Tasks (Celery)

Background tasks are auto-discovered by Celery from module tasks/ directories.

Location	Discovery	Registration
tasks/*.py	app/modules/tasks.py	Celery autodiscover

Structure:

app/modules/{module}/tasks/
├── __init__.py           # REQUIRED - imports task functions
├── import_tasks.py       # Task definitions
└── export_tasks.py       # Related tasks

Example:

# app/modules/marketplace/tasks/import_tasks.py
from celery import shared_task
from app.core.database import SessionLocal

@shared_task(bind=True)
def process_import(self, job_id: int, vendor_id: int):
    db = SessionLocal()
    try:
        # Process import
        pass
    finally:
        db.close()

# app/modules/marketplace/tasks/__init__.py
from .import_tasks import process_import
from .export_tasks import export_products

__all__ = ["process_import", "export_products"]

Legacy Locations (DEPRECATED - will cause errors):

• app/tasks/*.py - Move to module tasks/

---

Exceptions

Module-specific exceptions inherit from WizamartException.

Location	Base Class	Usage
exceptions.py	WizamartException	Domain errors

Structure:

app/modules/{module}/
└── exceptions.py         # All module exceptions

Example:

# app/modules/orders/exceptions.py
from app.exceptions import WizamartException

class OrderException(WizamartException):
    """Base exception for orders module."""
    pass

class OrderNotFoundError(OrderException):
    """Order not found."""
    def __init__(self, order_id: int):
        super().__init__(f"Order {order_id} not found")
        self.order_id = order_id

class OrderAlreadyFulfilledError(OrderException):
    """Order has already been fulfilled."""
    pass

---

Templates

Jinja2 templates are auto-discovered from module templates/ directories. The template loader searches app/templates/ first (for shared templates), then each module's templates/ directory.

Location	URL Pattern	Discovery
templates/{module}/vendor/*.html	/vendor/{vendor}/...	Jinja2 loader
templates/{module}/admin/*.html	/admin/...	Jinja2 loader
templates/{module}/storefront/*.html	/storefront/...	Jinja2 loader
templates/{module}/public/*.html	/... (platform pages)	Jinja2 loader

Module Template Structure:

app/modules/{module}/templates/
└── {module}/
    ├── admin/
    │   ├── list.html
    │   └── partials/          # Module-specific partials
    │       └── my-partial.html
    ├── vendor/
    │   ├── index.html
    │   └── detail.html
    ├── storefront/            # Customer-facing shop pages
    │   └── products.html
    └── public/                # Platform marketing pages
        └── pricing.html

Template Reference:

# In route
return templates.TemplateResponse(
    request=request,
    name="{module}/vendor/index.html",
    context={"items": items}
)

Shared Templates (in app/templates/):

Some templates remain in app/templates/ because they are used across all modules:

Directory	Contents	Purpose
admin/base.html	Admin layout	Parent template all admin pages extend
vendor/base.html	Vendor layout	Parent template all vendor pages extend
storefront/base.html	Shop layout	Parent template all storefront pages extend
platform/base.html	Public layout	Parent template all public pages extend
admin/errors/	Error pages	HTTP error templates (404, 500, etc.)
vendor/errors/	Error pages	HTTP error templates for vendor
storefront/errors/	Error pages	HTTP error templates for storefront
admin/partials/	Shared partials	Header, sidebar used across admin
vendor/partials/	Shared partials	Header, sidebar used across vendor
shared/macros/	Jinja2 macros	Reusable UI components (buttons, forms, tables)
shared/includes/	Includes	Common HTML snippets
invoices/	PDF templates	Invoice PDF generation

These shared templates provide the "framework" that module templates build upon. Module templates extend base layouts and import shared macros.

---

Static Files

JavaScript, CSS, and images are auto-mounted from module static/ directories.

Location	URL	Discovery
static/vendor/js/*.js	/static/modules/{module}/vendor/js/*.js	main.py
static/admin/js/*.js	/static/modules/{module}/admin/js/*.js	main.py

Structure:

app/modules/{module}/static/
├── vendor/js/
│   └── {module}.js
├── admin/js/
│   └── {module}.js
└── shared/js/
    └── common.js

Template Reference:

<script src="{{ url_for('{module}_static', path='vendor/js/{module}.js') }}"></script>

---

Locales (i18n)

Translation files are auto-discovered from module locales/ directories.

Location	Format	Discovery
locales/*.json	JSON key-value	app/utils/i18n.py

Structure:

app/modules/{module}/locales/
├── en.json
├── de.json
├── fr.json
└── lb.json

Example:

{
  "orders.title": "Orders",
  "orders.status.pending": "Pending",
  "orders.status.fulfilled": "Fulfilled"
}

Usage:

from app.utils.i18n import t

message = t("orders.title", locale="en")  # "Orders"

---

Configuration

Module-specific environment configuration.

Location	Base Class	Discovery
config.py	BaseSettings	app/modules/config.py

Example:

# app/modules/marketplace/config.py
from pydantic_settings import BaseSettings

class MarketplaceConfig(BaseSettings):
    api_timeout: int = 30
    batch_size: int = 100

    model_config = {"env_prefix": "MARKETPLACE_"}

config = MarketplaceConfig()

Environment Variables:

MARKETPLACE_API_TIMEOUT=60
MARKETPLACE_BATCH_SIZE=500

Architecture Validation Rules

The architecture validator (scripts/validate_architecture.py) enforces module structure:

Rule	Severity	Description
MOD-001	ERROR	Self-contained modules must have required directories
MOD-002	WARNING	Services must contain actual code, not re-exports
MOD-003	WARNING	Schemas must contain actual code, not re-exports
MOD-004	WARNING	Routes must import from module, not legacy locations
MOD-005	WARNING	Modules with UI must have templates and static
MOD-006	INFO	Modules should have locales for i18n
MOD-007	ERROR	Definition paths must match directory structure
MOD-008	WARNING	Self-contained modules must have exceptions.py
MOD-009	ERROR	Modules must have definition.py for auto-discovery
MOD-010	WARNING	Route files must export router variable
MOD-011	WARNING	Tasks directory must have __init__.py
MOD-012	INFO	Locales should have all language files
MOD-013	INFO	config.py should export config or config_class
MOD-014	WARNING	Migrations must follow naming convention
MOD-015	WARNING	Migrations directory must have __init__.py files
MOD-016	ERROR	Routes must be in modules, not app/api/v1/
MOD-017	ERROR	Services must be in modules, not app/services/
MOD-018	ERROR	Tasks must be in modules, not app/tasks/
MOD-019	ERROR	Schemas must be in modules, not models/schema/

Run validation:

python scripts/validate_architecture.py

Best Practices

Do

• Keep modules focused on a single domain
• Use requires for hard dependencies
• Provide health_check for critical modules
• Use events for cross-module communication
• Follow the standard directory structure
• Export router variable in route files
• Include all supported languages in locales

Don't

• Create circular dependencies
• Make core modules depend on optional modules
• Put framework-level code in modules
• Skip migration naming conventions
• Forget __init__.py in tasks directory
• Manually register modules in registry.py (use auto-discovery)

Related Documentation

• Creating Modules - Step-by-step guide
• Menu Management - Sidebar configuration
• Observability - Health checks integration
• Feature Gating - Tier-based access