Completed ADR Examples
Why this appendix matters
Templates are useful, but engineers learn architecture writing faster from completed examples. These ADRs show the expected level of specificity: context, constraints, alternatives, tradeoffs, decision, verification, rollback, and follow-up.
Use these examples as calibration, not as copy-paste policy.
Example ADR: Hybrid rendering for a lead funnel
Context
The acquisition team needs to launch campaign-specific landing pages with fast mobile load time, safe experiment routing, and a multi-step qualification form. Paid traffic is mostly mobile. Previous landing pages accumulated third-party scripts and client-rendered personalization, causing weak LCP and occasional form abandonment during slow network conditions.
Decision
Use static generation for the stable content shell, edge routing for campaign and experiment assignment, and a selectively hydrated form island for qualification. Keep analytics and personalization outside the critical rendering path. Serve hashed assets with immutable caching and keep HTML on short revalidation.
Alternatives considered
| Alternative | Why rejected |
|---|---|
| Full CSR landing page | Too much JavaScript before useful content; weaker LCP and SEO. |
| Per-request SSR for every variant | Higher compute cost and unnecessary origin dependency for mostly static content. |
| Client-side experiment assignment | Causes flicker, attribution risk, and delayed variant rendering. |
Tradeoff analysis
| Benefit | Cost |
|---|---|
| Fast first useful view | More build/revalidation coordination. |
| Cacheable variants | Experiment and campaign cache keys must be correct. |
| Smaller hydration surface | Form island boundaries need explicit state and validation design. |
| Safer third-party loading | Growth team must accept script governance and kill switches. |
Verification
- p75 mobile LCP under 2.5s for paid traffic.
- p75 INP under 200ms for form step changes.
- CLS under 0.1.
- Edge logs include campaign, variant, cache status, release, and request id.
- Third-party scripts have owner, purpose, loading strategy, and kill switch.
Rollback
Disable new variant routing at the edge and route traffic to the previous stable variant. Keep static assets for at least one full rollback window so HTML never points at missing files.
Follow-up
- Add automated budget checks for route JS and image weight.
- Add experiment cache-key tests.
- Review third-party register every campaign cycle.
Example ADR: GenUI component registry
Context
The operations copilot needs to render task-specific UI such as policy summaries, comparison tables, approval panels, and task checklists. Letting the model output arbitrary markdown or component names would create accessibility, security, and product consistency risk.
Decision
Create a server-owned GenUI registry with versioned component schemas. The model may request only registered component types. The backend validates model output before streaming component events to the browser. The frontend renderer maps valid schema payloads to design-system components and falls back to a safe text/card state when validation fails.
Alternatives considered
| Alternative | Why rejected |
|---|---|
| Free-form markdown | Too weak for interactive workflows and unsafe for complex UI. |
| Model-generated React/code | Unacceptable execution and supply-chain risk. |
| Frontend-only validation | Too late; invalid or unsafe payloads should be blocked at the orchestration boundary. |
Tradeoff analysis
| Benefit | Cost |
|---|---|
| Safe bounded UI generation | Registry requires governance and versioning. |
| Accessible components by default | Component schemas must encode required labels and states. |
| Better evals | Fixtures must be maintained as components evolve. |
| Better observability | Renderer must log validation and fallback events. |
Verification
- Unknown component types are rejected.
- Required accessibility props are enforced.
- Invalid schemas render a deterministic fallback.
- Component payload fixtures are covered by evals.
- Renderer logs component type, schema version, validation result, and fallback reason.
Rollback
Disable generated component rendering for affected schema versions and stream text-only responses with citations and task links.
Follow-up
- Add registry compatibility tests to release CI.
- Add a monthly review of component failure telemetry.
- Add design-system review for every new GenUI component.
Source lens
These examples apply the ADR patterns from Part I and part-xii/adr-templates. Use them as calibration for capstone ADRs, route architecture notes, and platform governance decisions.