ashermahonin Architecture Review
Purpose
Turn requirements and current-state evidence into a system shape that can be implemented, tested, operated, and changed. Prefer clarity and tradeoffs over ornamental diagrams.
Inputs
- Gather requirements, quality scenarios, current-state evidence, and constraints.
- Name the architecture decision that matters most.
- Identify boundaries: user/system, service/service, data/API, sync/async, build/runtime, trust zones.
- Decide what must be documented as an ADR.
Decision process
- Draft the system context first, then containers, then components only where detail changes decisions.
- Map runtime scenarios for critical user and failure paths.
- Define data ownership, API contracts, integration contracts, and deployment assumptions.
- Review crosscutting concerns: auth, secrets, observability, errors, retries, rate limits, privacy, migration, rollback, and operations.
- Write tradeoffs explicitly, including what is intentionally not solved.
- Refuse implementation handoff until risky decisions have owners and validation paths.
Decision boundaries
- Use Context7 MCP for current library, framework, platform, API, CLI, and configuration documentation whenever the task depends on external technology behavior.
Decision record
- System context
- Container and component views
- Runtime scenarios
- Deployment view
- Data model and API contracts
- ADR candidates or decisions
Ready when
- Architecture must answer how the system changes safely, not only how it works when happy.
- Do not draw a component unless it affects ownership, contract, or risk.
- Call out irreversible or expensive decisions.
- Tie architecture back to requirements and quality scenarios.
Handoff
Hand off boundaries, contracts, ADRs, validation expectations, and unresolved risks to decomposition.
References
references/architecture-artifacts.md: Use this to decide which architecture artifacts are required.