Phase Handover — Experience 11.4 Template System
Metadata
| Field |
Value |
| Phase ID |
experience-11.4 |
| Title |
Template System |
| Status |
Complete |
| Service(s) |
experience (experience_db) |
| Version |
0.11.4.0 |
| Date |
2026-07-26 |
| ADR(s) |
ADR-016, ADR-008 |
Discovery Summary
Prior phase delivered replaceable themes and dynamic layouts. The Phase 11.4 template scaffolding (models, services, schemas, repositories, commands/queries, policies/validators/specifications, and APIs) already existed on disk from earlier work but was intentionally unwired — models excluded from app/models/__init__.py, routers unmounted, and the Alembic revision suffixed .py.future — as part of the Phase 11.3 repair so the Alembic head stayed pinned to 0004. This phase re-wired that scaffolding: restored the migration, imported the models, mounted the routers, aligned events/permissions/capabilities, and added the phase 11.4 test suite.
Reusable Components
| Component |
Location |
Reuse notes |
| Template catalog + versions |
app/models/templates.py (ExperienceTemplate, ExperienceTemplateVersion), app/services/templates.py |
blueprint_json immutable once published; mirrors the Phase 11.2/11.3 catalog+immutable-version pattern |
| Instantiation |
TemplateInstantiation, ExperienceTemplateService.instantiate |
Creates an ExperiencePage from a published version's blueprint; records theme/layout readiness without owning those engines |
| Policies / specs |
app/policies/templates.py, app/specifications/templates.py |
Lifecycle + version-immutability + instantiation-eligibility rules, list UX |
| Validators |
app/validators/templates.py |
page_type validation, status-transition tables, blueprint_json shape checks |
Public APIs
| Method |
Path |
Permission |
| CRUD + activate/deprecate/archive/delete |
/api/v1/templates |
experience.templates.* |
| CRUD + publish/retire |
/api/v1/template-versions |
experience.templates.* |
| Instantiate / list / get |
/api/v1/template-instantiations |
experience.templates.* |
Events
| Event type |
Notes |
experience.template.* |
Template catalog lifecycle (created/updated/activated/deprecated/archived) |
experience.template_version.* |
Template version created/updated/published/retired |
experience.template.instantiated |
Emitted after a page is successfully created from a published version |
Extension Points
| Extension point |
How to extend |
Forbidden uses |
ExperienceTemplateVersion.blueprint_json |
page_type, content_shell, seo_shell, theme_id, layout_id, placement_shells — consumed at instantiation time |
Store full CMS blobs / binary media |
TemplateInstantiation.result_json |
Records whether the referenced theme/layout were ready and applied |
Do not use as a source of truth for theme/layout state — always re-read the theme/layout catalogs |
TemplateInstantiationPolicy / TemplateVersionPolicy |
Gate instantiation to published, non-deleted templates/versions |
Do not bypass via direct repository writes |
Known Limitations
- No forms/surveys/appointment engine (11.6)
- No localization/media-ref pipeline for template content yet (11.5)
- Instantiation only references theme/layout by id; it does not validate deep compatibility beyond active/published status
- Metrics remain discovery-oriented
Migration Notes
| Item |
Detail |
| Alembic revision(s) |
0005_phase_114_templates (head) |
| Upgrade steps |
alembic upgrade head |
| Downgrade support |
Drops experience_template_instantiations, experience_template_versions, experience_templates |
| Breaking changes |
None (additive) |
Dependencies
| Dependency |
Type |
| experience-11.3 themes/layouts |
Required prior (referenced by id from template blueprints) |
| experience-11.1 sites/pages |
Required prior (instantiation creates an ExperiencePage) |
| ADR-016 / ADR-008 |
Boundaries / branding |
Quality Gates
Next Phase Entry
| Field |
Value |
| Recommended next phase |
experience-11.5 Localization, RTL/LTR & Media |
| Entry checklist |
Read this handover + phase doc; implement locale profiles content/media refs only — no forms/surveys/appointments yet |
Completion Sign-Off
Related Documents
203671a7bf