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

Multi-Platform CMS Architecture - Implementation Plan

Status: All Phases Complete (1-6) Last Updated: 2026-01-19 Commits:

• 408019d (Phase 1: Database & Models)
• 9680026 (Phases 2-5: Migration, Admin, Docs, Vendor Dashboard)
• Phase 6: Loyalty Platform Setup (pending commit)

---

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

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

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

6.1 Database Setup ✅

Migration: alembic/versions/z5f6g7h8i9j0_add_loyalty_platform.py

Inserts Loyalty platform with:

• code: loyalty
• name: Loyalty+
• domain: loyalty.lu
• path_prefix: loyalty
• theme_config: purple color scheme

6.2 Platform Marketing Pages ✅

Page	Slug	Status
Homepage	home	✅
Pricing	pricing	✅
Features	features	✅
How It Works	how-it-works	✅

6.3 Vendor Default Pages ✅

Page	Slug	Status
About	about	✅
Rewards Catalog	rewards-catalog	✅
Terms	terms	✅
Privacy	privacy	✅

---

Documentation Requirements ✅ PARTIAL

Architecture Documentation ✅ COMPLETE

Created 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 endpoints reference
• Key files reference
• Adding new platform guide

API Documentation

OpenAPI specs auto-generated from FastAPI:

• Platform endpoints (/api/v1/admin/platforms)
• Content page endpoints with platform fields
• Vendor platform membership endpoints (future)

Developer Guide

Included in docs/architecture/multi-platform-cms.md:

• Step-by-step platform creation
• Required database records
• 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)