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

Multi-Platform CMS Architecture - Implementation Plan

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

• 408019d (Phase 1: Database & Models)
• 9680026 (Phases 2-5: Migration, Admin, Docs, Vendor Dashboard)
• 32bcbc8 (Phase 6: Loyalty Platform Setup)
• a2407ae (Phase 7: Platform URL Routing Strategy)

---

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

File: middleware/vendor_context.py

Changes completed:

• Use request.state.platform_clean_path instead of request.url.path for path-based vendor detection (line 52)
• 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 ✅ COMPLETE

• Add platform context to shop routes (shop_pages.py line 117)
• Use request.state.platform for template selection
• Pass platform to content page lookups (platform_id used in CMS queries)

5.3 Test All URL Patterns ✅ COMPLETE

Development (using /platforms/ prefix):

• localhost:9999/platforms/oms/ → OMS homepage
• localhost:9999/platforms/oms/pricing → OMS pricing page
• localhost:9999/platforms/oms/vendors/{code}/ → Vendor storefront
• localhost:9999/platforms/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	✅

---

Phase 7: Platform URL Routing Strategy ✅ COMPLETE

7.1 URL Structure Changes

Previous approach (DEPRECATED):

• Development: /oms/, /loyalty/ (first path segment = platform)
• Ambiguity: /faq could be platform or page

New approach:

• Development: /platforms/oms/, /platforms/loyalty/ (explicit prefix)
• Main marketing site: / (no prefix) → main platform
• Clear separation: /faq = main site, /platforms/oms/faq = OMS

7.2 Implementation Details

Task	File	Status
Update middleware URL detection	middleware/platform_context.py	✅
Change DEFAULT_PLATFORM_CODE	middleware/platform_context.py	✅
Remove hardcoded /oms, /loyalty routes	main.py	✅
Update platform_pages.py homepage	app/routes/platform_pages.py	✅
Add 'main' platform migration	alembic/versions/z6g7h8i9j0k1_...py	✅

7.3 URL Routing Summary

Platform	Code	Dev URL	Prod URL
Main Marketing	main	localhost:9999/	wizamart.lu/
OMS	oms	localhost:9999/platforms/oms/	oms.lu/
Loyalty	loyalty	localhost:9999/platforms/loyalty/	loyalty.lu/

7.4 Middleware Detection Logic

Request arrives
      │
      ▼
┌─────────────────────────────────────┐
│ Production domain? (oms.lu, etc.)   │
└─────────────────────────────────────┘
      │ YES → Route to that platform
      │
      ▼ NO (localhost)
┌─────────────────────────────────────┐
│ Path starts with /platforms/{code}? │
└─────────────────────────────────────┘
      │ YES → Strip prefix, route to platform
      │       /platforms/oms/pricing → /pricing
      │
      ▼ NO
┌─────────────────────────────────────┐
│ Use 'main' platform (DEFAULT)       │
│ /faq → Main site FAQ page           │
└─────────────────────────────────────┘

---

Documentation Requirements ✅ COMPLETE

Architecture Documentation ✅ COMPLETE

Updated documentation for Phase 7:

• docs/architecture/url-routing/overview.md - Multi-platform URL routing section
• docs/architecture/multi-platform-cms.md - Request flow with path rewriting
• docs/architecture/middleware.md - PlatformContextMiddleware documentation
• 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 with URL summary

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
• Platform URL summary table

---

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

---

Verification Checklist

All phases are complete. Use these commands to verify:

# 1. Check platforms in database
psql -d wizamart -c "SELECT code, name, domain FROM platforms;"
# Expected: main, oms, loyalty

# 2. Test main marketing site
curl -s localhost:9999/ | grep -o "<title>.*</title>"
# Expected: Main marketing site title

# 3. Test OMS platform
curl -s localhost:9999/platforms/oms/ | grep -o "<title>.*</title>"
# Expected: OMS platform title

# 4. Test Loyalty platform
curl -s localhost:9999/platforms/loyalty/ | grep -o "<title>.*</title>"
# Expected: Loyalty platform title

# 5. Verify middleware detection
python -c "
from middleware.platform_context import PlatformContextMiddleware, DEFAULT_PLATFORM_CODE
print(f'DEFAULT_PLATFORM_CODE: {DEFAULT_PLATFORM_CODE}')
# Expected: main
"

---

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)