orion/docs/proposals/storefront-builder-vision.md

Proposal: Storefront Builder Vision

Date: 2026-04-13 Status: Draft Author: Samir / Claude

---

Problem Statement

The platform has a solid CMS foundation — section-based homepages, module-driven menus, widget contracts, theme system, 3-tier content hierarchy, multi-language support. However, there are gaps between the platform marketing site (well-built) and the store storefront (catching up). The goal is to enable "yes, we can build you a one-page ecommerce site" as a real capability.

---

Current State

What works well

• Platform homepage: Section-based rendering via page.sections JSON with 8 section partials (hero, features, pricing, CTA, testimonials, gallery, contact, products)
• Admin section editor: API for editing sections individually or all at once, multi-language
• Module contracts: Widget protocol, context providers, menu declarations, route gating
• Store theme: Colors, fonts, logo, custom CSS — all applied via CSS variables
• Component library: Ecommerce macros (product cards, grids, add-to-cart, mini-cart) at /admin/components#ecommerce
• 3-tier content: Platform pages → store defaults → store overrides, with placeholder resolution

What's missing

1. Store homepages don't use sections (only landing-full.html supports them, but defaults use landing-default.html)
2. Header actions (search, cart) are bespoke in the base template
3. No widget slots on storefront pages (widgets only on dashboards)
4. No per-store menu customization (menus are platform-wide)
5. Section types are fixed (8 types, not pluggable by modules)
6. No visual editor (admin edits via JSON-backed forms)

---

Phase 1: Wire Sections to Store Homepages

Goal: Store homepages get section-based rendering immediately, using existing infrastructure.

Changes

• Change seed script: store default homepages use template="full" instead of template="default"
• Populate sections JSON per platform:
  • OMS stores: Hero → Product Showcase → Features → CTA
  • Loyalty stores: Hero → Loyalty Signup → Features → CTA
  • Hosting stores: Hero → Services → Features → CTA
• Admin can already edit sections via existing API at /admin/content-pages/{id}/edit

Impact

• Every store immediately gets a section-based homepage
• Merchants can customize via admin UI (no code changes needed)
• All 8 existing section types available

Effort

Small — mostly seed data and one template field change.

---

Phase 2: Module-Contributed Header Actions

Goal: Remove bespoke header rendering. Modules provide their own action templates.

Changes

• Add optional header_template field to MenuItemDefinition in app/modules/base.py
• Cart module provides cart/storefront/partials/header-cart.html (cart icon + Alpine badge)
• Catalog module provides catalog/storefront/partials/header-search.html (search button + modal trigger)
• Update storefront/base.html: iterate storefront_nav.get('actions', []), use {% include item.header_template %} when present, generic link otherwise
• Remove all hardcoded action rendering from base template

Architecture

Module definition:
    MenuItemDefinition(
        id="cart",
        label_key="cart.storefront.actions.cart",
        icon="shopping-cart",
        route="cart",
        header_template="cart/storefront/partials/header-cart.html",
    )

Base template:
    {% for item in storefront_nav.get('actions', []) %}
        {% if item.header_template %}
            {% include item.header_template %}
        {% else %}
            <a href="{{ base_url }}{{ item.route }}">{{ _(item.label_key) }}</a>
        {% endif %}
    {% endfor %}

Impact

• Any module can contribute a header action with custom UI
• Adding wishlist, notifications, etc. requires zero base template changes
• Fully module-agnostic

Effort

Small — new field on MenuItemDefinition, two partial templates, base template update.

---

Phase 3: Module-Contributed Page Sections

Goal: Modules can register their own section types for storefront pages.

Changes

• New contract: StorefrontSectionProviderProtocol in app/modules/contracts/

  class StorefrontSectionProviderProtocol(Protocol):
      def get_section_types(self) -> list[SectionTypeDefinition]: ...
      # SectionTypeDefinition: id, name, icon, template_path, default_config
  

• New field on ModuleDefinition: section_provider
• Section registry in CMS module aggregates section types from all enabled modules
• Catalog contributes:
  • product-showcase — featured products grid (uses existing product card macros)
  • category-grid — browse by category
• Loyalty contributes:
  • loyalty-signup — join rewards CTA with program details
  • rewards-overview — points/stamps explanation
• Update admin section editor to show available sections from enabled modules

Architecture

Section rendering flow:
    1. Page has sections JSON: {"hero": {...}, "product-showcase": {...}, ...}
    2. Template iterates sections in order
    3. For each section, looks up the partial from the section registry
    4. Renders: {% include section_registry[section_type].template_path %}
    5. Passes section data + language context

