Architecture

A comprehensive architecture skill that helps design, evaluate, and document software architectures for robust, scalable, and maintainable systems.

Quick Start

Basic architecture workflow:

# Understand requirements (functional + non-functional)
# Identify constraints and trade-offs
# Design system components and relationships
# Document architecture decisions
# Validate against requirements

Core Capabilities

1. System Architecture Design

Design complete system architectures:

• Monolithic: Single deployable unit
• Microservices: Distributed services architecture
• Serverless: Event-driven, function-based
• Event-Driven: Asynchronous message-based
• Layered: Separation of concerns in layers
• Hexagonal: Ports and adapters pattern
• CQRS: Command Query Responsibility Segregation
• Event Sourcing: State as sequence of events

2. Design Patterns

Apply proven design patterns:

Creational Patterns:

• Singleton, Factory, Builder, Prototype, Abstract Factory

Structural Patterns:

• Adapter, Bridge, Composite, Decorator, Facade, Proxy

Behavioral Patterns:

• Observer, Strategy, Command, State, Template Method, Chain of Responsibility

3. Architecture Quality Attributes

Evaluate and optimize for:

• Performance: Response time, throughput, resource usage
• Scalability: Horizontal and vertical scaling
• Availability: Uptime, fault tolerance, disaster recovery
• Security: Authentication, authorization, encryption, data protection
• Maintainability: Code quality, modularity, testability
• Reliability: Error handling, resilience, redundancy
• Usability: User experience, API design
• Observability: Logging, monitoring, tracing

4. Technology Selection

Evaluate and recommend technologies:

• Databases: SQL vs NoSQL, selection criteria
• Message Queues: Kafka, RabbitMQ, SQS
• Caching: Redis, Memcached, CDN
• API Protocols: REST, GraphQL, gRPC
• Cloud Platforms: AWS, Azure, GCP
• Containerization: Docker, Kubernetes

5. Architecture Documentation

Document architecture effectively:

• C4 Model: Context, Container, Component, Code diagrams
• Architecture Decision Records (ADRs): Document key decisions
• Data Flow Diagrams: How data moves through system
• Sequence Diagrams: Component interactions
• Deployment Diagrams: Infrastructure and deployment

Architecture Patterns

Microservices Architecture

┌─────────────────────────────────────────────────┐
│              API Gateway / BFF                   │
└────────┬──────────┬──────────┬──────────────────┘
         │          │          │
    ┌────▼───┐ ┌───▼────┐ ┌──▼──────┐
    │ User   │ │ Order  │ │ Payment │
    │Service │ │Service │ │ Service │
    └────┬───┘ └───┬────┘ └──┬──────┘
         │         │          │
    ┌────▼───┐ ┌──▼─────┐ ┌──▼──────┐
    │ User   │ │ Order  │ │ Payment │
    │  DB    │ │   DB   │ │   DB    │
    └────────┘ └────────┘ └─────────┘
         │         │          │
    └────┴─────────┴──────────┴──────┘
              Message Bus

Characteristics:

• Independent deployment and scaling
• Polyglot persistence
• Decentralized data management
• Resilience through isolation
• Technology diversity

Trade-offs:

• ✅ Independent scaling
• ✅ Technology flexibility
• ✅ Fault isolation
• ❌ Distributed system complexity
• ❌ Data consistency challenges
• ❌ Operational overhead

Event-Driven Architecture

┌──────────┐      ┌──────────────┐      ┌──────────┐
│ Producer │─────▶│ Event Bus    │─────▶│Consumer 1│
└──────────┘      │ (Kafka/SNS)  │      └──────────┘
                  └───────┬──────┘
                          │
                     ┌────▼──────┐
                     │Consumer 2 │
                     └───────────┘

Characteristics:

• Asynchronous communication
• Loose coupling between components
• Scalable event processing
• Event replay capability

Use Cases:

• Real-time data processing
• Microservices integration
• IoT systems
• Activity tracking

Layered Architecture

┌─────────────────────────────────┐
│     Presentation Layer          │ ← Controllers, Views
├─────────────────────────────────┤
│     Business Logic Layer        │ ← Services, Domain
├─────────────────────────────────┤
│     Data Access Layer           │ ← Repositories, DAOs
├─────────────────────────────────┤
│     Database Layer              │ ← Database
└─────────────────────────────────┘

Characteristics:

