Conduct architecture reviews that catch problems early without becoming bureaucratic bottlenecks. Covers review triggers, lightweight RFC processes, decision frameworks, review checklists, and scaling reviews across multiple teams.
Architecture reviews are the central mechanism for aligning engineering teams on long-term technical direction. They happen when a team is designing a new system, re-architecting an existing one, or evaluating a significant technology shift. A review is not a meeting—it is a process that begins weeks before a meeting, continues through a focused session, and concludes with documented decisions and follow-up actions. The goal is to ensure that architectural choices are evaluated, challenged, and agreed upon before implementation begins.
A review fails when participants arrive unprepared. The most common failure is a PDF of diagrams with no context: “Here is the architecture. What do you think?” The right way to prepare is to produce a decision record that includes the problem, alternatives, trade-offs, and rationale. This record must be the primary artifact.
The decision record is a markdown file in docs/decisions/2024-04-15-frontend-rewrite.md. It contains the following sections:
## Problem
Users report slow load times for the dashboard. Initial load is 3.8s on 3G, and navigation between views takes 1.5s on average.
## Context
- Current stack: Angular 11 with server-side rendering via Express
- 40% of users are on mobile devices with intermittent connectivity
- Team is already familiar with React but not with server components
## Alternatives
1. **Rewrite with React + Server Components**
- Pros: Faster TTFB, better hydration, improved developer experience
- Cons: Requires new build pipeline, learning curve for server components
2. **Enhance Angular with Ivy and Web Workers**
- Pros: Minimal disruption, reuses existing codebase
- Cons: Limited performance gains, no true server-side rendering
3. **Migrate to Svelte + Sapper**
- Pros: Small bundle size, excellent performance
- Cons: Steep learning curve, less ecosystem maturity
## Evaluation
| Criteria | React + SC | Angular + Ivy | Svelte + Sapper |
|------------------|------------|----------------|-----------------|
| TTFB < 1s | ✅ | ❌ | ✅ |
| Bundle size < 500kB | ✅ | ✅ | ✅ |
| Developer onboarding | ✅ | ✅ | ❌ |
| Long-term maintainability | ✅ | ✅ | ✅ |
## Decision
Choose React + Server Components. It achieves the TTFB goal, scales well, and aligns with the team’s growth path.
## Rationale
Server components reduce initial payload by 40%, and the team has already built two prototype apps using this pattern. The increased developer velocity offsets the initial ramp-up cost within six months.This document is reviewed by the team lead three days before the review meeting. The reviewer adds comments directly in the file using GitHub’s inline comments. The review is published as a pull request titled docs: add decision record for frontend rewrite.
The review meeting itself is a 90-point session, structured in three parts: review, discussion, and decision.
The session begins with a 15-minute presentation. The presenter uses a single slide deck exported as a PDF and shares it via screen sharing. The deck is built with decktape and includes:
npx decktape -p 1024x768 --slide 1 --output slides.pdf --format pdf --delay 3000 --wait 5000 \
--theme dark --title "Frontend Rewrite" \
https://example.com/slidesThe deck includes:
The presenter walks through the decision record, highlighting the problem, alternatives, and evaluation matrix. The review phase ends with a single question: “What is the single most important thing you want us to focus on during discussion?”
The discussion is driven by a shared document, created as a Google Doc or in a Notion page. The document has a table of review items with the following columns:
| Item | Owner | Status | Feedback | Action Items |
|---|---|---|---|---|
| High-level data flow | Alice | Open | Diagram is missing error handling | Update diagram to include retry logic |
| Server component hydration strategy | Bob | In Review | Consider using useClient in nested components | Add two examples with useClient and useServer |
Each item includes:
Participants use a decision matrix to evaluate the architecture against five criteria:
For each criterion, the team votes using a digital whiteboard tool (e.g., Miro or Figma). The voting is done via a shared canvas with sticky notes. Each participant places three sticky notes:
The most common failure in discussion is rehashing the problem instead of focusing on the architecture. To avoid this, the facilitator enforces a 10-minute rule: every discussion must include at least one question that starts with “How does this design handle…” followed by one of the five criteria.
The decision phase begins with a decision ballot. The facilitator posts a simple form with the following questions:
Each reviewer votes Yes, No, or Conditional (with a reason). The votes are collected in a shared spreadsheet or via a simple HTTP POST:
POST /api/v1/reviews/2024-04-15/votes
{
"review_id": "2024-04-15",
"reviewer": "[email protected]",
"votes": {
"primary_goal": "yes",
"tradeoffs_justified": "yes",
"incremental_path": "yes",
"biggest_risk": "microservices need strong observability; current setup lacks distributed tracing"
}
}The facilitator compiles the results and leads a discussion on the top three concerns. The session ends with a commitment statement:
> “We commit to this architecture as the foundation for the next 18 months. We will implement it in the following phases: [phase 1, phase 2, phase 3]. We will review it again in six months.”
The review does not end when the meeting ends. The following actions are tracked in a shared project board (e.g., GitHub Projects or Linear):
The decision record is updated based on the discussion. The team adds:
The final version is merged into main and tagged as v1.0.
The decision record is transformed into an ADR using adr-tool. The tool generates a new file in adr/0001-frontend-rewrite.md with the following structure:
---
title: Frontend Rewrite Using React and Server Components
status: reviewed
created: 2024-04-15
---
## Context
The frontend is slow and difficult to maintain. Users on mobile devices experience high latency.
## Decision
We will rewrite the frontend using React with server components.
## Consequences
- Improved TTFB from 3.8s to 0.9s
- Reduced bundle size by 40%
- Increased team velocity by 25% after the first quarterThe tool enforces:
adr/YYYY-MM-DD-title.md)A review tracking sheet is maintained in a Google Sheet with the following columns:
| Feature | Owner | Start Date | Due Date | Status | Link to PR | Review Status |
|---|---|---|---|---|---|---|
| Initial layout | Alice | 2024-04-22 | 2024-05-15 | In Progress | github.com/teams/web/pull/102 | Reviewed |
| Server components | Bob | 2024-04-25 | 2024-06-01 | Not Started | github.com/teams/web/pull/103 | Pending |
The sheet is updated weekly. Each row includes:
The most frequent failures in architecture reviews are:
The diagram is too high-level. A common fix is to add “zoom-in” diagrams for critical components. For example, the high-level data flow is expanded into a detailed diagram of the event processing pipeline, showing:
Scalability refers to the ability to handle increasing load with minimal effort. Performance refers to speed under a given load. The team must distinguish:
The architecture must specify:
A review fails when it concludes with “We like this design.” The decision must be explicit: “This architecture is approved. It will be the standard for all new services.”
The most effective reviews take at least four weeks: two weeks for preparation, one week for discussion, and one week for follow-up. A common mistake is scheduling the review too close to implementation.
Architecture reviews are not one-off events. They are part of a continuous cycle:
docs/reviews/.The review process is validated by a review health check:
curl -s http://api.engineering/health/reviews \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
| jq '.reviews | length, .avg_days_to_decision, .completed_percentage'The output is:
{
"reviews": 24,
"avg_days_to_decision": 37.2,
"completed_percentage": 83.3
}This check is run monthly. If the average time exceeds 30 days, the team revisits the review preparation phase.
An effective architecture review is not a meeting—it is a process. It begins with a well-crafted decision record, is driven by structured discussion, and culminates in a documented decision with clear follow-up. The key to success is consistency: every review follows the same pattern, uses the same tools, and produces the same artifacts. The process is not dependent on a single platform or tool. It is a pattern that can be applied across any engineering organization, regardless of stack or scale.
This page was rewritten on 17 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.
We use cookies for analytics (Google Analytics) and advertising (Google AdSense) to improve your experience and support free content. Privacy Policy