Architecture Patterns

Overview

Architecture patterns provide proven solutions for structuring software systems. Choosing the right architecture is crucial for scalability, maintainability, and team productivity.

Patterns

Monolithic Architecture

Description: Single deployable unit containing all application functionality.

Key Features:

• Simple deployment and development

• Shared database and memory

• Straightforward debugging

Use Cases:

• MVPs and startups

• Small teams (< 10 developers)

• Simple domain logic

Best Practices:

src/ ├── modules/ # Feature-based organization │ ├── users/ │ ├── orders/ │ └── products/ ├── shared/ # Cross-cutting concerns └── infrastructure/ # External services

Microservices Architecture

Description: Distributed system of independently deployable services.

Key Features:

• Independent deployment and scaling

• Technology diversity per service

• Fault isolation

Use Cases:

• Large teams needing autonomy

• Complex domains with clear boundaries

• High scalability requirements

Key Components:

Component Purpose Tools

API Gateway Entry point, routing Kong, AWS API Gateway

Service Discovery Service registration Consul, Kubernetes DNS

Config Management Centralized config Spring Cloud Config, Consul

Circuit Breaker Fault tolerance Resilience4j, Hystrix

Best Practices:

• Design around business capabilities

• Decentralize data management

• Design for failure

• Automate deployment

Event-Driven Architecture

Description: Systems communicating through events.

Key Patterns:

Pattern Description Use Case

Event Sourcing Store state as events Audit trails, temporal queries

CQRS Separate read/write models High-read workloads

Saga Distributed transactions Cross-service workflows

Event Sourcing Example:

// Events are the source of truth interface OrderEvent { id: string; type: 'OrderCreated' | 'ItemAdded' | 'OrderShipped'; timestamp: Date; payload: unknown; }

// Rebuild state from events function rebuildOrder(events: OrderEvent[]): Order { return events.reduce((order, event) => { switch (event.type) { case 'OrderCreated': return { ...event.payload }; case 'ItemAdded': return { ...order, items: [...order.items, event.payload] }; case 'OrderShipped': return { ...order, status: 'shipped' }; } }, {} as Order); }

Serverless Architecture

Description: Cloud-managed execution without server management.

Key Features:

• Pay-per-execution pricing

• Auto-scaling to zero

• Reduced operational overhead

Considerations:

Aspect Impact

Cold Start 100ms-2s latency on first invocation

Timeout Usually 15-30 min max execution

State Must use external storage

Vendor Lock-in Platform-specific features

Best Practices:

• Keep functions small and focused

• Minimize dependencies

• Use connection pooling for databases

• Implement proper error handling

Clean Architecture

Description: Dependency-inverted architecture with domain at center.

Layer Structure:

┌──────────────────────────────────────┐ │ Frameworks & Drivers │ ← External (DB, Web, UI) ├──────────────────────────────────────┤ │ Interface Adapters │ ← Controllers, Gateways ├──────────────────────────────────────┤ │ Application Business │ ← Use Cases ├──────────────────────────────────────┤ │ Enterprise Business │ ← Entities, Domain Rules └──────────────────────────────────────┘

Dependency Rule: Dependencies point inward. Inner layers know nothing about outer layers.

Domain-Driven Design (DDD)

Description: Architecture aligned with business domain.

Strategic Patterns:

Pattern Purpose

Bounded Context Clear domain boundaries

Context Map Relationships between contexts

Ubiquitous Language Shared vocabulary

Tactical Patterns:

Pattern Purpose

Entity Objects with identity

Value Object Immutable descriptors

Aggregate Consistency boundary

Repository Collection-like persistence

Domain Event Something that happened

Decision Guide

START │ ├─ Team size < 10? ──────────────────→ Monolith │ ├─ Need independent deployments? ────→ Microservices │ ├─ Audit trail required? ────────────→ Event Sourcing │ ├─ Variable/unpredictable load? ─────→ Serverless │ ├─ Complex business logic? ──────────→ Clean Architecture + DDD │ └─ Default ──────────────────────────→ Modular Monolith

Common Pitfalls

1. Premature Microservices

Problem: Starting with microservices for a simple application Solution: Start monolithic, extract services when boundaries are clear

2. Distributed Monolith