• Clear separation of concerns
• Each layer has specific responsibility
• Dependencies flow downward
• Easy to understand and maintain

Hexagonal Architecture (Ports & Adapters)

         ┌─────────────────────────┐
         │   External Systems      │
         └───────────┬─────────────┘
                     │
         ┌───────────▼─────────────┐
         │      Adapters           │ ← HTTP, CLI, Message Queue
         └───────────┬─────────────┘
                     │
         ┌───────────▼─────────────┐
         │       Ports             │ ← Interfaces
         └───────────┬─────────────┘
                     │
         ┌───────────▼─────────────┐
         │    Domain Logic         │ ← Core Business Logic
         └───────────┬─────────────┘
                     │
         ┌───────────▼─────────────┐
         │       Ports             │ ← Interfaces
         └───────────┬─────────────┘
                     │
         ┌───────────▼─────────────┐
         │      Adapters           │ ← Database, APIs, File System
         └───────────┬─────────────┘
                     │
         ┌───────────▼─────────────┐
         │   External Systems      │
         └─────────────────────────┘

Characteristics:

• Domain logic independent of external concerns
• Testable in isolation
• Flexible adapter implementation
• Clear boundaries

Scalability Patterns

Horizontal Scaling

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

Techniques:

• Load balancing
• Stateless services
• Shared data layer
• Session management

Caching Strategy

Client ──▶ CDN ──▶ API Server ──▶ Redis ──▶ Database
           (Static)  (Cache)     (Cache)    (Source)

Cache Levels:

1. CDN: Static assets
2. Application Cache: Query results, computed data
3. Database Cache: Query cache

Cache Patterns:

• Cache-Aside: Application manages cache
• Read-Through: Cache loads data automatically
• Write-Through: Write to cache and DB
• Write-Behind: Async writes to DB

Database Scaling

Vertical Scaling:

• Increase server resources
• Limited by hardware

Horizontal Scaling:

• Replication: Master-Slave, Multi-Master
• Sharding: Partition data across servers
• CQRS: Separate read and write databases

Architecture Decision Framework

Decision Template

# Decision: [Title]

## Context
- What problem are we solving?
- What are the constraints?
- What are the requirements?

## Options Considered

### Option 1: [Name]
**Pros:**
- Pro 1
- Pro 2

**Cons:**
- Con 1
- Con 2

**Estimated Effort:** [Low/Medium/High]
**Risk Level:** [Low/Medium/High]

### Option 2: [Name]
[Same structure]

## Decision
We chose [Option X] because [reasoning].

## Consequences
- Positive: [benefits]
- Negative: [trade-offs]
- Risks: [what could go wrong]
- Mitigation: [how to address risks]

## Validation
How will we validate this decision?

Common Architecture Patterns

API Gateway Pattern

"""
API Gateway centralizes external requests and routes to services.
"""

class APIGateway:
    def __init__(self):
        self.user_service = UserService()
        self.order_service = OrderService()
        self.auth_service = AuthService()
    
    async def handle_request(self, request: Request) -> Response:
        # Authentication
        if not await self.auth_service.authenticate(request):
            return Response(status=401)
        
        # Rate limiting
        if not await self.rate_limiter.check(request.user_id):
            return Response(status=429)
        
        # Route to appropriate service
        if request.path.startswith('/users'):
            return await self.user_service.handle(request)
        elif request.path.startswith('/orders'):
            return await self.order_service.handle(request)
        
        return Response(status=404)

Circuit Breaker Pattern

"""
Circuit breaker prevents cascading failures.
"""

class CircuitBreaker:
    def __init__(self, failure_threshold=5, timeout=60):
        self.failure_threshold = failure_threshold
        self.timeout = timeout
        self.failures = 0
        self.last_failure_time = None
        self.state = 'CLOSED'  # CLOSED, OPEN, HALF_OPEN
    
    async def call(self, func, *args, **kwargs):
        if self.state == 'OPEN':
            if self._should_attempt_reset():
                self.state = 'HALF_OPEN'
            else:
                raise CircuitBreakerOpen('Service unavailable')
        
        try:
            result = await func(*args, **kwargs)
            self._on_success()
            return result
        except Exception as e:
            self._on_failure()
            raise
    
    def _on_success(self):
        self.failures = 0
        self.state = 'CLOSED'
    
    def _on_failure(self):
        self.failures += 1
        self.last_failure_time = time.time()
        if self.failures >= self.failure_threshold:
            self.state = 'OPEN'
    
    def _should_attempt_reset(self):
        return (time.time() - self.last_failure_time) >= self.timeout

