orion/docs/proposals/cms-redesign-alignment.md

# Proposal: CMS Redesign — Alignment with Market Standards

**Date:** 2026-04-14
**Status:** Draft
**Author:** Samir / Claude

---

## Problem Statement

The CMS has good foundations but several design flaws that create confusion and limit usability:

1. **Template vs Theme are disconnected** — Theme (colors/fonts at `/admin/stores/{code}/theme`) and page template (layout structure in `ContentPage.template`) are separate concepts with overlapping names, no UI connection
2. **No template selector in admin** — The `template` field can only be set via seed data or API, not the UI
3. **Content vs Sections duality** — A page has both a freeform `content` field AND a structured `sections` JSON. Which one renders depends on the template. Confusing for admins
4. **Sections editor shows platform-only sections** — Pricing section appears for store pages where it makes no sense
5. **No title/content translation UI** — The `title_translations` and `content_translations` fields exist in the model but have no admin editor. Only seed data populates them. Store overrides lose translations
6. **Fixed section types** — Only 5-8 section types, can't be extended by modules
7. **No section reordering** — Sections render in a fixed order defined by the template
8. **Everything mixed in one list** — Platform marketing pages, store defaults, and store overrides all in `/admin/content-pages`

### Specific bug found
FASHIONHUB has a store override for `/about` with `title_translations=NULL`. The override was created without translations (no UI to add them), so it always shows "About Fashion Hub" regardless of language. The store default it overrides has full translations (`fr="À propos"`, etc.).

---

## Market Standard (Shopify, WordPress, Squarespace)

| Concept | Market Standard | Our Current State |
|---------|----------------|-------------------|
| **Page types** | "Page" (prose) vs "Landing page" (sections) — clearly distinct | Mixed: same model, hidden `template` field decides rendering |
| **Template** | A starting point you choose when creating a page, pre-populates layout | Hidden field, can't be changed in UI |
| **Sections** | Ordered list, drag-and-drop, add/remove any type | Fixed positions, hardcoded in template |
| **Theme** | Global visual styling (colors, fonts) applied to all templates | Separate system, works but disconnected |
| **Translations** | Per-field translations, always visible when editing | Fields exist but no admin UI for page title/content |
| **Content editing** | Rich text for prose pages, section editor for landing pages | Both shown on same edit page |
| **Storefront management** | Dedicated section (Shopify: "Online Store") | Mixed into Content Management |

---

## Proposed Admin Menu Restructure

### Current
```
Content Management (CMS module, order=70)
  ├── Content Pages      → /admin/content-pages     (everything mixed)
  └── Store Themes       → /admin/store-themes

Platform Admin (Tenancy module)
  ├── Merchants          → /admin/merchants
  ├── Stores             → /admin/stores
  └── Platforms          → /admin/platforms
```

### Proposed
```
Platform Admin (Tenancy module)
  ├── Merchants          → /admin/merchants
  ├── Stores             → /admin/stores
  ├── Storefronts        → /admin/storefronts        ← NEW (card grid per store)
  └── Platforms          → /admin/platforms

Content Management (CMS module)
  ├── Platform Pages     → /admin/platform-pages     (renamed, platform marketing only)
  └── Media Library      → /admin/media
```

### Storefronts page (`/admin/storefronts`)

Card grid layout (like current `/admin/store-themes` but expanded). Each store card shows:

```
┌─────────────────────────────────────┐
│  🏪 FashionHub                      │
│  loyalty platform · active          │
│                                     │
│  [Customize Theme]  [Edit Homepage] │
│  [Manage Pages]     [Preview →]     │
└─────────────────────────────────────┘
```

| Action | What it opens |
|--------|--------------|
| **Customize Theme** | `/admin/stores/{code}/theme` (existing, works well) |
| **Edit Homepage** | Landing page section editor for this store's `slug=home` page |
| **Manage Pages** | List of content pages for this store (about, contact, faq — with translations) |
| **Preview** | Opens storefront in new tab |

This replaces the current **Store Themes** menu item — themes become one tab/action within the broader Storefronts management.

### Platform Pages (`/admin/platform-pages`)

Renamed from "Content Pages". Only shows `is_platform_page=True` pages. Used for platform marketing (homepage, pricing, about, terms, privacy). This is what the admin uses to manage the platform marketing site — not individual store content.

---

## Proposed CMS Changes

### Change 1: Page type selector in admin UI

Add a **Page Type** dropdown at the top of the content page edit form:

| Page Type | Template field | Editor shows | Hides |
|-----------|---------------|-------------|-------|
| **Content Page** | `default` | Title (with translations), content editor (with translations), SEO | Sections editor |
| **Landing Page** | `full` | Title (with translations), section editor, SEO | Content field |

When switching types:
- Content → Landing: initialize empty sections if none exist, hide content field
- Landing → Content: show content field, hide sections editor
- Data is preserved in both cases (no deletion)

### Change 2: Title and content translation UI

Add **language tabs** to the title and content fields — same pattern the sections editor already uses:

```
[FR] [EN] [DE] [LB]
┌────────────────────────────┐
│ Title: À propos            │
└────────────────────────────┘
┌────────────────────────────┐
│ Content:                   │
│ Bienvenue chez ...         │
└────────────────────────────┘
```

