# Headless Architecture Decision Canvas

Use this canvas before choosing a CMS, framework, or hosting platform. Replace the example prompts with evidence from your business, then keep the completed file as an architecture decision record.

## 1. Decision statement

- Decision owner:
- Review date:
- Decision deadline:
- Current architecture:
- Proposed boundary:
- Business outcome this separation must improve:
- What will not change:

## 2. Readiness gates

Mark each statement **Yes**, **No**, or **Unknown**. An unknown is work to complete, not a soft yes.

| Gate | Yes / No / Unknown | Evidence | Owner |
|---|---|---|---|
| The same governed content or capability must serve at least two real experiences. |  |  |  |
| A template or integrated platform is blocking a named, valuable requirement. |  |  |  |
| The team can own a frontend release and dependency lifecycle. |  |  |  |
| API authentication, authorization, rate limits, and failure behavior are understood. |  |  |  |
| Editors have a tested draft preview and rollback path. |  |  |  |
| Cache invalidation and freshness rules are defined for every public route type. |  |  |  |
| Monitoring covers the frontend, API boundary, upstream services, and publishing pipeline. |  |  |  |
| The three-year cost includes internal engineering and incident response. |  |  |  |

## 3. Route delivery matrix

Choose a delivery pattern route by route. “Headless” does not require one rendering strategy for the entire site.

| Route or template | Audience | Freshness requirement | Personalization | Indexable HTML required? | Proposed pattern | Cache / invalidation rule | Failure fallback |
|---|---|---|---|---|---|---|---|
| Example: article | Public | Minutes | None | Yes | Static or cached server rendering | Revalidate on publish | Serve last known good version |
|  |  |  |  |  |  |  |  |
|  |  |  |  |  |  |  |  |
|  |  |  |  |  |  |  |  |

## 4. Service boundary register

| Capability | System of record | Adapter owner | Auth method | Rate / quota limit | Timeout and retry rule | Degraded behavior | Exit / replacement path |
|---|---|---|---|---|---|---|---|
| Content |  |  |  |  |  |  |  |
| Search |  |  |  |  |  |  |  |
| Commerce |  |  |  |  |  |  |  |
| Identity |  |  |  |  |  |  |  |
| Analytics |  |  |  |  |  |  |  |

## 5. Editorial operating test

- [ ] An editor can create, preview, schedule, publish, correct, and roll back without production access.
- [ ] Preview resolves references, locales, permissions, and unpublished linked records correctly.
- [ ] A schema change has a migration plan and compatibility window.
- [ ] Publishing triggers invalidate the intended content—and nothing broader than necessary.
- [ ] Broken references, missing required fields, and invalid metadata fail before release.

## 6. One-slice prototype

- Journey or content type:
- Representative market and device:
- Real upstream dependencies:
- Success criteria:
- Failure scenarios to test:
- Observability required before launch:
- Rollback mechanism:
- Result and decision:

## 7. Lifecycle-cost inventory

| Cost area | Year 1 | Years 2–3 | Assumption / source |
|---|---:|---:|---|
| CMS and service licenses |  |  |  |
| Frontend hosting and CDN |  |  |  |
| Build, preview, and deployment infrastructure |  |  |  |
| Migration and content restructuring |  |  |  |
| Engineering, QA, security, and accessibility |  |  |  |
| Monitoring and incident response |  |  |  |
| Vendor and framework upgrades |  |  |  |

## 8. Decision record

- **Decision:** Adopt / pilot / defer / reject
- **Why now:**
- **Evidence that mattered most:**
- **Risks accepted:**
- **Conditions that would reverse this decision:**
- **Next review date:**