| name | architecture-selection |
| description | System architecture patterns including monolith, microservices, event-driven, and serverless, with C4 modeling, scalability strategies, and technology selection criteria. Use when designing system architectures, evaluating patterns, or planning scalability. |
Architecture Pattern Selection
Systematic guidance for selecting and implementing architecture patterns that match requirements, team capabilities, and scalability needs.
When to Activate
- Designing new system architectures
- Evaluating monolith vs microservices vs serverless
- Planning scalability strategies
- Selecting technology stacks
- Creating architecture documentation
- Reviewing architecture decisions
Architecture Patterns
Monolithic Architecture
A single deployable unit containing all functionality.
┌─────────────────────────────────────────────────────────────┐
│ Monolithic Application │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Web UI │ │ API Layer │ │ Admin UI │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ ┌───────────────────────┴───────────────────────────┐ │
│ │ Business Logic Layer │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Orders │ │ Users │ │ Products │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └───────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────────────────┴───────────────────────────┐ │
│ │ Data Access Layer │ │
│ └───────────────────────┬───────────────────────────┘ │
│ │ │
└──────────────────────────┼──────────────────────────────────┘
│
┌──────┴──────┐
│ Database │
└─────────────┘
When to Use:
- Small team (< 10 developers)
- Simple domain
- Rapid iteration needed
- Limited infrastructure expertise
Trade-offs:
| Pros | Cons |
|---|---|
| Simple deployment | Limited scalability |
| Easy debugging | Large codebase to manage |
| Single codebase | Technology lock-in |
| Fast development initially | Team coupling |
| Transactional consistency | Full redeploy for changes |
Microservices Architecture
Independently deployable services organized around business capabilities.
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Web UI │ │Mobile │ │ Admin │ │External│
└───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
│ │ │ │
└────────────┴────────────┴────────────┘
│
┌────────┴────────┐
│ API Gateway │
└────────┬────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌───┴───┐ ┌────┴───┐ ┌───┴───┐
│ Order │ │ User │ │Product│
│Service│ │Service │ │Service│
├───────┤ ├────────┤ ├───────┤
│ DB │ │ DB │ │ DB │
└───────┘ └────────┘ └───────┘
│ │ │
└──────────────────┴──────────────────┘
│
┌────────┴────────┐
│ Message Bus │
└─────────────────┘
When to Use:
- Large team (> 20 developers)
- Complex, evolving domain
- Independent scaling needed
- Different tech stacks for different services
- High availability requirements
Trade-offs:
| Pros | Cons |
|---|---|
| Independent deployment | Operational complexity |
| Technology flexibility | Network latency |
| Team autonomy | Distributed debugging |
| Targeted scaling | Data consistency challenges |
| Fault isolation | More infrastructure |
Event-Driven Architecture
Services communicate through events rather than direct calls.
┌─────────────────────────────────────────────────────────────┐
│ Event Bus / Broker │
├─────────────────────────────────────────────────────────────┤
│ │
│ OrderPlaced UserCreated PaymentReceived │
│ │
└──────┬──────────────┬──────────────┬───────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Order │ │ User │ │ Payment │
│ Service │ │ Service │ │ Service │
│ │ │ │ │ │
│ Publishes: │ │ Publishes: │ │ Publishes: │
│ OrderPlaced │ │ UserCreated │ │ PaymentRcvd │
│ │ │ │ │ │
│ Subscribes: │ │ Subscribes: │ │ Subscribes: │
│ PaymentRcvd │ │ OrderPlaced │ │ OrderPlaced │
└─────────────┘ └─────────────┘ └─────────────┘
When to Use:
- Loose coupling required
- Asynchronous processing acceptable
- Complex workflows spanning multiple services
- Audit trail needed
- Event sourcing scenarios
Trade-offs:
| Pros | Cons |
|---|---|
| Temporal decoupling | Eventual consistency |
| Natural audit log | Complex debugging |
| Scalability | Message ordering challenges |
| Extensibility | Infrastructure requirements |
| Resilience | Learning curve |
Serverless Architecture
Functions executed on-demand without managing servers.
┌────────────────────────────────────────────────────────────┐
│ Client │
└────────────────────────────┬───────────────────────────────┘
│
┌────────────────────────────┴───────────────────────────────┐
│ API Gateway │
└────────────────────────────┬───────────────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Function │ │ Function │ │ Function │
│ GetUser │ │CreateOrder│ │ SendEmail│
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Database │ │ Queue │ │ Email │
│ │ │ │ │ Service │
└──────────┘ └──────────┘ └──────────┘
When to Use:
- Variable/unpredictable workloads
- Event-triggered processing
- Cost optimization for low traffic
- Rapid development needed
- Short-running operations
Trade-offs:
| Pros | Cons |
|---|---|
| No server management | Cold start latency |
| Pay-per-use | Execution time limits |
| Auto-scaling | Vendor lock-in |
| Rapid deployment | Complex local development |
| Reduced ops burden | Stateless constraints |
Pattern Selection Guide
| Factor | Monolith | Microservices | Event-Driven | Serverless |
|---|---|---|---|---|
| Team Size | Small (<10) | Large (>20) | Any | Any |
| Domain Complexity | Simple | Complex | Complex | Simple-Medium |
| Scaling Needs | Uniform | Varied | Async | Unpredictable |
| Time to Market | Fast initially | Slower start | Medium | Fast |
| Ops Maturity | Low | High | High | Medium |
C4 Model
Hierarchical way to document architecture at multiple levels of detail.
Level 1: System Context
Shows system in its environment with external actors and systems.
┌──────────────────────────────────────────────────────────────┐
│ System Context Diagram │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Customer │ │ Admin │ │
│ │ [User] │ │ [User] │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ │ Places orders │ Manages │
│ │ │ products │
│ ▼ ▼ │
│ ┌────────────────────────────────────────────────┐ │
│ │ E-Commerce System │ │
│ │ [Software System] │ │
│ └───────────┬─────────────────┬──────────────────┘ │
│ │ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ │
│ │ Payment │ │ Email │ │
│ │ Gateway │ │ Provider │ │
│ │ [External] │ │ [External] │ │
│ └───────────────┘ └───────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
Level 2: Container
Shows the high-level technology choices and how containers communicate.
┌──────────────────────────────────────────────────────────────┐
│ Container Diagram │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Web App │ │ Mobile App │ │
│ │ [React SPA] │ │ [React Native] │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ │ HTTPS │ │
│ └───────────┬───────────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ API Gateway │ │
│ │ [Kong] │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Order │ │ User │ │ Product │ │
│ │ Service │ │ Service │ │ Service │ │
│ │ [Node] │ │ [Node] │ │ [Go] │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Orders │ │ Users │ │Products │ │
│ │ DB │ │ DB │ │ DB │ │
│ │[Postgres│ │[Postgres│ │ [Mongo] │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
Level 3: Component
Shows internal structure of a container.
┌──────────────────────────────────────────────────────────────┐
│ Component Diagram: Order Service │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ API Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ OrdersCtrl │ │ HealthCtrl │ │ MetricsCtrl │ │ │
│ │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────┼─────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────┼─────────────────────────────────────────────┐ │
│ │ ▼ Domain Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │OrderService │ │ OrderCalc │ │ Validators │ │ │
│ │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────┼─────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────┼─────────────────────────────────────────────┐ │
│ │ ▼ Infrastructure Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ OrderRepo │ │PaymentClient│ │ EventPub │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
Level 4: Code
Shows implementation details (class diagrams, sequence diagrams).
Use standard UML when needed at this level.
Scalability Patterns
Horizontal Scaling
Add more instances of the same component.
Load Balancer
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│Instance │ │Instance │ │Instance │
│ 1 │ │ 2 │ │ 3 │
└─────────┘ └─────────┘ └─────────┘
Requirements:
- Stateless services
- Shared session storage
- Database can handle connections
Caching
Reduce load on slow resources.
┌─────────────────────────────────────────────────────┐
│ Caching Layers │
├─────────────────────────────────────────────────────┤
│ │
│ Browser Cache → CDN → App Cache → Database Cache │
│ │
│ Examples: │
│ - Browser: Static assets, API responses │
│ - CDN: Static content, cached API responses │
│ - App: Redis/Memcached for sessions, computed data│
│ - Database: Query cache, connection pooling │
│ │
└─────────────────────────────────────────────────────┘
Cache Invalidation Strategies:
- TTL (Time to Live): Simplest, eventual consistency
- Write-through: Update cache on write
- Write-behind: Async update for performance
- Cache-aside: App manages cache explicitly
Database Scaling
| Strategy | Use Case | Trade-off |
|---|---|---|
| Read Replicas | Read-heavy workloads | Replication lag |
| Sharding | Large datasets | Query complexity |
| Partitioning | Time-series data | Partition management |
| CQRS | Different read/write patterns | System complexity |
Reliability Patterns
| Pattern | Purpose | Implementation |
|---|---|---|
| Circuit Breaker | Prevent cascade failures | Fail fast after threshold |
| Bulkhead | Isolate failures | Separate thread pools |
| Retry | Handle transient failures | Exponential backoff |
| Timeout | Bound wait times | Don't wait forever |
| Rate Limiting | Prevent overload | Throttle requests |
Circuit Breaker States:
┌────────┐
│ CLOSED │ ──── Failure Threshold ──► ┌────────┐
│(normal)│ │ OPEN │
└────────┘ │(failing│
▲ └────┬───┘
│ │
Success Timeout
Threshold │
│ ▼
┌────┴────┐ ┌─────────┐
│HALF-OPEN│ ◄─── Test Request ────── │ │
└─────────┘ └─────────┘
Technology Selection
Selection Criteria
| Criterion | Questions |
|---|---|
| Fit | Does it solve the actual problem? |
| Maturity | Production-proven? Community size? |
| Team Skills | Can the team use it effectively? |
| Performance | Meets requirements? Benchmarks? |
| Operations | How hard to deploy, monitor, debug? |
| Cost | License, infrastructure, learning curve? |
| Lock-in | Exit strategy? Standards compliance? |
| Security | Track record? Compliance certifications? |
Evaluation Matrix
| Technology | Fit | Maturity | Skills | Perf | Ops | Cost | Score |
|------------|-----|----------|--------|------|-----|------|-------|
| Option A | 4 | 5 | 3 | 4 | 4 | 3 | 3.8 |
| Option B | 5 | 3 | 4 | 5 | 2 | 4 | 3.8 |
| Option C | 3 | 4 | 5 | 3 | 5 | 5 | 4.2 |
Weights: Fit(25%), Maturity(15%), Skills(20%), Perf(15%), Ops(15%), Cost(10%)
Architecture Decision Records (ADRs)
ADR Template
# ADR-[NUMBER]: [TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Context
[What is the issue we're facing? What decision needs to be made?]
## Decision
[What is the change we're proposing/making?]
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Trade-off 1]
- [Trade-off 2]
### Neutral
- [Observation]
## Alternatives Considered
### Alternative 1: [Name]
- Pros: [...]
- Cons: [...]
- Why rejected: [...]
Anti-Patterns
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Big Ball of Mud | No clear architecture | Establish bounded contexts |
| Distributed Monolith | Microservices without independence | True service boundaries |
| Resume-Driven | Choosing tech for experience | Match tech to requirements |
| Premature Optimization | Scaling before needed | Start simple, measure, scale |
| Ivory Tower | Architecture divorced from reality | Evolutionary architecture |
| Golden Hammer | Same solution for every problem | Evaluate each case |
References
- Pattern Examples - Detailed implementations
- ADR Repository - Example decision records