orion/docs/archive/SESSION_NOTE_2026-01-26_self-contained-modules.md

# Session Note: Self-Contained Module Architecture

**Date:** 2026-01-26
**Plan Reference:** `docs/proposals/TEMP.md` (now this file)
**Previous Session:** `docs/proposals/SESSION_NOTE_2026-01-25_modular-platform-architecture.md`

---

## Summary

Transformed thin module wrappers into fully self-contained modules, using CMS as the pilot. Each self-contained module is an autonomous unit with its own services, models, schemas, templates, exceptions, and locales.

---

## Completed Phases

### Phase 1: Foundation

Created infrastructure for self-contained modules:

| File | Purpose |
|------|---------|
| `app/modules/contracts/` | Protocol definitions for cross-module dependencies |
| `app/templates_config.py` | Multi-directory template loader for module templates |
| `app/modules/base.py` | Enhanced ModuleDefinition with self-contained flags |

**Git tag:** `pre-modular-architecture`

### Phase 2: CMS Pilot (Full Self-Contained Module)

Migrated CMS to be the first fully self-contained module:

| Component | Location | Status |
|-----------|----------|--------|
| Services | `app/modules/cms/services/content_page_service.py` | ✅ |
| Models | `app/modules/cms/models/content_page.py` | ✅ |
| Schemas | `app/modules/cms/schemas/content_page.py` | ✅ |
| Exceptions | `app/modules/cms/exceptions.py` | ✅ |
| Locales | `app/modules/cms/locales/{en,fr,de,lb}.json` | ✅ |
| Templates | `app/modules/cms/templates/cms/{admin,store}/` | ✅ |
| Static | `app/modules/cms/static/{admin,store}/js/` | ✅ |
| Routes | `app/modules/cms/routes/{api,pages}/` | ✅ |

---

## CMS Module Structure

```
app/modules/cms/
├── __init__.py              # Lazy getter to avoid circular imports
├── definition.py            # ModuleDefinition with self-contained config
├── exceptions.py            # CMSException, ContentPageNotFoundError
├── locales/
│   ├── en.json
│   ├── fr.json
│   ├── de.json
│   └── lb.json
├── models/
│   ├── __init__.py          # Exports: ContentPage, MediaFile, ProductMedia
│   └── content_page.py      # ContentPage model (canonical location)
├── routes/
│   ├── __init__.py
│   ├── admin.py             # Admin router wrapper
│   ├── store.py            # Store router wrapper
│   ├── api/
│   │   ├── admin.py         # Admin API endpoints
│   │   ├── store.py        # Store API endpoints
│   │   └── shop.py          # Shop/public API endpoints
│   └── pages/
│       ├── admin.py         # Admin page routes
│       └── store.py        # Store page routes
├── schemas/
│   ├── __init__.py
│   └── content_page.py      # Pydantic schemas
├── services/
│   ├── __init__.py
│   └── content_page_service.py
├── static/
│   ├── admin/js/
│   │   ├── content-pages.js
│   │   └── content-page-edit.js
│   └── store/js/
│       ├── content-pages.js
│       └── content-page-edit.js
└── templates/
    └── cms/
        ├── admin/
        │   ├── content-pages.html
        │   └── content-page-edit.html
        └── store/
            ├── content-pages.html
            └── content-page-edit.html
```

---

## Key Patterns Established

### 1. Module-First Models

Models live in module folders and are dynamically loaded at startup:

```python
# app/modules/cms/models/content_page.py (canonical location)
from app.core.database import Base

class ContentPage(Base):
    __tablename__ = "content_pages"
    ...

# models/database/__init__.py (dynamic loader)
def _discover_module_models():
    for module_dir in sorted(modules_dir.iterdir()):
        models_init = module_dir / "models" / "__init__.py"
        if models_init.exists():
            importlib.import_module(f"app.modules.{module_dir.name}.models")

_discover_module_models()
```

### 2. Shared Templates Instance

Route files must import from `app.templates_config`:

```python
# CORRECT
from app.templates_config import templates

# WRONG - creates local instance without module loaders
templates = Jinja2Templates(directory="app/templates")
```

### 3. Template Namespacing

Module templates use namespace prefix to avoid collisions:

```python
# Module templates at: app/modules/cms/templates/cms/admin/content-pages.html
# Rendered as:
templates.TemplateResponse("cms/admin/content-pages.html", ...)
```

### 4. Import Pattern

All code should import from module:

```python
# Models
from app.modules.cms.models import ContentPage

# Services
from app.modules.cms.services import content_page_service

# Exceptions
from app.modules.cms.exceptions import ContentPageNotFoundException
```

