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

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

# 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

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

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

# 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

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