- Default language tab edits `form.title` / `form.content` directly
- Other language tabs edit `form.title_translations[lang]` / `form.content_translations[lang]`
- When creating a store override from a default, pre-populate translations from the default

### Change 3: Context-aware section editor

Hide irrelevant sections based on page context:

| Section | Platform Homepage | Store Homepage |
|---------|------------------|----------------|
| Hero | Yes | Yes |
| Features | Yes | Yes |
| Pricing | Yes | **No** |
| CTA | Yes | Yes |
| Testimonials | Yes | Yes |
| Gallery | Yes | Yes |
| Contact Info | Yes | Yes |

Implementation: pass `is_platform_page` to the JS component, conditionally show Pricing.

### Change 4: Sections as ordered list (future)

**Current:** Dict with fixed keys (`{"hero": {...}, "features": {...}, "cta": {...}}`)
**Proposed:** Ordered array:
```json
[
  {"type": "hero", "enabled": true, "data": {...}},
  {"type": "features", "enabled": true, "data": {...}},
  {"type": "cta", "enabled": true, "data": {...}}
]
```

Benefits:
- Admin can reorder (drag-and-drop)
- Admin can add/remove section types
- Template iterates array generically
- New section types don't require template changes

Migration: if `sections` is a dict → render in legacy order. If array → render in order.

### Change 5: Module-contributed section types (future)

New contract: `StorefrontSectionProviderProtocol`
- Catalog contributes: `product-showcase`, `category-grid`
- Loyalty contributes: `loyalty-signup`, `rewards-overview`
- Section registry aggregates from enabled modules
- Admin section editor shows available types from enabled modules

---

## What Stays the Same

- **3-tier content hierarchy** (platform → store default → store override) — solid
- **TranslatableText pattern** for sections — well-built
- **Section partials** as Jinja2 macros — reusable, themeable
- **Module-driven menus and widgets** — clean contracts
- **Theme system** (colors, fonts, CSS variables) — works well
- **CMS context providers** for header/footer pages — good pattern
- **ContentPage model** — no schema changes needed for Phase A

---

## Implementation Phases

### Phase A: Quick fixes (immediate, no schema changes)
- [ ] Title + content translation UI (language tabs on edit page)
- [ ] Page type selector (Content Page / Landing Page dropdown)
- [ ] Hide content field when Landing Page selected
- [ ] Hide Pricing section for non-platform pages
- [ ] Fix: FASHIONHUB about page — add translations
- [ ] Fix: store theme API bug (done — `get_store_by_code_or_subdomain`)

### Phase B: Menu restructure + Storefronts page
- [ ] Add "Storefronts" menu item under Platform Admin
- [ ] Build card grid page at `/admin/storefronts`
- [ ] Rename "Content Pages" → "Platform Pages" (filter to `is_platform_page=True`)
- [ ] Move Store Themes into Storefronts
- [ ] "Edit Homepage" action on store card → section editor for store's home page
- [ ] "Manage Pages" action → filtered content page list for that store

### Phase C: Section ordering + add/remove
- [ ] Migrate sections from dict to ordered array
- [ ] Drag-and-drop reordering in admin section editor
- [ ] Add/remove sections from available types
- [ ] Template renders sections from ordered array
- [ ] Backward compatibility for dict-format sections

### Phase D: Module-contributed sections
- [ ] `StorefrontSectionProviderProtocol` contract
- [ ] Catalog: product-showcase section
- [ ] Loyalty: loyalty-signup section
- [ ] Section registry in CMS module
- [ ] Admin section editor shows available types from enabled modules

---

## Relation to Storefront Builder Vision

This proposal covers the CMS foundation. The broader [storefront builder vision](storefront-builder-vision.md) builds on top:

| Builder Vision Phase | CMS Redesign Phase |
|---------------------|-------------------|
| Phase 1: Wire sections to store homepages | ✅ Done |
| Phase 2: Module header actions | ✅ Done |
| Phase 3: Module-contributed sections | Phase D |
| Phase 4: Widget slots | Separate (post Phase D) |
| Phase 5: Per-store menus | Phase B sets up the UI |
| Phase 6: Visual editor | Post Phase C (drag-and-drop foundation) |

---

## Key Files

| Component | File |
|-----------|------|
| Content page edit template | `app/modules/cms/templates/cms/admin/content-page-edit.html` |
| Content page edit JS | `app/modules/cms/static/admin/js/content-page-edit.js` |
| ContentPage model | `app/modules/cms/models/content_page.py` |
| Section schemas | `app/modules/cms/schemas/homepage_sections.py` |
| Section partials | `app/modules/cms/templates/cms/platform/sections/_*.html` |
| CMS definition (admin menu) | `app/modules/cms/definition.py` |
| Tenancy definition (admin menu) | `app/modules/tenancy/definition.py` |
| Store theme page | `app/modules/tenancy/templates/tenancy/admin/store-theme.html` |
| Store themes list | `app/modules/cms/templates/cms/admin/store-themes.html` |
| Storefront landing templates | `app/modules/cms/templates/cms/storefront/landing-*.html` |
| Seed data | `scripts/seed/create_default_content_pages.py` |