Software Architect

Architecture Patterns

Monolith vs Microservices

When to Choose Monolith

• Starting a new project (start simple)
• Small team (< 10 developers)
• Simple domain with clear boundaries
• Rapid iteration/prototyping phase
• Limited DevOps expertise

When to Consider Microservices

• Clear domain boundaries identified
• Independent scaling requirements
• Multiple teams working in parallel
• Different technology requirements per service
• Existing mature DevOps practices

Modular Monolith (Recommended Starting Point)

src/
├── modules/
│   ├── users/
│   │   ├── api/           # HTTP handlers
│   │   ├── domain/        # Business logic
│   │   ├── infrastructure/# Database, external services
│   │   └── index.ts       # Public API
│   ├── orders/
│   │   ├── api/
│   │   ├── domain/
│   │   ├── infrastructure/
│   │   └── index.ts
│   └── payments/
│       └── ...
├── shared/                 # Cross-module utilities
└── app.ts

Benefits:

• Clear module boundaries
• Easy to extract to microservices later
• Single deployment simplicity
• Enforced API contracts between modules

Layered Architecture

┌─────────────────────────────────────┐
│         Presentation Layer          │  UI, API Controllers
├─────────────────────────────────────┤
│         Application Layer           │  Use Cases, Orchestration
├─────────────────────────────────────┤
│           Domain Layer              │  Business Logic, Entities
├─────────────────────────────────────┤
│        Infrastructure Layer         │  Database, External APIs
└─────────────────────────────────────┘

Dependency Rule: Upper layers depend on lower layers, never reverse.

Clean Architecture

┌─────────────────────────────────────────────┐
│              Frameworks & Drivers           │
│  ┌─────────────────────────────────────┐   │
│  │        Interface Adapters           │   │
│  │  ┌─────────────────────────────┐   │   │
│  │  │     Application Layer       │   │   │
│  │  │  ┌─────────────────────┐   │   │   │
│  │  │  │   Domain Layer      │   │   │   │
│  │  │  │   (Entities)        │   │   │   │
│  │  │  └─────────────────────┘   │   │   │
│  │  └─────────────────────────────┘   │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

Dependency Rule: Dependencies point inward only.

System Design Patterns

API Gateway Pattern

┌─────────┐     ┌─────────────┐     ┌──────────────┐
│ Clients │────▶│ API Gateway │────▶│ Service A    │
└─────────┘     │             │     ├──────────────┤
                │ - Auth      │────▶│ Service B    │
                │ - Rate Limit│     ├──────────────┤
                │ - Routing   │────▶│ Service C    │
                └─────────────┘     └──────────────┘

Responsibilities:

• Request routing
• Authentication/Authorization
• Rate limiting
• Request/Response transformation
• Load balancing
• Caching

Event-Driven Architecture

┌───────────┐    publish    ┌───────────────┐    subscribe    ┌───────────┐
│ Service A │─────────────▶│ Message Broker │◀───────────────│ Service B │
└───────────┘              │  (Kafka/RMQ)   │                └───────────┘
                           └───────────────┘
                                  │
                                  ▼ subscribe
                           ┌───────────┐
                           │ Service C │
                           └───────────┘

Event Types:

• Domain Events: Significant business occurrences
• Integration Events: Cross-service communication
• Commands: Request for action
• Queries: Request for data

CQRS (Command Query Responsibility Segregation)

┌─────────────────────────────────────────────────────┐
│                     Application                      │
│  ┌──────────────────┐    ┌──────────────────┐      │
│  │   Command Side   │    │   Query Side     │      │
│  │                  │    │                  │      │
│  │ - Create Order   │    │ - Get Order      │      │
│  │ - Update Order   │    │ - List Orders    │      │
│  │ - Cancel Order   │    │ - Search Orders  │      │
│  └────────┬─────────┘    └────────┬─────────┘      │
│           │                       │                 │
│           ▼                       ▼                 │
│  ┌────────────────┐     ┌────────────────┐        │
│  │ Write Database │────▶│ Read Database  │        │
│  │ (Normalized)   │ sync│ (Denormalized) │        │
│  └────────────────┘     └────────────────┘        │
└─────────────────────────────────────────────────────┘

Use CQRS when:

• Read and write patterns differ significantly
• Read scaling requirements are high
• Complex queries on normalized data are slow
• Event sourcing is being used

Scalability Patterns

Horizontal Scaling

                    ┌───────────────┐
                    │ Load Balancer │
                    └───────┬───────┘
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ Server 1 │  │ Server 2 │  │ Server 3 │
        └──────────┘  └──────────┘  └──────────┘

Requirements for horizontal scaling:

• Stateless application servers
• Session stored externally (Redis)
• Shared file storage (S3, shared filesystem)
• Database supports connections from multiple instances

Database Scaling

Read Replicas:
┌────────────┐      ┌────────────────┐
│   Primary  │─────▶│ Read Replica 1 │
│  (writes)  │      ├────────────────┤
└────────────┘─────▶│ Read Replica 2 │
                    ├────────────────┤
               ────▶│ Read Replica N │
                    └────────────────┘

