orion/docs/proposals/section-based-homepage-plan.md

Section-Based Homepage Management System

Status: COMPLETE Created: 2026-01-20 Updated: 2026-01-23 Completed: All 7 phases implemented

Problem Statement

Current homepage implementation has critical issues:

1. Hardcoded platform content - Migrations contain OMS/Loyalty/Main-specific HTML
2. Monolithic content storage - Entire page stored as HTML blob, can't edit sections individually
3. No admin control - Hero, features, pricing sections are hardcoded in templates

Solution: JSON-Based Section Architecture

Approach: Add sections JSON field to ContentPage

Why JSON field vs separate PageSection model:

• Simpler - no new tables, no joins, no N+1 queries
• Flexible - schema can evolve without migrations
• Atomic - save entire homepage in one transaction
• Follows existing pattern - VendorTheme already uses JSON for colors

---

Multi-Language Support

Dynamic Language Support

Languages are NOT hardcoded. The system uses the platform's supported_languages setting:

# Platform model already has:
supported_languages = Column(JSON)  # e.g., ["fr", "de", "en"]
default_language = Column(String)   # e.g., "fr"

Schema with Dynamic i18n

class TranslatableText(BaseModel):
    """
    Text field with translations stored as dict.
    Keys are language codes from platform.supported_languages.
    """
    translations: dict[str, str] = {}  # {"fr": "...", "de": "...", "en": "..."}

    def get(self, lang: str, default_lang: str = "fr") -> str:
        """Get translation with fallback to default language."""
        return self.translations.get(lang) or self.translations.get(default_lang) or ""

class HeroButton(BaseModel):
    text: TranslatableText
    url: str
    style: str = "primary"

class HeroSection(BaseModel):
    enabled: bool = True
    badge_text: Optional[TranslatableText] = None
    title: TranslatableText
    subtitle: TranslatableText
    background_type: str = "gradient"
    buttons: list[HeroButton] = []

Template Usage with Platform Languages