### 5. Lazy Imports for Circular Import Prevention

```python
# app/modules/cms/__init__.py
def get_cms_module():
    """Lazy getter for cms_module to avoid circular imports."""
    from app.modules.cms.definition import cms_module
    return cms_module
```

---

## Decisions Made

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Pilot Module | CMS | Simplest, minimal dependencies |
| Cross-Module Pattern | Protocol pattern | Type-safe interfaces |
| Timeline | Incremental | Alongside feature work |
| Backwards Compatibility | No shims | Pre-launch, can delete old files |
| Template Namespace | `{module}/admin/`, `{module}/store/` | Prevent collisions |

---

## Verification Completed

- [x] `python -c "from main import app"` succeeds
- [x] ContentPage model in `app/modules/cms/models/content_page.py`
- [x] Dynamic model loader in `models/database/__init__.py`
- [x] `content_pages` table in Base.metadata (67 total tables)
- [x] Template files in correct locations
- [x] Route files use shared templates instance
- [x] Admin CMS pages render correctly
- [x] Store CMS pages render correctly

---

## What Stays in Core vs Moves to Modules

### Core (Stays in Place)

| Component | Location | Reason |
|-----------|----------|--------|
| User, Store, Merchant, Platform models | `models/database/` | Foundational entities |
| Auth service | `app/services/` | Cross-cutting concern |
| Storage, Cache, Email services | `app/services/` | Infrastructure utilities |
| Base exceptions | `app/exceptions/` | Shared error types |
| Shared macros, partials | `app/templates/shared/` | Reusable UI components |
| API dependencies | `app/api/deps.py` | Auth, module access checks |

### Modules (Move to Self-Contained)

| Module | Services | Models | Status |
|--------|----------|--------|--------|
| cms | content_page, media | content_page, media | ✅ Complete |
| billing | billing, stripe, invoice, subscription | subscription, invoice, payment | Pending |
| inventory | inventory, inventory_transaction | inventory, inventory_transaction | Pending |
| orders | order, cart, order_item_exception | order, order_item_exception | Pending |
| marketplace | marketplace, marketplace_product, letzshop_export | marketplace_product, import_job | Pending |
| customers | customer, customer_address | customer | Pending |
| messaging | messaging, notification | message, notification | Pending |
| analytics | stats, capacity_forecast | (uses other models) | Pending |
| monitoring | background_tasks, test_runner, log | test_run, architecture_scan | Pending |

---

## Pending/Next Steps

### Phase 3: Simple Modules Migration

- [ ] Migrate analytics module
- [ ] Migrate monitoring module
- [ ] Migrate messaging module
- [ ] Migrate customers module

### Phase 4: Complex Modules Migration

- [ ] Migrate billing (with Stripe integration)
- [ ] Migrate inventory
- [ ] Migrate orders
- [ ] Migrate marketplace

### Phase 5: Cleanup

- [ ] Remove deprecated shims (if any created)
- [ ] Update all imports across codebase
- [ ] Delete `app/platforms/` directory
- [ ] Update architecture documentation

### Other Pending Items

- [ ] Wire up store module routers to `app/api/v1/store/__init__.py`
- [ ] PlatformModule database table (optional - for audit trail)
- [ ] Module-specific configuration UI
- [ ] Integration tests for `/api/v1/admin/modules/*` endpoints

---

## Git Commits

```
ec4ec04 feat: complete CMS as fully autonomous self-contained module
0b65864 fix: resolve circular import in CMS module
3ffa890 fix: correct static file mount order and update architecture validator
3307205 feat: add module info and configuration pages to admin panel
```

---

## Key Files Reference

### Self-Contained Module Infrastructure

- `app/modules/base.py` - ModuleDefinition with self-contained flags
- `app/modules/contracts/` - Protocol definitions for cross-module deps
- `app/templates_config.py` - Multi-directory template loader
- `models/database/__init__.py` - Dynamic module model discovery

### CMS Module (Pilot)

- `app/modules/cms/definition.py` - Module metadata
- `app/modules/cms/models/content_page.py` - ContentPage model
- `app/modules/cms/services/content_page_service.py` - Business logic
- `app/modules/cms/exceptions.py` - Module-specific exceptions
- `app/modules/cms/templates/cms/` - Namespaced templates

---

## Testing

```bash
# Verify app starts
python -c "from main import app; print('OK')"

# Run module service tests
python -m pytest tests/unit/services/test_module_service.py -v

# Verify CMS model is loaded
python -c "from app.modules.cms.models import ContentPage; print(ContentPage.__tablename__)"

# Verify template loading
python -c "from app.templates_config import templates; print(templates.env.loader)"
```