orion/docs/proposals/multi-platform-cms-architecture-implementation-plan.md

# Multi-Platform CMS Architecture - Implementation Plan

> **Status:** Phases 1-5 Complete | Phase 6 Pending
> **Last Updated:** 2026-01-19
> **Commits:**
> - `408019d` (Phase 1: Database & Models)
> - `9680026` (Phases 2-5: Migration, Admin, Docs, Vendor Dashboard)

---

## Executive Summary

Transform the single-platform OMS into a multi-platform system supporting independent business offerings (OMS, Loyalty, Site Builder), each with its own CMS, vendor defaults, and marketing pages.

---

## Phase 1: Database & Models ✅ COMPLETE

### Completed Work

| Task | File | Status |
|------|------|--------|
| Platform model | `models/database/platform.py` | ✅ |
| VendorPlatform junction table | `models/database/vendor_platform.py` | ✅ |
| SubscriptionTier updates | `models/database/subscription.py` | ✅ |
| ContentPage updates | `models/database/content_page.py` | ✅ |
| CMS feature codes | `models/database/feature.py` | ✅ |
| Model exports | `models/database/__init__.py` | ✅ |
| PlatformContextMiddleware | `middleware/platform_context.py` | ✅ |
| Middleware exports | `middleware/__init__.py` | ✅ |
| ContentPageService updates | `app/services/content_page_service.py` | ✅ |
| Alembic migration | `alembic/versions/z4e5f6a7b8c9_...py` | ✅ |
| Platform folder structure | `app/platforms/` | ✅ |

---

## Phase 2: OMS Migration & Integration ✅ COMPLETE

### 2.1 Run Database Migration

```bash
# 1. Backup database first
pg_dump wizamart > wizamart_backup_$(date +%Y%m%d).sql

# 2. Run migration
alembic upgrade head

# 3. Verify migration
psql -d wizamart -c "SELECT * FROM platforms;"
psql -d wizamart -c "SELECT COUNT(*) FROM vendor_platforms;"
psql -d wizamart -c "SELECT platform_id, is_platform_page, COUNT(*) FROM content_pages GROUP BY 1, 2;"
```

### 2.2 Register PlatformContextMiddleware in main.py

```python
# In main.py, add BEFORE VendorContextMiddleware
from middleware import PlatformContextMiddleware

# Order matters: Platform detection must run first
app.add_middleware(VendorContextMiddleware)  # Runs second (existing)
app.add_middleware(PlatformContextMiddleware)  # Runs first (NEW)
```

### 2.3 Update VendorContextMiddleware

File: `middleware/vendor_context.py`

Changes needed:
- [ ] Use `request.state.platform_clean_path` instead of `request.url.path` for path-based vendor detection
- [ ] Skip vendor detection if no platform found (platform marketing pages like /oms/pricing)
- [ ] Pass platform context to vendor lookup for multi-platform vendor support

### 2.4 Fix Platform Homepage Route

File: `app/routes/platform/homepage.py`

Current state (BROKEN):
- Uses hardcoded `homepage-wizamart.html` template
- Admin CMS changes are saved but ignored by route

Fix required:
```python
# Get platform from middleware
platform = request.state.platform

# Query CMS for platform homepage
page = content_page_service.get_platform_page(
    db,
    platform_id=platform.id,
    slug="home"
)

if page:
    # Render with selected template
    return templates.TemplateResponse(
        f"platform/homepage-{page.template}.html",
        {"request": request, "page": page}
    )
else:
    # Fallback to hardcoded (temporary)
    return templates.TemplateResponse("platform/homepage-wizamart.html", {...})
```

### 2.5 Update Content Page Routes

Files to update:
- [ ] `app/routes/platform/content_pages.py` - Add platform_id from request.state.platform
- [ ] `app/routes/vendor/content_pages.py` - Add platform_id to queries
- [ ] `app/routes/admin/content_pages.py` - Add platform filtering

---

## Phase 3: Admin Interface ✅ COMPLETE

