Architecture Review Skill

Overview

Architecture decisions are expensive to change later. This skill guides systematic architectural review and design before committing to implementation.

Core principle: Understand trade-offs BEFORE building. The cheapest architecture change is the one made before code is written.

The Architecture Review Process

Phase 1: Requirements Understanding

Before proposing ANY architecture:

1. Clarify Functional Requirements

   • What must the system DO?
   • What are the critical user flows?
   • What data needs to be stored/processed?

2. Identify Quality Attributes

   • Performance: What latency/throughput is acceptable?
   • Scalability: What growth is expected?
   • Availability: What uptime is required?
   • Security: What data sensitivity levels?

3. Understand Constraints

   • Team size and expertise
   • Timeline and budget
   • Existing systems to integrate with
   • Regulatory or compliance requirements

Phase 2: Design Exploration

NEVER propose a single solution. Always present options.

1. Generate 2-3 Approaches

   • What's the simplest solution that could work?
   • What's the "industry standard" approach?
   • What's the most scalable/flexible option?

2. Evaluate Trade-offs For each approach, assess:

   • Complexity: How hard to build and maintain?
   • Flexibility: How easy to change later?
   • Risk: What could go wrong?
   • Cost: Development time, infrastructure, operations

3. Present with Recommendation

   • Lead with your recommended option
   • Explain WHY you recommend it
   • Be explicit about trade-offs you're accepting

Phase 3: Validation

Before finalizing:

1. SOLID Check

   • Does the design follow SOLID principles?
   • See references/solid-principles.md for patterns

2. Boundary Check

   • Are responsibilities clearly separated?
   • Are interfaces well-defined?
   • Can components be tested independently?

3. Future-Proofing Check

   • What's likely to change?
   • Is the design flexible where it needs to be?
   • Is it simple where change is unlikely?

Red Flags - STOP and Reconsider

If you encounter ANY of these, pause and investigate:

Complexity Smells

- More than 3 levels of inheritance
- Circular dependencies between modules
- God classes (>500 lines, >10 methods)
- "Manager", "Handler", "Processor" classes doing everything
- Config files longer than the code they configure

Design Smells

- Copy-paste code across multiple files
- Switch statements on type fields
- Null checks everywhere
- Deep nesting (>3 levels)
- Methods with >5 parameters

Architecture Smells

- Every change requires modifying multiple services
- Can't deploy one component without deploying others
- Can't test without the full system running
- Unclear ownership of functionality
- Data duplicated across services without clear reason

Common Rationalizations - Don't Accept These

Architecture Decision Record Template

For significant decisions, document:

# ADR-001: [Decision Title]

## Status
[Proposed | Accepted | Deprecated | Superseded]

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

## Options Considered
1. **Option A**: [Description]
   - Pros: ...
   - Cons: ...

2. **Option B**: [Description]
   - Pros: ...
   - Cons: ...

## Decision
We chose Option [X] because [reasoning].

## Consequences
- Positive: ...
- Negative: ...
- Risks: ...

Quick Architecture Checklist

Before approving any architectural decision:

• Requirements: Do we understand what we're building and why?
• Options: Have we considered at least 2 approaches?
• Trade-offs: Are we explicit about what we're sacrificing?
• Simplicity: Is this the simplest solution that meets requirements?
• Boundaries: Are responsibilities clearly separated?
• Testability: Can components be tested in isolation?
• Reversibility: How hard is this to change if we're wrong?

Pattern Selection Guide

References

Detailed patterns and examples in references/:

• solid-principles.md - SOLID with anti-patterns and fixes
• design-patterns.md - Common patterns and when to use them
• api-design.md - REST API design principles
• architecture-patterns.md - Monolith, microservices, hexagonal