203671a7bf
Add the experience service with sites through analytics/AI hooks, migrations through 0011, and phase docs/manifests marking the track complete. Co-authored-by: Cursor <cursoragent@cursor.com>
5.1 KiB
Phase: Experience Theme & Layout Engine (11.3)
| Field | Value |
|---|---|
| Identifier | experience-11.3 |
| Status | Complete |
| Owner | Platform |
| Module(s) | Themes, Theme Versions, Layouts, Layout Versions, Site Theme Bindings, Page Layout Bindings |
| Service(s) | experience (Torbat Pages) |
| Depends On | experience-11.2 |
| ADR(s) | ADR-016, ADR-008 |
| Manifest | phase-manifest.yaml |
Enterprise Phase Discovery Record
| Input | Finding |
|---|---|
| Roadmap / manifest | Next unfinished Experience phase = experience-11.3 Theme & Layout Engine |
| Prior handover | phase-11-2.md — themes/layouts only; no template catalog |
| Boundaries | Experience owns themes/layouts; brand tokens align with ADR-008; no Core DB access |
| Existing codebase | Components/versions/placements complete; themes/layouts were capability flags False |
| Missing vs DoD | Theme packs, dynamic layouts, directionality shells, site/page assignments, policies/specs/CQ |
Derived capabilities: replaceable theme packs with immutable, versioned CSS tokens; dynamic layouts with immutable, versioned regions; RTL/LTR/both shells; bind a published theme version to a site and a published layout version to a page. Not templates, forms, SEO, visual builder UI.
Objective
Deliver production-ready replaceable themes and dynamic layouts on experience_db using a catalog + immutable version model (mirrors the Phase 11.2 component/component-version pattern) with directionality-ready shells and binding APIs — without a template catalog engine.
Scope
In Scope
ExperienceTheme(catalog: code, name, direction_mode, status, latest/published version pointers)ExperienceThemeVersion(immutable once published: tokens, brand_shell, direction_mode override)ExperienceLayout(catalog: code, name, kind, direction_mode, status, latest/published version pointers)ExperienceLayoutVersion(immutable once published: regions, structure_shell)SiteThemeBinding(pins a published theme version to a site; replaceable)PageLayoutBinding(pins a published layout version to a page; replaceable)- Policies, specifications, commands, queries
- Pagination / filter / sort / search on list APIs
- Permissions
experience.themes.*/experience.layouts.* - Events
experience.theme.*/experience.theme_version.*/experience.layout.*/experience.layout_version.*/experience.site_theme.*/experience.page_layout.* - Alembic
0004_phase_113_themes_layouts; version0.11.3.0 - Seed discovery:
direction_modesvia/capabilities
Out of Scope
- Template catalog / instantiation — Phase 11.4
- Full localization media pipeline — Phase 11.5
- Forms / surveys — Phase 11.6
- Owning Core tenant brand tables (ADR-008 remains Core; Experience stores theme packs)
Models
| Entity | Soft delete | Audit | Tenant | Optimistic lock |
|---|---|---|---|---|
| ExperienceTheme | Yes | Yes | Yes | Yes |
| ExperienceThemeVersion | Yes | Yes | Yes | Yes |
| ExperienceLayout | Yes | Yes | Yes | Yes |
| ExperienceLayoutVersion | Yes | Yes | Yes | Yes |
| SiteThemeBinding | Yes | Yes | Yes | Yes |
| PageLayoutBinding | Yes | Yes | Yes | Yes |
Permissions
experience.themes.view|create|update|delete|manage
experience.layouts.view|create|update|delete|manage
Events
experience.theme.created|updated|activated|deprecated|archived
experience.theme_version.created|updated|published|retired
experience.layout.created|updated|activated|deprecated|archived
experience.layout_version.created|updated|published|retired
experience.site_theme.assigned|replaced|unassigned
experience.page_layout.assigned|replaced|unassigned
APIs
| Method | Path |
|---|---|
| * | /api/v1/themes (+ activate/deprecate/archive/delete) |
| * | /api/v1/theme-versions (+ publish/retire) |
| * | /api/v1/layouts (+ activate/deprecate/archive/delete) |
| * | /api/v1/layout-versions (+ publish/retire) |
| * | /api/v1/site-theme-bindings (+ unassign) |
| * | /api/v1/page-layout-bindings (+ unassign) |
Artifact coverage (DoD)
| Artifact | Status |
|---|---|
| Discovery | This record |
| Policies / Specs / Commands / Queries | Implemented |
| Soft delete / Optimistic lock / Audit / Tenant | Yes |
| Pagination / Filter / Sort / Search | Yes |
| Background jobs | N/A — no async work in phase boundary |
| Templates | Explicitly out of scope |
Tests
- Unit policies
- API theme/layout/assignment flow
- Tenant isolation + optimistic lock
- Architecture / permission / migration / docs
Completion Criteria
- Theme and layout APIs + tests green
- No template catalog engine
- Docs / manifests / handover updated