orion/docs/proposals/SESSION_NOTE_2026-01-28_module-config-migrations.md

Session Note: Module Config & Migrations Infrastructure

Date: 2026-01-28 Focus: Self-contained module configuration and migrations auto-discovery

Summary

Completed the infrastructure for fully self-contained modules with config and migrations auto-discovery. All modules now have placeholder files ready for the final migration phase.

What Was Done

1. Module Config Auto-Discovery

Created app/modules/config.py that auto-discovers module configurations:

from app.modules.config import get_module_config

marketplace_config = get_module_config("marketplace")

Each module now has a config.py placeholder:

# app/modules/marketplace/config.py
class MarketplaceConfig(BaseSettings):
    model_config = {"env_prefix": "MARKETPLACE_"}

config = MarketplaceConfig()

2. Module Migrations Directories

Created migrations/versions/ directories for all 11 self-contained modules:

• analytics, billing, cms, customers, dev_tools
• inventory, marketplace, messaging, monitoring, orders, payments

Each with required __init__.py files for Alembic discovery.

3. New Architecture Rules

Added rules MOD-013 to MOD-015:

Rule	Description
MOD-013	config.py should export config or config_class
MOD-014	Migrations must follow naming convention {module}_{seq}_{desc}.py
MOD-015	Migrations directory must have __init__.py files

4. Module Migration Commits

Committed all pending module migration work:

Commit	Description
2466dfd	feat: add module config and migrations auto-discovery infrastructure
bd2c99a	feat: complete analytics module self-containment
f79e67d	feat: complete billing module self-containment
b74d134	feat: complete marketplace module self-containment
705d336	feat: add self-contained structure to remaining modules
d987274	feat: complete dev_tools module self-containment
37cf74c	refactor: update registry and main.py for module auto-discovery
3ffa337	refactor: convert legacy models/schemas to re-exports
bf871dc	refactor: convert legacy services/tasks to re-exports
fbcf079	chore: update API routers, validation, and docs

5. Documentation Updates

• docs/architecture/module-system.md - Added Module Configuration and Module Migrations sections
• docs/development/creating-modules.md - Added config.py pattern, updated migrations docs

Current Module Status

Module	definition.py	config.py	migrations/	routes/api/	routes/pages/	locales/	Status
analytics	✅	✅	✅	✅	✅	✅	Complete
billing	✅	✅	✅	✅	⚠️	✅	Needs pages
cms	✅	✅	✅	✅	✅	-	Complete
customers	✅	✅	✅	⚠️	⚠️	-	Needs routes
dev_tools	✅	✅	✅	✅	-	-	Complete
inventory	✅	✅	✅	⚠️	⚠️	-	Needs routes
marketplace	✅	✅	✅	✅	⚠️	✅	Needs pages
messaging	✅	✅	✅	⚠️	⚠️	-	Needs routes
monitoring	✅	✅	✅	⚠️	⚠️	-	Needs routes
orders	✅	✅	✅	⚠️	⚠️	-	Needs routes
payments	✅	✅	✅	⚠️	⚠️	-	Needs routes
core	✅	-	-	-	-	-	Minimal
tenancy	✅	-	-	-	-	-	Minimal

Decisions Made

1. Config is environment-based: Each module uses Pydantic Settings with {MODULE}_ prefix
2. Migrations stay central for now: Existing migrations remain in alembic/versions/, module directories are for future changes
3. Migration reorganization deferred: Will move existing migrations to modules before production
4. Legacy files become re-exports: Original files in models/database/, models/schema/, app/services/ re-export from modules

Tomorrow's Tasks

Phase 1: Module Alignment Audit

Run architecture validator and fix all modules to comply with rules:

python scripts/validate_architecture.py

Check each module for:

• MOD-001: Required directories exist
• MOD-002: Services contain actual code (not re-exports)
• MOD-003: Schemas contain actual code (not re-exports)
• MOD-004: Routes import from module, not legacy
• MOD-005: Templates and static exist for UI modules
• MOD-008: exceptions.py exists
• MOD-010: Routes export router variable
• MOD-011: Tasks have __init__.py

Phase 2: Complete Module Routes Migration

Move remaining routes to self-contained structure:

1. customers - Move routes from app/api/v1/*/customers.py
2. inventory - Move routes from app/api/v1/*/inventory.py
3. messaging - Move routes from app/api/v1/*/messages.py
4. monitoring - Move routes from app/api/v1/admin/monitoring.py
5. orders - Move routes from app/api/v1/*/orders.py
6. payments - Move routes from app/api/v1/*/payments.py

Phase 3: Migration Reorganization (Pre-Production)

Move existing migrations to module-specific directories:

1. Identify which tables belong to which module
2. Create baseline migrations in module directories
3. Test migration chain works correctly
4. Remove/reorganize central migrations

Phase 4: Validation & Testing

1. Run full architecture validation
2. Test all routes are accessible
3. Test module enable/disable functionality
4. Verify Alembic discovers all migrations

Files Changed

New Files

• app/modules/config.py - Config auto-discovery
• app/modules/*/config.py - Module config placeholders (11 files)
• app/modules/*/migrations/__init__.py - Migration package markers (11 modules)
• app/modules/*/migrations/versions/__init__.py - Version package markers (11 modules)
• .architecture-rules/module.yaml - Module validation rules

Modified Files

• docs/architecture/module-system.md - Added config/migrations sections
• docs/development/creating-modules.md - Added config pattern, updated migrations

Related Documentation

• Module System Architecture
• Creating Modules Guide
• Module Migration Plan