### 3.1 Platform Management UI

| Task | File | Status |
|------|------|--------|
| Platform list page route | `app/routes/admin_pages.py` | ✅ |
| Platform detail/edit routes | `app/routes/admin_pages.py` | ✅ |
| Platform API endpoints | `app/api/v1/admin/platforms.py` | ✅ |
| Register API router | `app/api/v1/admin/__init__.py` | ✅ |
| Platforms template | `app/templates/admin/platforms.html` | ✅ |
| Platforms JS component | `static/admin/js/platforms.js` | ✅ |
| Sidebar menu item | `app/templates/admin/partials/sidebar.html` | ✅ |

### 3.2 Update Content Pages Admin

| Task | File | Status |
|------|------|--------|
| Platform dropdown filter | `app/templates/admin/content-pages.html` | ✅ |
| Four-tab tier view | `app/templates/admin/content-pages.html` | ✅ |
| Tier badges (Blue/Teal/Purple) | `static/admin/js/content-pages.js` | ✅ |
| Platform filter in JS | `static/admin/js/content-pages.js` | ✅ |
| API schema with platform fields | `app/api/v1/admin/content_pages.py` | ✅ |
| Model to_dict with platform_name | `models/database/content_page.py` | ✅ |

---

## Phase 4: Vendor Dashboard ✅ COMPLETE

### 4.1 Content Pages List Updates

| Task | File | Status |
|------|------|--------|
| Source indicators (Default/Override/Custom) | `app/templates/vendor/content-pages.html` | ✅ Already existed |
| Override Default button | `app/templates/vendor/content-pages.html` | ✅ Already existed |
| Revert to Default (delete override) | `static/vendor/js/content-pages.js` | ✅ Already existed |
| CMS usage API endpoint | `app/api/v1/vendor/content_pages.py` | ✅ New |
| CMS usage progress bar | `app/templates/vendor/content-pages.html` | ✅ New |
| Upgrade prompt at 80% limit | `app/templates/vendor/content-pages.html` | ✅ New |
| Load usage in JS | `static/vendor/js/content-pages.js` | ✅ New |

### 4.2 Page Editor Updates

| Task | File | Status |
|------|------|--------|
| Override info banner | `app/templates/vendor/content-page-edit.html` | ✅ Already existed |
| View Default button | `app/templates/vendor/content-page-edit.html` | ✅ New |
| Default preview modal | `app/templates/vendor/content-page-edit.html` | ✅ New |
| Platform default API | `app/api/v1/vendor/content_pages.py` | ✅ New |
| Show default preview JS | `static/vendor/js/content-page-edit.js` | ✅ New |
| Revert button (styled) | `app/templates/vendor/content-page-edit.html` | ✅ New |

---

## Phase 5: Routes & Templates ✅ COMPLETE

### 5.1 Platform-Prefixed Routes (Development)

Register in `main.py`:
```python
# Development mode: path-based routing
if settings.environment == "development":
    app.mount("/oms", oms_router)
    app.mount("/loyalty", loyalty_router)
```

### 5.2 Update Shop Routes

- [ ] Add platform context to shop routes
- [ ] Use `request.state.platform` for template selection
- [ ] Pass platform to content page lookups

### 5.3 Test All URL Patterns

Development:
- [ ] `localhost:9999/oms/` → OMS homepage
- [ ] `localhost:9999/oms/pricing` → OMS pricing page
- [ ] `localhost:9999/oms/vendors/{code}/` → Vendor storefront
- [ ] `localhost:9999/loyalty/` → Loyalty homepage

---

## Phase 6: Loyalty Platform Setup

### 6.1 Database Setup

```sql
-- Insert loyalty platform
INSERT INTO platforms (code, name, description, domain, path_prefix, ...)
VALUES ('loyalty', 'Loyalty+', 'Customer loyalty program', 'loyalty.lu', 'loyalty', ...);
```

### 6.2 Create Platform Pages

