Designing Architecture Architecture Decision Workflow
Copy this checklist and track progress:
Architecture Design Progress: - [ ] Step 1: Understand requirements and constraints - [ ] Step 2: Assess project size and team capabilities - [ ] Step 3: Select architecture pattern - [ ] Step 4: Define directory structure - [ ] Step 5: Document trade-offs and decision - [ ] Step 6: Validate against decision framework
Pattern Selection Guide By Project Size Size Recommended Pattern Small (<10K LOC) Simple MVC/Layered Medium (10K-100K) Clean Architecture Large (>100K) Modular Monolith or Microservices By Team Size Team Recommended 1-3 devs Monolith with clear modules 4-10 devs Modular Monolith 10+ devs Microservices (if justified) Common Patterns 1. Layered Architecture ┌─────────────────────────────┐ │ Presentation │ ← UI, API Controllers ├─────────────────────────────┤ │ Application │ ← Use Cases, Services ├─────────────────────────────┤ │ Domain │ ← Business Logic, Entities ├─────────────────────────────┤ │ Infrastructure │ ← Database, External APIs └─────────────────────────────┘
Use when: Simple CRUD apps, small teams, quick prototypes
- Clean Architecture ┌─────────────────────────────────────┐ │ Frameworks & Drivers │ │ ┌─────────────────────────────┐ │ │ │ Interface Adapters │ │ │ │ ┌─────────────────────┐ │ │ │ │ │ Application │ │ │ │ │ │ ┌─────────────┐ │ │ │ │ │ │ │ Domain │ │ │ │ │ │ │ └─────────────┘ │ │ │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────┘ │ └─────────────────────────────────────┘
Use when: Complex business logic, long-lived projects, testability is key
- Hexagonal (Ports & Adapters) ┌──────────┐ │ HTTP API │ └────┬─────┘ │ Port ┌────────▼────────┐ │ │ │ Application │ │ Core │ │ │ └────────┬────────┘ │ Port ┌────▼─────┐ │ Database │ └──────────┘
Use when: Need to swap external dependencies, multiple entry points
- Event-Driven Architecture Producer → Event Bus → Consumer │ ├─→ Consumer │ └─→ Consumer
Use when: Loose coupling needed, async processing, scalability
- CQRS (Command Query Responsibility Segregation) ┌─────────────┐ ┌─────────────┐ │ Commands │ │ Queries │ │ (Write) │ │ (Read) │ └──────┬──────┘ └──────┬──────┘ │ │ ▼ ▼ Write Model Read Model │ │ └────────┬───────────┘ ▼ Event Store
Use when: Different read/write scaling, complex domains, event sourcing
Directory Structure Patterns Feature-Based (Recommended for medium+) src/ ├── features/ │ ├── users/ │ │ ├── api/ │ │ ├── components/ │ │ ├── hooks/ │ │ ├── services/ │ │ └── types/ │ └── orders/ │ ├── api/ │ ├── components/ │ └── ... ├── shared/ │ ├── components/ │ ├── hooks/ │ └── utils/ └── app/ └── ...
Layer-Based (Simple apps) src/ ├── controllers/ ├── services/ ├── models/ ├── repositories/ └── utils/
Decision Framework
When making architectural decisions, evaluate against these criteria:
Simplicity - Start simple, evolve when needed Team Skills - Match architecture to team capabilities Requirements - Let business needs drive decisions Scalability - Consider growth trajectory Maintainability - Optimize for change Trade-off Analysis Template
Use this template to document architectural decisions:
Decision: [What we're deciding]
Context
[Why this decision is needed now]
Options Considered
- Option A: [Description]
- Option B: [Description]
Trade-offs
| Criteria | Option A | Option B |
|----------|----------|----------|
| Complexity | Low | High |
| Scalability | Medium | High |
| Team familiarity | High | Low |
Decision
We chose [Option] because [reasoning].
Consequences
- [What this enables]
- [What this constrains]
Validation Checklist
After selecting an architecture, validate against:
Architecture Validation: - [ ] Matches project size and complexity - [ ] Aligns with team skills and experience - [ ] Supports current requirements - [ ] Allows for anticipated growth - [ ] Dependencies flow inward (core has no external deps) - [ ] Clear boundaries between modules/layers - [ ] Testing strategy is feasible - [ ] Trade-offs are documented
If validation fails, reconsider the pattern selection or adjust the implementation approach.