Problem: Microservices that must deploy together Solution: Ensure services are truly independent with clear API contracts

3. Ignoring Data Boundaries

Problem: Shared database across services Solution: Each service owns its data, use events for synchronization

Hexagonal Architecture (Ports & Adapters)

Description: Application core isolated from external concerns through ports (interfaces) and adapters (implementations).

Structure:

┌─────────────────────────────────────────────────────────────┐ │ Driving Adapters │ │ (REST API, CLI, GraphQL, Message Consumer) │ └──────────────────────────┬──────────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────────┐ │ Input Ports │ │ (Use Case Interfaces) │ ├─────────────────────────────────────────────────────────────┤ │ │ │ APPLICATION CORE │ │ (Domain Logic, Entities) │ │ │ ├─────────────────────────────────────────────────────────────┤ │ Output Ports │ │ (Repository, Gateway Interfaces) │ └──────────────────────────┬──────────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────────┐ │ Driven Adapters │ │ (Database, External APIs, Message Publisher) │ └─────────────────────────────────────────────────────────────┘

TypeScript Example:

// Port (Interface) interface OrderRepository { save(order: Order): Promise<void>; findById(id: string): Promise<Order | null>; }

// Adapter (Implementation) class PostgresOrderRepository implements OrderRepository { constructor(private db: Database) {}

async save(order: Order): Promise<void> { await this.db.query('INSERT INTO orders...', [order]); }

async findById(id: string): Promise<Order | null> { const row = await this.db.query('SELECT * FROM orders WHERE id = $1', [id]); return row ? this.toDomain(row) : null; } }

// Use Case (Application Core) class CreateOrderUseCase { constructor(private orderRepo: OrderRepository) {} // Depends on Port, not Adapter

async execute(input: CreateOrderInput): Promise<Order> { const order = new Order(input); await this.orderRepo.save(order); return order; } }

Benefits:

• Easy to swap implementations (DB, external services)

• Highly testable (mock ports)

• Framework-agnostic domain logic

Modular Monolith

Description: Monolith with strict module boundaries, preparing for potential microservices extraction.

Key Features:

• Modules communicate via defined interfaces

• Each module owns its data

• Can be deployed as single unit or extracted

Structure:

src/ ├── modules/ │ ├── users/ │ │ ├── api/ # Public API of module │ │ │ └── UserService.ts │ │ ├── internal/ # Private implementation │ │ │ ├── UserRepository.ts │ │ │ └── UserEntity.ts │ │ └── index.ts # Only exports public API │ ├── orders/ │ │ ├── api/ │ │ │ └── OrderService.ts │ │ ├── internal/ │ │ └── index.ts │ └── shared/ # Cross-cutting utilities ├── infrastructure/ │ ├── database/ │ ├── messaging/ │ └── http/ └── main.ts

Module Communication Rules:

// ✅ Good: Use public API import { UserService } from '@modules/users'; const user = await userService.getById(id);

// ❌ Bad: Direct access to internal import { UserRepository } from '@modules/users/internal/UserRepository';

Enforcement:

// eslint rules or ts-paths to prevent internal imports { "rules": { "no-restricted-imports": ["error", { "patterns": ["@modules//internal/"] }] } }

Strangler Fig Pattern

Description: Gradually replace legacy system by routing traffic to new implementation.

Migration Process:

Phase 1: Facade ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ Client │────→│ Facade │────→│ Legacy │ └─────────┘ └─────────┘ │ System │ └─────────────┘

Phase 2: Partial Migration ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ Client │────→│ Facade │──┬─→│ Legacy │ └─────────┘ └─────────┘ │ └─────────────┘ │ ┌─────────────┐ └─→│ New System │ └─────────────┘

Phase 3: Complete Migration ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ Client │────→│ Facade │────→│ New System │ └─────────┘ └─────────┘ └─────────────┘

Implementation:

