Architecture review template
A structured framework for evaluating architecture decisions before they become technical debt.
An architecture review evaluates how well a system's structure supports its current and planned requirements. This template is for developers and technical leads who need to assess an existing system or review a proposed architecture.
The output is a decision-support document. It identifies strengths, risks, and specific recommendations. Keep it under 3 pages.
Review scope and goals
Define what you are reviewing and why. Include the review trigger (acquisition, migration, performance issue) and specific questions to answer.
Example
Scope: Full architecture review of the OrderService microservice. Trigger: The service has experienced 3 outages in the past month. The team needs to assess whether the current architecture can support 10x traffic growth planned for Q3. Goals: 1. Identify root causes of recent instability. 2. Evaluate scalability of the current design. 3. Recommend changes for the Q3 growth target.
System context
Where the system sits in the broader landscape. What systems does it interact with? Who are the users?
Example
OrderService handles order creation, payment processing, and fulfillment tracking. It receives orders from the web frontend and mobile app (via API Gateway), processes payments through Stripe, updates inventory in InventoryService, and sends notifications via NotificationService. Traffic: ~500 orders/hour during normal periods, ~5,000 orders/hour during flash sales.
Current architecture
Document the existing architecture with diagrams. Include components, communication patterns, data stores, and deployment topology.
Example
Components: - API layer: Express.js service running on ECS Fargate (2 instances) - Business logic: Monolithic service in the same process - Database: RDS PostgreSQL (db.r5.large, single AZ) - Message queue: SQS for async fulfillment processing - Cache: No caching layer [Include architecture diagram - use CodeDashboard to generate this automatically]
Quality attribute analysis
Evaluate the architecture against key quality attributes: performance, scalability, reliability, security, and maintainability.
Example
Performance: Average response time is 200ms for order creation. P99 is 1.2s during peak traffic, which exceeds the 500ms SLA. Scalability: ECS auto-scaling is configured but the database is a single instance with no read replicas. The database is the bottleneck during flash sales. Reliability: Single-AZ database deployment means a zone failure takes down the entire service. No circuit breakers between services. Security: API authentication via JWT. Input validation present but inconsistent across endpoints. No rate limiting. Maintainability: Monolithic service with 45,000 lines of code in a single project. No clear module boundaries. Test coverage at 34%.
Risks identified
Specific risks with severity (high/medium/low) and the evidence supporting each.
Example
1. [HIGH] Single-AZ database: A zone failure will cause complete service outage. This caused the Feb 3 outage. 2. [HIGH] No read replicas: All queries hit the primary instance. Database CPU reaches 90% during flash sales. 3. [MEDIUM] No circuit breakers: InventoryService downtime cascades to OrderService, causing timeouts and error responses. 4. [MEDIUM] Monolithic codebase: Changes to payment logic require deploying the entire service, increasing deployment risk. 5. [LOW] No rate limiting: The API is vulnerable to abuse, though no incidents have occurred yet.
Recommendations
Specific, actionable recommendations prioritized by impact and effort. Each recommendation should address a specific risk.
Example
Immediate (this sprint): 1. Enable Multi-AZ for RDS. Addresses Risk #1. Estimated effort: 2 hours, requires a maintenance window. 2. Add a read replica for query traffic. Addresses Risk #2. Estimated effort: 4 hours. Short-term (next 2 sprints): 3. Add circuit breakers for InventoryService and NotificationService calls. Addresses Risk #3. Use the existing resilience4j dependency. Medium-term (next quarter): 4. Extract payment processing into a separate service. Addresses Risk #4. This reduces deployment scope and allows independent scaling.
Trade-offs and alternatives considered
Document alternatives you considered and why you chose the recommended approach.
Example
Alternative to recommendation #4: Instead of extracting a payment microservice, we considered adding module boundaries within the monolith (modular monolith pattern). This is less effort but does not solve the independent scaling requirement for Q3. We recommend extraction because the payment module has distinct scaling characteristics and a clear API boundary.
Automate this with CodeDashboard
CodeDashboard generates the "current architecture" section automatically with architecture diagrams, component summaries, and tech stack analysis. Use it as the starting point for your review. The quality attribute analysis, risk identification, and recommendations require human judgment and cannot be fully automated.
Get this template as Markdown
Related templates
Codebase overview template
The document every new developer wishes they had on day one.
Software handover document template
Copy this template and fill it in. Or let CodeDashboard generate most of it for you.
Technical documentation template
The documentation structure that covers what developers actually need to know.
Try CodeDashboard free for 7 days
Paste a GitHub URL and get a full visual dashboard in under 2 minutes. No credit card required for free accounts.