Tutorial: Run a Frontend Architecture Review Program
Why this tutorial matters
Architecture work fails when it stays inside one architect's head. Teams need a review program that turns decisions into visible artifacts, reusable checklists, scorecards, and follow-up actions without becoming bureaucracy.
This tutorial builds a practical Frontend Architecture Review Program for a mid-sized product organization.
What you will build
| Artifact | Purpose |
|---|---|
| intake template | capture proposed change and risk |
| ADR template | record important decisions |
| RFC process | review cross-team changes |
| scorecards | track health and ownership |
| review checklists | performance/security/accessibility/design system |
| exception register | manage deviations with expiry |
| postmortem loop | turn incidents into architecture controls |
Milestone 1: Define review scope
Not every change needs architecture review.
Review required when a change:
- affects shared rendering/data architecture
- adds a third-party script
- changes auth/session behavior
- introduces new generated UI or AI tool action
- changes design-system primitives
- crosses team boundaries
- affects Core Web Vitals on critical routes
- creates a long-lived exception
No review required for:
- local feature UI using established patterns
- copy/content changes inside approved templates
- small bug fixes with no contract change
Acceptance criteria:
- teams know when review is required
- review scope is risk-based, not title-based
Milestone 2: Create intake
Use a one-page intake:
# Architecture Review Intake
## Change
What are we changing?
## User impact
Who is affected and how?
## Risk areas
- Performance:
- Accessibility:
- Security:
- Reliability:
- Data/rendering:
- Design system:
## Reversibility
How do we roll back or degrade?
## Decision needed
What question should reviewers answer?
Acceptance criteria:
- reviewers can understand the risk in five minutes
- teams are not forced to write a long document for low-risk changes
Milestone 3: ADR workflow
ADR required for decisions that are hard to reverse or teach.
ADR sections:
- context
- decision
- alternatives
- tradeoffs
- consequences
- owner
- review date
- links to metrics/incidents
Rules:
- ADRs are short
- rejected alternatives are included
- review date is explicit
- ADRs link to implementation PRs
Milestone 4: RFC workflow
Use RFCs for cross-team or platform-level changes.
RFC phases:
- draft
- review
- decision
- implementation
- adoption
- follow-up
Decision record:
| Field | Purpose |
|---|---|
| status | proposed, accepted, rejected, superseded |
| owner | accountable person/team |
| affected teams | adoption planning |
| migration plan | prevents orphaned old paths |
| success metrics | makes decision testable |
| rollback | protects production |
Milestone 5: Scorecards
Create route/system scorecards.
| Scorecard | Example metrics |
|---|---|
| performance | LCP, INP, CLS, JS KB, request count |
| security | CSP status, third-party owners, dependency risk |
| accessibility | automated violations, manual test coverage, known defects |
| reliability | error rate, degraded-mode coverage, incident count |
| design system | component adoption, token usage, overrides |
| AI/GenUI | invalid schema rate, approval rate, tool failures, eval pass rate |
Scorecards should show ownership and trend, not just numbers.
Milestone 6: Exception register
Every exception needs:
type ArchitectureException = {
id: string;
rule: string;
reason: string;
owner: string;
createdAt: string;
expiresAt: string;
mitigation: string;
};
Examples:
- route exceeds JS budget until migration completes
- third-party script allowed for campaign period
- CSP temporarily allows one external domain
- design-system escape hatch used for partner launch
Acceptance criteria:
- exceptions expire
- owners are visible
- expired exceptions are reviewed
Milestone 7: Review meeting format
Keep meetings short:
- decision needed
- risk summary
- alternatives
- tradeoffs
- decision or required follow-up
Do not use review meetings for live document reading. Documents must be readable before the meeting.
Milestone 8: Incident-to-architecture loop
After an incident, ask:
- which architecture boundary failed?
- what signal should have detected it earlier?
- what default would prevent recurrence?
- what checklist needs a new item?
- what test/eval/CI gate should be added?
- what ADR/RFC should be updated?
This converts incidents into institutional learning instead of blame.
Program health metrics
Track:
- review cycle time
- number of expired exceptions
- recurring issue categories
- ADRs without review date
- scorecard coverage
- incident follow-up completion
- teams using templates without architect handholding
The goal is not more reviews. The goal is better decisions with less repeated explanation.
Review checklist library
Create short checklists, not giant forms.
Performance:
- route budget changed?
- LCP element affected?
- new JavaScript or third-party domain?
- new client-side experiment/personalization?
- rollback path?
Security:
- new script, iframe, rich text, generated UI, or auth boundary?
- CSP/security headers affected?
- sensitive data in browser/cache/logs?
- server validation present?
Accessibility:
- keyboard path tested?
- focus behavior changed?
- async status announced?
- error messages associated?
- color/contrast checked?
Design system:
- uses existing primitives?
- new component justified?
- tokens used correctly?
- escape hatch documented?
AI/GenUI:
- model can only propose allowed outputs?
- generated UI schema validated?
- retrieval permissions enforced?
- tools classified by side effect?
- evals updated?
Example review: edge-routed GenUI landing page
Intake summary:
- AI generates landing page variants from ad intent.
- Humans approve variants.
- Edge middleware routes to static variant path.
- Small form island hydrates.
Review findings:
- performance review requires CDN cache key proof
- security review requires no user data in cache key
- accessibility review requires generated variant templates pass checks
- design-system review requires approved section components
- AI review requires source/copy policy and human approval record
Decision:
- approved for one route with three variants
- variant expansion requires separate review
- rollback flag must disable edge rewrite
- metrics: LCP, INP, conversion, invalid variant, cache hit ratio
Operating cadence
| Cadence | Activity |
|---|---|
| weekly | review high-risk intakes |
| biweekly | review scorecard regressions |
| monthly | expired exceptions review |
| quarterly | architecture standards update |
| after incidents | postmortem-to-checklist update |
Keep cadence predictable. Ad hoc architecture review becomes either a bottleneck or an afterthought.
Capstone exercise
Run the program on three proposals:
- Add a new analytics vendor.
- Introduce generated UI into a customer workflow.
- Move a high-traffic route from SSR to edge-routed static variants.
For each, produce:
- intake
- ADR or RFC
- risk checklist
- scorecard entry
- exception if needed
- follow-up review date
Source lens
This tutorial is synthesized from the book's ADR templates, architecture review checklists, NFR templates, source-derived review playbooks, incident postmortem templates, and governance chapters.