Architecture Review

Conduct rigorous architectural reviews that blend enterprise governance with modern, agent-friendly development patterns. Produce decisions that are documented, defensible, and immediately actionable.

Core Philosophy

Make decisions explicit. Every significant choice becomes an ADR. Guardrails over gates. Provide golden paths and reference architectures, not bureaucratic approval queues. Agent-native from day one. Structure projects so AI agents can understand, modify, and extend them reliably. Start right, stay lean. Enterprise-grade foundations without enterprise-grade overhead.

Quick Start: New Project Review

When starting a new project, run through these phases in order:

Phase 1: Strategic Alignment (5 min)

Answer these before touching code:

1. What problem does this solve? One sentence.
2. Who are the users? Primary persona + scale expectations.
3. What are the constraints? Budget, timeline, team size, compliance requirements.
4. What exists already? Existing services, data stores, or platforms to integrate with.
5. What is the deployment target? Cloud provider, on-prem, edge, hybrid.

Phase 2: Architecture Decision Cascade

Work through these decisions in order. Each produces an ADR.

Phase 3: Scaffold and Ship

After decisions are made, generate the project structure. See [project-scaffolding.md](references/project-scaffolding.md) for the canonical directory layout and day-one checklist.

Architecture Decision Record Template

Every significant decision gets an ADR. Store in docs/adr/ with sequential numbering.

# ADR-NNNN: [Short Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## Context
What forces are at play? What is the problem?

## Decision Drivers
- Key factor 1
- Key factor 2

## Considered Options
1. **Option A** -- pros / cons
2. **Option B** -- pros / cons

## Decision
What we chose and why.

## Consequences
What becomes easier. What becomes harder. What risks remain.

Rules:

• One decision per ADR. Never combine.
• Immutable once accepted -- supersede, don't edit.
• Keep under 2 pages. Alternatives considered is the most valuable section.
• Link related ADRs to create a decision graph.

Quality Attributes Checklist

Evaluate every architecture against these attributes. Score each as: Addressed / Planned / Not Applicable / Risk.

Anti-Patterns to Flag

Reject architectures exhibiting these patterns:

Review Outcomes

Every review produces one of these decisions:

Reference Materials

• [Architecture Patterns](references/architecture-patterns.md) -- Hexagonal, DDD, modular monolith, microservices decision framework
• [API and Data Architecture](references/api-and-data.md) -- REST/GraphQL/gRPC, database selection, caching, event streaming
• [Security and Compliance](references/security-and-compliance.md) -- Zero trust, OWASP, auth patterns, supply chain, compliance
• [DevOps and Quality](references/devops-and-quality.md) -- CI/CD, observability, testing strategies, resilience patterns
• [Agentic Patterns](references/agentic-patterns.md) -- Agent-native project structure, CLAUDE.md, parallel work, quality gates
• [Project Scaffolding](references/project-scaffolding.md) -- Day-one directory structure, checklist, and timeline