Sharding:
┌────────────────────────────────────┐
│         Shard Router               │
└──────────────┬─────────────────────┘
       ┌───────┴───────┐
       ▼               ▼
┌─────────────┐ ┌─────────────┐
│ Shard A     │ │ Shard B     │
│ (users A-M) │ │ (users N-Z) │
└─────────────┘ └─────────────┘

Caching Strategy

Cache-Aside Pattern:
1. Check cache for data
2. If miss, read from database
3. Store in cache
4. Return data

Write-Through:
1. Write to cache
2. Cache writes to database
3. Return success

Write-Behind (Write-Back):
1. Write to cache
2. Return immediately
3. Cache asynchronously writes to database

Cache Invalidation:
- TTL-based (simple, may serve stale data)
- Event-based (complex, more accurate)
- Hybrid approach (TTL + event invalidation)

Caching Layers

┌─────────┐    ┌───────────┐    ┌───────────┐    ┌──────────┐
│ Browser │───▶│ CDN Cache │───▶│ App Cache │───▶│ Database │
│ Cache   │    │           │    │ (Redis)   │    │          │
└─────────┘    └───────────┘    └───────────┘    └──────────┘

Cache levels:

1. Browser cache: Static assets, API responses
2. CDN: Static assets, edge caching
3. Application cache: Session data, frequent queries
4. Database cache: Query cache, buffer pool

Integration Patterns

Synchronous Communication

// REST API call
const response = await fetch('https://api.service.com/resource');

// gRPC call
const result = await client.getResource(request);

Pros: Simple, immediate response Cons: Tight coupling, cascade failures

Asynchronous Communication

// Publish event
await messageQueue.publish('order.created', { orderId, items });

// Subscribe to events
messageQueue.subscribe('order.created', async (event) => {
  await processOrder(event);
});

Pros: Loose coupling, resilience Cons: Complexity, eventual consistency

Circuit Breaker Pattern

States:
┌────────┐  failures > threshold  ┌────────┐
│ CLOSED │───────────────────────▶│  OPEN  │
└────────┘                        └────┬───┘
     ▲                                 │
     │ success                         │ timeout
     │                                 ▼
     │                           ┌───────────┐
     └───────────────────────────│ HALF-OPEN │
                  success        └───────────┘

class CircuitBreaker {
  private failures = 0;
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
  private nextAttempt = Date.now();
  
  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'OPEN') {
      if (Date.now() < this.nextAttempt) {
        throw new Error('Circuit breaker is open');
      }
      this.state = 'HALF_OPEN';
    }
    
    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
}

Technology Evaluation Framework

Evaluation Criteria

Technology Comparison Template

## Technology Comparison: [Category]

### Options
1. Option A
2. Option B
3. Option C

### Comparison Matrix

| Criterion        | Option A | Option B | Option C |
|-----------------|----------|----------|----------|
| Fit for purpose | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐   | ⭐⭐⭐     |
| Team expertise  | ⭐⭐⭐     | ⭐⭐⭐⭐⭐ | ⭐⭐       |
| Performance     | ⭐⭐⭐⭐   | ⭐⭐⭐     | ⭐⭐⭐⭐⭐ |
| Cost            | ⭐⭐⭐⭐   | ⭐⭐       | ⭐⭐⭐⭐⭐ |

### Recommendation
[Your recommendation with rationale]

Documentation

System Context Diagram (C4 Level 1)

┌─────────────────────────────────────────────────────────┐
│                      Users                               │
│                        │                                 │
│                        ▼                                 │
│  ┌──────────────────────────────────────────────────┐  │
│  │              Our System                           │  │
│  │                                                   │  │
│  │  Manages user accounts, processes orders,        │  │
│  │  handles payments                                 │  │
│  └──────────────────────────────────────────────────┘  │
│                        │                                 │
│           ┌────────────┴────────────┐                   │
│           ▼                         ▼                   │
│  ┌─────────────────┐    ┌─────────────────┐            │
│  │ Payment Gateway │    │ Email Service   │            │
│  │ [External]      │    │ [External]      │            │
│  └─────────────────┘    └─────────────────┘            │
└─────────────────────────────────────────────────────────┘

Container Diagram (C4 Level 2)

┌──────────────────────────────────────────────────────────┐
│                     Our System                            │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │  Web App    │───▶│   API       │◀───│ Mobile App  │  │
│  │  [React]    │    │  [Node.js]  │    │ [React Nat] │  │
│  └─────────────┘    └──────┬──────┘    └─────────────┘  │
│                            │                             │
│                            ▼                             │
│                    ┌─────────────┐                       │
│                    │  Database   │                       │
│                    │ [PostgreSQL]│                       │
│                    └─────────────┘                       │
└──────────────────────────────────────────────────────────┘

Output Artifacts

When this skill is activated, I can help create:

1. Architecture Decision Records: Document key decisions
2. System Diagrams: Context, container, component diagrams
3. Technology Evaluation: Comparison matrices and recommendations
4. Scalability Plan: Caching, database, and infrastructure strategy
5. Integration Design: API contracts, event schemas
6. Migration Plan: Steps to evolve architecture
7. Architecture Review: Analysis of existing systems