# Multi-Platform CMS Architecture - Implementation Plan

> **Status:** Phase 1 Complete | Phases 2-6 Pending
> **Last Updated:** 2026-01-18
> **Commit:** `408019d` (feat: add multi-platform CMS architecture Phase 1)

---

## 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 🔄 NEXT

### 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

### 3.1 Platform Management UI

New routes needed:
- [ ] `GET /admin/platforms` - List all platforms
- [ ] `GET /admin/platforms/{code}` - Platform details
- [ ] `GET /admin/platforms/{code}/pages` - Platform marketing pages
- [ ] `GET /admin/platforms/{code}/defaults` - Vendor default pages
- [ ] `POST/PUT/DELETE` endpoints for CRUD operations

### 3.2 Update Content Pages Admin

Changes to existing admin:
- [ ] Add platform dropdown filter
- [ ] Show page tier badge (Platform / Default / Override)
- [ ] Add `is_platform_page` toggle for platform-level pages
- [ ] Group pages by tier in list view

---

## Phase 4: Vendor Dashboard

### 4.1 Content Pages List Updates

- [ ] Show source indicator: "Default" / "Override" / "Custom"
- [ ] Add "Override Default" button for vendor default pages
- [ ] Add "Revert to Default" button for vendor overrides
- [ ] Show CMS usage: "3 of 10 pages used" with progress bar
- [ ] Upgrade prompt when approaching limit

### 4.2 Page Editor Updates

- [ ] Show banner: "This page overrides the platform default"
- [ ] "View Default" button to preview default content
- [ ] "Revert" button inline in editor

---

## Phase 5: Routes & Templates

### 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

### Architecture Documentation

Create `docs/architecture/multi-platform-cms.md`:
- [ ] Three-tier content hierarchy explanation
- [ ] Platform vs Vendor Default vs Vendor Override
- [ ] Database schema diagrams
- [ ] Request flow diagrams

### API Documentation

Update OpenAPI specs:
- [ ] Platform endpoints
- [ ] Content page endpoints with platform_id
- [ ] Vendor platform membership endpoints

### Developer Guide

Create `docs/guides/adding-new-platform.md`:
- [ ] Step-by-step platform creation
- [ ] Required database records
- [ ] Required config files
- [ ] Required routes and templates

---

## 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)