Impact

• Platform-specific storefronts: OMS stores get product sections, Loyalty stores get loyalty sections
• Admin editor adapts to available sections based on platform modules
• No template changes needed when adding new section types

Effort

Medium — new contract, section registry service, admin UI update, 4-6 new section partials.

---

Phase 4: Storefront Page Widget Slots

Goal: Place smaller components within pages — product carousels, loyalty badges, social feeds.

Changes

• Define named slots in storefront templates: below-hero, above-footer, content-sidebar
• New contract method on widget protocol:

  def get_page_widgets(self, db, store_id, slot, page_slug, context) -> list[StorefrontPageWidget]
  # StorefrontPageWidget: key, template, data, order
  

• Widget aggregator collects from enabled modules per slot
• Templates render:

  {% for widget in page_widgets.get('below-hero', []) %}
      {% include widget.template %}
  {% endfor %}
  

• Catalog contributes: "featured products" widget, "new arrivals" widget
• Loyalty contributes: "join rewards" widget, "points balance" widget

Sections vs Widgets

• Sections = full-width page blocks, ordered top-to-bottom, part of page structure
• Widgets = smaller components placed within named slots, multiple per slot

Impact

• Mix-and-match content: a loyalty store can add a product widget to their homepage
• Modules contribute without coupling — templates never check module names
• Foundation for "one-page ecommerce" capability

Effort

Medium — builds on existing widget infrastructure, new slot rendering in templates.

---

Phase 5: Per-Store Menu & Section Ordering

Goal: Stores can customize their navigation and homepage layout.

Changes

• Menu overrides: store_menu_config table (store_id, item_id, is_visible, display_order)
  • Stores can hide/reorder items from the platform menu
  • menu_discovery_service gets a store-level filter on top of platform-level
• Section ordering: display_order field per section in the sections JSON
  • Admin UI: drag-and-drop section reordering
  • Sections can be enabled/disabled per store override
• Section visibility: Store overrides can hide sections from the default homepage

Impact

• Each store can have a unique navigation and homepage layout
• Platform provides the base, stores customize
• Follows existing 3-tier pattern (platform → store default → store override)

Effort

Medium-large — new table, menu service update, admin drag-and-drop UI.

---

Phase 6: Visual Editor (Future)

Goal: WYSIWYG editing experience for storefront pages.

Changes

• Live preview panel showing section rendering as you edit
• Drag-and-drop section placement and reordering
• Inline text editing with rich text toolbar
• Template/section picker with visual thumbnails
• Mobile/desktop preview toggle

Architecture

• Frontend-only addition — calls the same section APIs
• Could use iframe-based preview with postMessage communication
• Section partials render identically in preview and production

Impact

• Non-technical merchants can build their own storefronts
• Reduces support burden
• Competitive feature for attracting merchants

Effort

Large — significant frontend work, but backend APIs already exist.

---

One-Page Ecommerce Site — End-to-End Flow

With Phases 1-4 complete, here's the workflow:

1. Admin creates store on OMS platform
2. Store homepage auto-created with section-based default (hero, product showcase, features, CTA)
3. Merchant edits at /admin/content-pages/{id}/edit:
   • Hero: store branding, tagline, "Shop Now" button
   • Product Showcase: featured products (from catalog module section)
   • Testimonials: customer reviews
   • CTA: newsletter signup
4. Theme at /admin/stores/{code}/theme: colors, logo, fonts
5. Customer visits storefront → sees professional one-page site with products, cart, checkout

---

Key Files Reference

Component	File
Section partials	app/modules/cms/templates/cms/platform/sections/_*.html
ContentPage model	app/modules/cms/models/content_page.py
Section schemas	app/modules/cms/schemas/homepage_sections.py
Widget contracts	app/modules/contracts/widgets.py
Module base	app/modules/base.py (MenuItemDefinition, ModuleDefinition)
Storefront base	app/templates/storefront/base.html
Store theme model	app/modules/cms/models/store_theme.py
Menu discovery	app/modules/core/services/menu_discovery_service.py
Widget aggregator	app/modules/core/services/widget_aggregator.py
Component library	app/modules/dev_tools/templates/dev_tools/admin/components.html
Seed data	scripts/seed/create_default_content_pages.py
Storefront routes	app/modules/cms/routes/pages/storefront.py
Admin section API	app/modules/cms/routes/api/admin_content_pages.py