class PaymentFacade { constructor( private legacyPayment: LegacyPaymentService, private newPayment: NewPaymentService, private featureFlags: FeatureFlags ) {}

async processPayment(payment: Payment): Promise<Result> { // Gradually migrate traffic if (this.featureFlags.isEnabled('new-payment-system', payment.userId)) { return this.newPayment.process(payment); } return this.legacyPayment.process(payment); } }

Backend for Frontend (BFF)

Description: Dedicated backend for each frontend type (web, mobile, etc.).

Structure:

                ┌─────────────┐
                │ Web Client  │
                └──────┬──────┘
                       │
                ┌──────▼──────┐
                │  Web BFF    │
                └──────┬──────┘
                       │
   ┌───────────────────┼───────────────────┐
   │                   │                   │

┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ User Service│ │Order Service│ │Product Svc │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └───────────────────┼───────────────────┘ │ ┌──────▼──────┐ │ Mobile BFF │ └──────┬──────┘ │ ┌──────▼──────┐ │Mobile Client│ └─────────────┘

Benefits:

• Optimized payload for each client

• Client-specific authentication

• Independent deployment per frontend

• Reduces over-fetching

When to Use:

Scenario Recommendation

Single client type Skip BFF

Web + Mobile with same needs Single API Gateway

Different UX per platform Separate BFFs

Multiple teams per frontend Dedicated BFFs

Architecture Patterns Comparison

Pattern Complexity Scalability Team Size Best For

Monolith Low Vertical Small (2-10) MVPs, Simple apps

Modular Monolith Medium Vertical Medium (5-20) Growing apps

Microservices High Horizontal Large (20+) Complex domains

Serverless Medium Auto Any Event-driven, Variable load

Event-Driven High Horizontal Medium-Large Async workflows

Architecture Decision Record (ADR) Template

When choosing an architecture, document decisions:

ADR-001: Choose Modular Monolith

Status

Accepted

Context

• Team of 8 developers
• MVP deadline in 3 months
• Uncertain about domain boundaries
• Limited DevOps resources

Decision

Adopt Modular Monolith with strict boundaries

Consequences

Positive

• Faster initial development
• Simpler deployment
• Can extract services later

Negative

• Single point of failure
• Scaling limited to vertical
• Need discipline for module boundaries

Alternatives Considered

1. Microservices - Too complex for team size
2. Traditional Monolith - No path to scale

Evolution Path

┌─────────────────────────────────────────────────────────────────┐ │ Architecture Evolution │ │ │ │ Monolith ──→ Modular Monolith ──→ Microservices │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ Event-Driven / CQRS │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ [Simple] [Growing] [Complex/Scale] │ │ │ │ Tip: Don't skip steps. Each stage teaches domain boundaries. │ └─────────────────────────────────────────────────────────────────┘

Anti-Patterns to Avoid

1. Big Ball of Mud

Symptom: No clear structure, everything depends on everything Fix: Introduce module boundaries, apply Clean Architecture principles

2. Golden Hammer

Symptom: Using same architecture for every project Fix: Evaluate requirements, use decision guide

3. Accidental Complexity

Symptom: Architecture more complex than domain requires Fix: Start simple, add complexity only when needed

4. Resume-Driven Development

Symptom: Choosing tech for learning, not solving problems Fix: Align architecture with team skills and project needs

5. Vendor Lock-In

Symptom: Core logic tightly coupled to cloud provider Fix: Use Hexagonal Architecture, abstract vendor-specific code

Performance Considerations by Pattern

Pattern Latency Throughput Cold Start

Monolith Low High N/A

Microservices Medium (network) High (distributed) N/A

Serverless Variable Auto-scale 100ms-2s

Event-Driven Higher (async) Very High Depends

Testing Strategies by Pattern

Monolith

Unit Tests → Integration Tests → E2E Tests 70% 20% 10%

Microservices

Unit Tests → Contract Tests → Integration → E2E 60% 20% 15% 5%

// Contract Test Example (Pact) const provider = new Pact({ consumer: 'OrderService', provider: 'UserService' }); await provider.addInteraction({ state: 'user exists', uponReceiving: 'get user request', withRequest: { method: 'GET', path: '/users/123' }, willRespondWith: { status: 200, body: { id: '123', name: 'John' } } });

Event-Driven

• Test event producers and consumers independently

• Use event schema validation

• Test saga/workflow orchestration

Related Skills

• [[api-design]] - API design for service communication

• [[system-design]] - Large-scale system considerations

• [[devops-cicd]] - Deployment strategies for each pattern

• [[data-design]] - Database patterns for each architecture