architecture-selection

# 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

```markdown
# 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](examples/architecture-patterns.md) - Detailed implementations
- [ADR Repository](examples/adrs/) - Example decision records