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>
4.2 KiB
4.2 KiB
Phase Handover — Experience 11.3 Theme & Layout Engine
Metadata
| Field | Value |
|---|---|
| Phase ID | experience-11.3 |
| Title | Theme & Layout Engine |
| Status | Complete |
| Service(s) | experience (experience_db) |
| Version | 0.11.3.0 |
| Date | 2026-07-26 |
| ADR(s) | ADR-016, ADR-008 |
Discovery Summary
Prior phase delivered versioned components. Gap: replaceable theme packs and dynamic layout shells with directionality, plus site/page bindings without rewriting page trees. Mirrors the Phase 11.2 component/component-version catalog+immutable-version pattern. Templates deferred to 11.4.
Reusable Components
| Component | Location | Reuse notes |
|---|---|---|
| Theme catalog + versions | app/models/themes.py (ExperienceTheme, ExperienceThemeVersion), services/themes.py |
Tokens + brand shell immutable once published |
| Layout catalog + versions | app/models/themes.py (ExperienceLayout, ExperienceLayoutVersion) |
Regions/structure shell immutable once published |
| Bindings | SiteThemeBinding, PageLayoutBinding |
Pin a published version; swap without page rewrite |
| Policies / specs | app/policies/themes.py, app/specifications/themes.py |
Lifecycle + version + binding rules, list UX |
Public APIs
| Method | Path | Permission |
|---|---|---|
| CRUD + activate/deprecate/archive | /api/v1/themes |
experience.themes.* |
| CRUD + publish/retire | /api/v1/theme-versions |
experience.themes.* |
| CRUD + activate/deprecate/archive | /api/v1/layouts |
experience.layouts.* |
| CRUD + publish/retire | /api/v1/layout-versions |
experience.layouts.* |
| Assign / unassign | /api/v1/site-theme-bindings |
experience.themes.* |
| Assign / unassign | /api/v1/page-layout-bindings |
experience.layouts.* |
Events
| Event type | Notes |
|---|---|
experience.theme.* |
Theme catalog lifecycle |
experience.theme_version.* |
Theme version created/updated/published/retired |
experience.layout.* |
Layout catalog lifecycle |
experience.layout_version.* |
Layout version created/updated/published/retired |
experience.site_theme.* |
Site theme bind/replace/unassign |
experience.page_layout.* |
Page layout bind/replace/unassign |
Extension Points
| Extension point | How to extend | Forbidden uses |
|---|---|---|
ExperienceThemeVersion.tokens |
Frontend CSS variables (ADR-008) | Write Core tenant brand tables |
ExperienceLayoutVersion.regions / structure_shell |
Template phase consumes regions | Store full page trees / CMS |
ThemeMarketplaceProvider |
External packs via protocol | Shared marketplace DB |
Known Limitations
- No template catalog (11.4)
- Bindings require an ACTIVE theme/layout with a PUBLISHED version
- Metrics remain discovery-oriented
- Visual theme editor UI is frontend-only
Migration Notes
| Item | Detail |
|---|---|
| Alembic revision(s) | 0004_phase_113_themes_layouts (head) |
| Upgrade steps | alembic upgrade head |
| Downgrade support | Drops bindings, versions, layouts, themes |
| Breaking changes | None (additive) |
Dependencies
| Dependency | Type |
|---|---|
| experience-11.2 components | Required prior |
| ADR-016 / ADR-008 | Boundaries / branding |
Quality Gates
- Discovery complete
- Architecture / boundaries preserved
- Tests green
- Documentation + manifests + registries updated
- Self audit: no template engine leakage; themes replaceable
Next Phase Entry
| Field | Value |
|---|---|
| Recommended next phase | experience-11.4 Template System |
| Entry checklist | Read this handover + phase doc; implement templates only — no forms/surveys yet |
Completion Sign-Off
- Quality gates passed
- Tests green
- Documentation updated
- Progress / next-steps / registries updated
- Self audit completed