- [ ] Loyalty homepage
- [ ] Loyalty pricing
- [ ] Loyalty features
- [ ] How it works

### 6.3 Create Vendor Defaults

- [ ] About (loyalty-specific)
- [ ] Rewards catalog
- [ ] Terms of service
- [ ] Privacy policy

---

## Documentation Requirements ✅ PARTIAL

### Architecture Documentation ✅ COMPLETE

Created `docs/architecture/multi-platform-cms.md`:
- [x] Three-tier content hierarchy explanation
- [x] Platform vs Vendor Default vs Vendor Override
- [x] Database schema diagrams
- [x] Request flow diagrams
- [x] API endpoints reference
- [x] Key files reference
- [x] Adding new platform guide

### API Documentation

OpenAPI specs auto-generated from FastAPI:
- [x] Platform endpoints (`/api/v1/admin/platforms`)
- [x] Content page endpoints with platform fields
- [ ] Vendor platform membership endpoints (future)

### Developer Guide

Included in `docs/architecture/multi-platform-cms.md`:
- [x] Step-by-step platform creation
- [x] Required database records
- [x] Key files reference

---

## Quick Reference

### Three-Tier Content Resolution

```
Customer visits: oms.lu/vendors/wizamart/about
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ Tier 1: Vendor Override                                      │
│ WHERE platform_id=1 AND vendor_id=123 AND slug='about'       │
│ Found? → Return vendor's custom page                         │
└─────────────────────────────────────────────────────────────┘
                         │ Not found
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ Tier 2: Vendor Default                                       │
│ WHERE platform_id=1 AND vendor_id IS NULL                    │
│   AND is_platform_page=FALSE AND slug='about'                │
│ Found? → Return platform default                             │
└─────────────────────────────────────────────────────────────┘
                         │ Not found
                         ▼
                    Return 404
```

### CMS Tier Limits

| Tier | Total Pages | Custom Pages |
|------|-------------|--------------|
| Essential | 3 | 0 |
| Professional | 10 | 5 |
| Business | 30 | 20 |
| Enterprise | Unlimited | Unlimited |

### Platform Marketing Page Slugs

`home`, `platform_homepage`, `pricing`, `about`, `contact`, `faq`, `terms`, `privacy`, `features`, `integrations`

---

## Next Session Checklist

Start here when resuming work:

1. [ ] Run `alembic upgrade head` (backup DB first!)
2. [ ] Verify migration: `SELECT * FROM platforms;`
3. [ ] Register PlatformContextMiddleware in `main.py`
4. [ ] Update VendorContextMiddleware to use `platform_clean_path`
5. [ ] Fix platform homepage to use CMS
6. [ ] Test: `localhost:9999/oms/` shows CMS homepage
7. [ ] Test: Three-tier resolution works

---

## Files Created/Modified in Phase 1

### New Files (17)
```
models/database/platform.py
models/database/vendor_platform.py
middleware/platform_context.py
alembic/versions/z4e5f6a7b8c9_add_multi_platform_support.py
app/platforms/__init__.py
app/platforms/oms/__init__.py
app/platforms/oms/config.py
app/platforms/oms/routes/__init__.py
app/platforms/oms/templates/__init__.py
app/platforms/loyalty/__init__.py
app/platforms/loyalty/config.py
app/platforms/loyalty/routes/__init__.py
app/platforms/loyalty/templates/__init__.py
app/platforms/shared/__init__.py
app/platforms/shared/base_platform.py
app/platforms/shared/routes/__init__.py
app/platforms/shared/templates/__init__.py
```

### Modified Files (7)
```
models/database/__init__.py
models/database/content_page.py
models/database/subscription.py
models/database/feature.py
models/database/vendor.py
middleware/__init__.py
app/services/content_page_service.py
```

---

## Notes

- Git tag `v1.0.0-pre-multiplatform` was created before starting
- All existing `content_pages` will be backfilled to OMS platform
- All existing vendors will be linked to OMS via `vendor_platforms`
- Migration is reversible (see downgrade function in migration file)