Architecture Patterns

Architecture Patterns

This skill provides knowledge about common architectural patterns to help design feature implementations. Apply these patterns based on the project's existing architecture and the feature's requirements.

Pattern Selection Guide

Choose patterns based on:

1. Existing architecture - Match what's already in use
2. Team familiarity - Use patterns the team knows
3. Feature requirements - Some patterns fit better for certain features
4. Scale requirements - Consider current and future scale

Layered Architecture (N-Tier)

When to use: Most web applications, CRUD operations, clear separation of concerns needed

Layers:

┌─────────────────────────┐
│   Presentation Layer    │  UI, API endpoints, controllers
├─────────────────────────┤
│    Application Layer    │  Use cases, orchestration, DTOs
├─────────────────────────┤
│      Domain Layer       │  Business logic, entities, rules
├─────────────────────────┤
│   Infrastructure Layer  │  Database, external services, I/O
└─────────────────────────┘

Key rules:

• Dependencies flow downward only
• Each layer only talks to the layer directly below
• Domain layer has no external dependencies

Implementation tips:

• Use interfaces at layer boundaries
• Keep domain logic in the domain layer, not controllers
• Use DTOs to transfer data between layers

MVC (Model-View-Controller)

When to use: Web applications with server-rendered views, simple CRUD apps

Components:

User → Controller → Model → Controller → View → User
           ↓           ↑
        Updates      Reads

Model: Data and business logic View: Presentation/UI Controller: Handles input, coordinates model and view

Implementation tips:

• Keep controllers thin - delegate to services
• Models should be framework-agnostic when possible
• Views should have minimal logic

Repository Pattern

When to use: Data access abstraction, testability, multiple data sources

Structure:

interface UserRepository {
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  save(user: User): Promise<User>;
  delete(id: string): Promise<void>;
}

class PostgresUserRepository implements UserRepository {
  // Implementation using PostgreSQL
}

class InMemoryUserRepository implements UserRepository {
  // Implementation for testing
}

Benefits:

• Abstracts data access details
• Easy to swap implementations
• Simplifies testing with in-memory implementations

Service Layer Pattern

When to use: Complex business logic, multiple entry points (API, CLI, queue)

Structure:

class UserService {
  constructor(
    private userRepo: UserRepository,
    private emailService: EmailService,
    private logger: Logger
  ) {}

  async registerUser(data: RegisterDTO): Promise<User> {
    // Validation
    // Business logic
    // Coordination of multiple repositories/services
    // Return result
  }
}

Implementation tips:

• Services contain business logic, not controllers
• One service per domain concept
• Services can call other services (but avoid cycles)

Event-Driven Architecture

When to use: Decoupled components, async processing, audit trails, notifications

Patterns:

Event Emitter (Simple)

// Emit events for side effects
userService.on('userCreated', async (user) => {
  await emailService.sendWelcome(user);
  await analyticsService.trackSignup(user);
});

Message Queue (Distributed)

Producer → Queue → Consumer
              ↓
           Consumer

Event structure:

interface DomainEvent {
  type: string;
  timestamp: Date;
  payload: unknown;
  metadata: {
    correlationId: string;
    causationId: string;
  };
}

Implementation tips:

• Events should be immutable
• Include enough context to process without additional queries
• Handle idempotency for at-least-once delivery

CQRS (Command Query Responsibility Segregation)

When to use: Complex domains, different read/write patterns, high-performance reads needed

Structure:

Commands (Write)              Queries (Read)
     ↓                              ↓
Command Handler              Query Handler
     ↓                              ↓
Write Model                  Read Model
     ↓                              ↓
Write Database              Read Database

Simplified CQRS:

// Commands modify state
class CreateUserCommand {
  execute(data: CreateUserDTO): Promise<void>
}

// Queries return data without modification
class GetUserQuery {
  execute(id: string): Promise<UserDTO>
}

Implementation tips:

• Start simple - same database, different models
• Use for complex domains where read/write models differ
• Consider eventual consistency implications

Ports and Adapters (Hexagonal)

When to use: High testability needs, multiple I/O channels, long-lived applications

Structure:

          ┌──────────────────────────────────────┐
Adapters  │  HTTP  │  CLI  │  Queue  │  Timer   │
(Driving) └────────┴───────┴─────────┴──────────┘
                          ↓ Ports
          ┌──────────────────────────────────────┐
          │         Application Core            │
          │  ┌────────────────────────────────┐ │
          │  │      Domain Logic              │ │
          │  └────────────────────────────────┘ │
          └──────────────────────────────────────┘
                          ↓ Ports
          ┌──────────────────────────────────────┐
Adapters  │  DB   │  Cache │  Email  │  API     │
(Driven)  └───────┴────────┴─────────┴──────────┘

Key concept: Business logic at center, all I/O through ports/adapters

Implementation tips:

• Define ports (interfaces) for all external interactions
• Adapters implement ports for specific technologies
• Domain code never imports adapter code

Microservices Patterns

When to use: Large teams, independent deployability, different scaling needs

API Gateway

Single entry point that routes to services

Service Discovery

Services register themselves, clients look them up

Circuit Breaker

Prevent cascade failures when services are down

const breaker = new CircuitBreaker(remoteService.call, {
  timeout: 3000,
  errorThreshold: 50,
  resetTimeout: 30000
});

Saga Pattern

Coordinate transactions across services

Service A → Service B → Service C
    ↓           ↓           ↓
Compensate ← Compensate ← Compensate (on failure)

Choosing the Right Pattern

Anti-Patterns to Avoid

1. Big Ball of Mud - No clear structure
2. God Object - One class does everything
3. Spaghetti Code - Tangled dependencies
4. Golden Hammer - Using one pattern for everything
5. Premature Optimization - Complex patterns for simple needs

Application Guidelines

1. Match existing architecture - Don't introduce new patterns unnecessarily
2. Start simple - Add complexity only when needed
3. Document decisions - Explain why a pattern was chosen
4. Consider team skills - A simpler pattern well-executed beats a complex one poorly understood