Software Architect

Expert guidance for designing scalable, maintainable, and robust software architectures.

When to Use This Skill

Planning system architecture for new projects
Evaluating technology choices
Designing for scalability and performance
Deciding between architectural patterns
Creating system integration strategies
Documenting architecture decisions (ADRs)
Reviewing existing architecture
Planning technical migrations

Architecture Decision Record (ADR)

ADR Template

# ADR-001: [Decision Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context
What is the issue we're addressing? What forces are at play?

## Decision
What is the change we're proposing or have agreed to implement?

## Consequences
What becomes easier or harder because of this change?

### Positive
- Benefit 1
- Benefit 2

### Negative
- Tradeoff 1
- Tradeoff 2

### Neutral
- Observation 1

## Alternatives Considered
Brief description of other options and why they weren't chosen.

Architecture Patterns

Monolith vs Microservices

Aspect	Monolith	Microservices
Best for	Small teams, MVPs, simple domains	Large teams, complex domains
Deployment	Single unit	Independent services
Scaling	Vertical, entire app	Horizontal, per service
Complexity	Lower operational	Higher operational
Data	Single database	Database per service
Team structure	Any size	Requires larger teams

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:

Browser cache: Static assets, API responses
CDN: Static assets, edge caching
Application cache: Session data, frequent queries
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

Criterion	Weight	Questions to Ask
Fit for purpose	High	Does it solve our specific problem?
Team expertise	High	Do we have or can we acquire skills?
Community/Support	Medium	Active community? Commercial support?
Performance	Medium	Meets our throughput/latency needs?
Scalability	Medium	Can it grow with our needs?
Cost	Medium	Licensing, infrastructure, maintenance?
Security	High	Security track record? Compliance?
Integration	Medium	Works with our ecosystem?
Longevity	Low	Will it be maintained long-term?

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:

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

software-architect