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