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>
127 lines
5.1 KiB
Markdown
127 lines
5.1 KiB
Markdown
# 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](architecture/adr/ADR-016.md), [ADR-008](architecture/adr/ADR-008.md) |
|
|
| Manifest | [phase-manifest.yaml](ai-framework/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](phase-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`; version `0.11.3.0`
|
|
- Seed discovery: `direction_modes` via `/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
|
|
|
|
- [x] Unit policies
|
|
- [x] API theme/layout/assignment flow
|
|
- [x] Tenant isolation + optimistic lock
|
|
- [x] Architecture / permission / migration / docs
|
|
|
|
## Completion Criteria
|
|
|
|
- [x] Theme and layout APIs + tests green
|
|
- [x] No template catalog engine
|
|
- [x] Docs / manifests / handover updated
|
|
|
|
## Related Documents
|
|
|
|
- [Handover](phase-handover/phase-11-3.md)
|
|
- [Phase 11.2](experience-phase-11-2.md)
|
|
- [Experience Roadmap](experience-roadmap.md)
|
|
- [ADR-016](architecture/adr/ADR-016.md)
|
|
- [ADR-008](architecture/adr/ADR-008.md)
|