# 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](../architecture/adr/ADR-016.md), [ADR-008](../architecture/adr/ADR-008.md) |

## 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

- [x] Discovery complete
- [x] Architecture / boundaries preserved
- [x] Tests green
- [x] Documentation + manifests + registries updated
- [x] Self audit: no forms/surveys/CMS leakage; template versions immutable once published

## 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

- [x] Quality gates passed
- [x] Tests green
- [x] Documentation updated
- [x] Progress / next-steps / registries updated
- [x] Self audit completed

## Related Documents

- [Experience Phase 11.4](../experience-phase-11-4.md)
- [Experience Roadmap](../experience-roadmap.md)
- [ADR-016](../architecture/adr/ADR-016.md)
- [ADR-008](../architecture/adr/ADR-008.md)