Repository Pattern

"""
Repository pattern abstracts data access.
"""

from abc import ABC, abstractmethod
from typing import List, Optional

class UserRepository(ABC):
    @abstractmethod
    async def find_by_id(self, user_id: int) -> Optional[User]:
        pass
    
    @abstractmethod
    async def find_by_email(self, email: str) -> Optional[User]:
        pass
    
    @abstractmethod
    async def save(self, user: User) -> User:
        pass
    
    @abstractmethod
    async def delete(self, user_id: int) -> bool:
        pass

class SQLUserRepository(UserRepository):
    def __init__(self, db_session):
        self.db = db_session
    
    async def find_by_id(self, user_id: int) -> Optional[User]:
        result = await self.db.execute(
            "SELECT * FROM users WHERE id = ?", (user_id,)
        )
        row = result.fetchone()
        return User.from_row(row) if row else None
    
    async def save(self, user: User) -> User:
        if user.id:
            await self.db.execute(
                "UPDATE users SET name = ?, email = ? WHERE id = ?",
                (user.name, user.email, user.id)
            )
        else:
            result = await self.db.execute(
                "INSERT INTO users (name, email) VALUES (?, ?)",
                (user.name, user.email)
            )
            user.id = result.lastrowid
        return user

System Design Process

1. Requirements Gathering

Functional Requirements:

• What should the system do?
• What features are needed?
• What are the use cases?

Non-Functional Requirements:

• Performance: Latency, throughput targets
• Scale: Expected users, data volume
• Availability: Uptime requirements
• Security: Compliance, data protection
• Cost: Budget constraints

2. Capacity Planning

Users: 10 million
Daily Active Users: 1 million
Requests per second: 1M users × 10 requests/day / 86400 seconds ≈ 116 RPS
Peak traffic (3x average): 350 RPS

Data:
- Per user: 1 KB metadata + 100 KB content
- Total: 10M × 101 KB ≈ 1 TB

Bandwidth:
- Request size: 1 KB
- Response size: 10 KB
- Bandwidth: 350 RPS × 11 KB ≈ 3.85 MB/s ≈ 30 Mbps

3. High-Level Design

┌─────────┐
│ Client  │
└────┬────┘
     │
┌────▼──────────┐
│  CDN          │ (Static content)
└────┬──────────┘
     │
┌────▼──────────┐
│ Load Balancer │
└────┬──────────┘
     │
┌────▼──────────┐
│  Web Servers  │ (3+ instances)
└────┬──────────┘
     │
┌────▼──────────┐
│  App Servers  │ (5+ instances)
└────┬──────────┘
     │
┌────▼──────────┬────────────┐
│               │            │
│  Cache       │  Database  │ Message
│  (Redis)     │  (Master/  │ Queue
│              │   Slaves)  │ (Kafka)
└──────────────┴────────────┴─────────┘

4. Detailed Component Design

Design each component with:

• Inputs and outputs
• Data models
• API contracts
• Error handling
• Monitoring

5. Identify Bottlenecks

• Single points of failure
• Performance bottlenecks
• Scaling limitations
• Data consistency issues

6. Optimization

• Caching strategy
• Database indexing
• Load balancing
• CDN for static content
• Async processing
• Connection pooling

Best Practices

1. Start Simple: Begin with simplest architecture that works
2. Design for Failure: Assume components will fail
3. Loose Coupling: Minimize dependencies between components
4. High Cohesion: Group related functionality
5. Separation of Concerns: Each component has single responsibility
6. Document Decisions: Use ADRs for important choices
7. Consider Trade-offs: Every decision has pros and cons
8. Plan for Scale: Design with growth in mind
9. Security First: Build security in from the start
10. Measure Everything: Observability is crucial

When to Use This Skill

Use this skill when:

• Designing new systems
• Evaluating architecture options
• Planning system migrations
• Addressing scalability issues
• Making technology decisions
• Documenting architecture
• Conducting architecture reviews
• Planning for growth
• Solving system design problems
• Training team on architecture patterns

Examples

See EXAMPLES.md for complete architecture examples including:

• E-commerce system design
• Social media platform
• Video streaming service
• Real-time analytics system
• Multi-tenant SaaS application

For architecture templates, see templates/.

For architecture decision records, see adr/.