{# Language comes from platform settings #}
{% set lang = request.state.language or platform.default_language %}
{% set default_lang = platform.default_language %}

<h1>{{ hero.title.get(lang, default_lang) }}</h1>
<p>{{ hero.subtitle.get(lang, default_lang) }}</p>

Admin UI Language Tabs

The admin editor dynamically generates language tabs from platform.supported_languages:

// Fetch platform languages
const platform = await apiClient.get(`/admin/platforms/${platformCode}`);
const languages = platform.supported_languages; // ["fr", "de", "en"]

// Render language tabs dynamically
languages.forEach(lang => {
    addLanguageTab(lang);
});

---

Implementation Plan

Phase 1: Database Changes

1.1 Add sections column to ContentPage

File: models/database/content_page.py

sections = Column(JSON, nullable=True, default=None)

1.2 Create migration

File: alembic/versions/xxx_add_sections_to_content_pages.py

• Add sections JSON column (nullable)

Phase 2: Schema Validation

2.1 Create Pydantic schemas with dynamic i18n

File: models/schema/homepage_sections.py (NEW)

from pydantic import BaseModel
from typing import Optional

class TranslatableText(BaseModel):
    """
    Stores translations as dict with language codes as keys.
    Language codes come from platform.supported_languages.
    """
    translations: dict[str, str] = {}

    def get(self, lang: str, default_lang: str = "fr") -> str:
        """Get text for language with fallback."""
        return self.translations.get(lang) or self.translations.get(default_lang) or ""

class HeroButton(BaseModel):
    text: TranslatableText
    url: str
    style: str = "primary"  # primary, secondary, outline

class HeroSection(BaseModel):
    enabled: bool = True
    badge_text: Optional[TranslatableText] = None
    title: TranslatableText = TranslatableText()
    subtitle: TranslatableText = TranslatableText()
    background_type: str = "gradient"
    buttons: list[HeroButton] = []

class FeatureCard(BaseModel):
    icon: str
    title: TranslatableText
    description: TranslatableText

class FeaturesSection(BaseModel):
    enabled: bool = True
    title: TranslatableText = TranslatableText()
    subtitle: Optional[TranslatableText] = None
    features: list[FeatureCard] = []
    layout: str = "grid"

class PricingSection(BaseModel):
    enabled: bool = True
    title: TranslatableText = TranslatableText()
    subtitle: Optional[TranslatableText] = None
    use_subscription_tiers: bool = True  # Pull from DB dynamically

class CTASection(BaseModel):
    enabled: bool = True
    title: TranslatableText = TranslatableText()
    subtitle: Optional[TranslatableText] = None
    buttons: list[HeroButton] = []

class HomepageSections(BaseModel):
    hero: Optional[HeroSection] = None
    features: Optional[FeaturesSection] = None
    pricing: Optional[PricingSection] = None
    cta: Optional[CTASection] = None

Phase 3: Template Changes

3.1 Create section partials

Directory: app/templates/platform/sections/ (NEW)

• _hero.html - Renders hero with language support
• _features.html - Renders features grid
• _pricing.html - Renders pricing (uses subscription_tiers from DB)
• _cta.html - Renders CTA section

3.2 Update homepage templates

File: app/templates/platform/homepage-default.html

{% set lang = request.state.language or platform.default_language or 'fr' %}

{% if page and page.sections %}
    {{ render_hero(page.sections.hero, lang) }}
    {{ render_features(page.sections.features, lang) }}
    {{ render_pricing(page.sections.pricing, lang, tiers) }}
    {{ render_cta(page.sections.cta, lang) }}
{% else %}
    {# Placeholder for unconfigured homepage #}
{% endif %}

Phase 4: Service Layer

4.1 Add section methods to ContentPageService

File: app/services/content_page_service.py

• update_homepage_sections(db, page_id, sections, updated_by) - Validates and saves
• get_default_sections() - Returns empty section structure

Phase 5: Admin API

5.1 Add section endpoints

File: app/api/v1/admin/content_pages.py

• GET /{page_id}/sections - Get structured sections
• PUT /{page_id}/sections - Update all sections
• PUT /{page_id}/sections/{section_name} - Update single section

Phase 6: Remove Hardcoded Content from Migrations

6.1 Update OMS migration

File: alembic/versions/z4e5f6a7b8c9_add_multi_platform_support.py

• Remove oms_homepage_content variable
• Create homepage with empty sections structure instead
• Set is_published=False (admin configures before publishing)

6.2 Migration creates structure only

• Migrations should ONLY create empty structure
• Content is entered via admin UI in each language

Phase 7: Admin UI

7.1 Add section editor to content-page-edit

File: app/templates/admin/content-page-edit.html

• Add "Sections" tab for homepage pages
• Language tabs within each section (dynamically from platform.supported_languages)
• Form fields for each section type
• Enable/disable toggle per section

File: static/admin/js/content-page-edit.js

• Section editor logic
• Language tab switching
• Save sections via API

---

Critical Files to Modify

1. models/database/content_page.py - Add sections column
2. models/schema/homepage_sections.py - NEW: Pydantic schemas with i18n
3. app/services/content_page_service.py - Add section methods
4. app/api/v1/admin/content_pages.py - Add section endpoints
5. app/templates/platform/sections/ - NEW: Section partials
6. app/templates/platform/homepage-default.html - Use section partials
7. app/routes/platform_pages.py - Pass sections + language to context
8. alembic/versions/z4e5f6a7b8c9_*.py - Remove hardcoded content
9. app/templates/admin/content-page-edit.html - Section editor UI with language tabs
10. static/admin/js/content-page-edit.js - Section editor JS

---

Section JSON Schema Example (with dynamic i18n)

Languages in translations dict come from platform.supported_languages.

{
  "hero": {
    "enabled": true,
    "badge_text": {
      "translations": {
        "fr": "Essai gratuit de 30 jours",
        "de": "30 Tage kostenlos testen",
        "en": "30-Day Free Trial"
      }
    },
    "title": {
      "translations": {
        "fr": "Votre titre de plateforme ici",
        "de": "Ihr Plattform-Titel hier",
        "en": "Your Platform Headline Here"
      }
    },
    "subtitle": {
      "translations": {
        "fr": "Une description convaincante de votre plateforme.",
        "de": "Eine überzeugende Beschreibung Ihrer Plattform.",
        "en": "A compelling description of your platform."
      }
    },
    "background_type": "gradient",
    "buttons": [
      {
        "text": {
          "translations": {"fr": "Commencer", "de": "Loslegen", "en": "Get Started"}
        },
        "url": "/signup",
        "style": "primary"
      }
    ]
  },
  "features": {
    "enabled": true,
    "title": {
      "translations": {
        "fr": "Pourquoi nous choisir",
        "de": "Warum uns wählen",
        "en": "Why Choose Us"
      }
    },
    "features": [
      {
        "icon": "lightning-bolt",
        "title": {"translations": {"fr": "Rapide", "de": "Schnell", "en": "Fast"}},
        "description": {"translations": {"fr": "Rapide et efficace.", "de": "Schnell und effizient.", "en": "Quick and efficient."}}
      }
    ]
  },
  "pricing": {
    "enabled": true,
    "title": {
      "translations": {
        "fr": "Tarification simple",
        "de": "Einfache Preise",
        "en": "Simple Pricing"
      }
    },
    "use_subscription_tiers": true
  },
  "cta": {
    "enabled": true,
    "title": {
      "translations": {
        "fr": "Prêt à commencer?",
        "de": "Bereit anzufangen?",
        "en": "Ready to Start?"
      }
    },
    "buttons": [
      {
        "text": {
          "translations": {"fr": "S'inscrire gratuitement", "de": "Kostenlos registrieren", "en": "Sign Up Free"}
        },
        "url": "/signup",
        "style": "primary"
      }
    ]
  }
}

---

Migration Strategy (No Hardcoded Content)

When creating a platform homepage:

homepage = ContentPage(
    platform_id=platform_id,
    slug="home",
    title="Homepage",  # Generic
    content="",  # Empty - sections used instead
    sections=get_default_sections(),  # Empty structure with all languages
    is_published=False,  # Admin configures first
)

---

Verification Steps

1. Run migration to add sections column
2. Create a test homepage with sections via API (all languages)
3. Verify homepage renders correct language based on request
4. Test admin UI section editor with language tabs
5. Verify pricing section pulls from subscription_tiers
6. Test enable/disable toggle for each section
7. Test language fallback when translation is missing

---

Notes

• Languages are dynamic from platform.supported_languages (not hardcoded)
• Fallback uses platform.default_language
• Admin UI should allow partial translations (show warning indicator for missing)

Pre-Implementation Cleanup

Before implementing, fix the broken OMS migration file:

• alembic/versions/z4e5f6a7b8c9_add_multi_platform_support.py has "I dn" on line 181