Design Patterns

---
name: design-patterns
description: Design patterns — KISS, YAGNI, DRY, SOLID, GoF, DDD reference.
---

# Design Patterns

## Pragmatic Engineering Principles

These principles apply at every layer of the stack, independent of language or framework.

| Principle | Rule | Violated when... |
|-----------|------|------------------|
| **KISS** — Keep It Simple | Prefer the simplest solution that correctly solves the problem | A simpler approach exists but a more complex one was chosen without justification |
| **YAGNI** — You Aren't Gonna Need It | Don't build features, abstractions, or generalization until they are actually needed | Code is written for a hypothetical future requirement that doesn't exist yet |
| **DRY** — Don't Repeat Yourself | Every piece of knowledge has a single, authoritative representation | Logic, validation rules, or configuration are duplicated across two or more places |

### KISS — Observable violations
- Multiple layers of indirection for a straight-line operation
- Abstract base classes or interfaces with a single implementation
- Configuration system for a value that never changes
- Helper utilities that wrap a single built-in function call

### YAGNI — Observable violations
- Methods, parameters, or flags added "for future use"
- Generic or pluggable architecture for a system with one known use case
- Premature abstraction before a second consumer exists
- Feature flags or extension points with no current users

### DRY — Observable violations
- Copy-pasted logic across two or more files
- Identical validation rules defined independently per endpoint or form
- Hardcoded values (strings, numbers, URLs) repeated in multiple places
- Parallel data structures that must be kept manually in sync

---

## SOLID Principles

| Principle | Rule |
|-----------|------|
| **S** — Single Responsibility | A class/module has one reason to change |
| **O** — Open/Closed | Open for extension, closed for modification |
| **L** — Liskov Substitution | Subtypes must be substitutable for their base types |
| **I** — Interface Segregation | Clients should not depend on interfaces they don't use |
| **D** — Dependency Inversion | Depend on abstractions, not concretions |

---

## Creational Patterns

### Factory Method
Creates objects without specifying the exact class. Use when the creation logic may vary or is complex.
```
Creator → factoryMethod() → Product
```

### Abstract Factory
Creates families of related objects. Use when the system needs to be independent of how products are created.

### Builder
Constructs complex objects step by step. Use when an object has many optional parameters or construction phases.

### Singleton
Ensures a class has only one instance. Use sparingly — prefer dependency injection. Avoid in testable code.

---

## Structural Patterns

### Adapter
Converts an interface into another that clients expect. Use for integrating incompatible interfaces (e.g., third-party SDKs).

### Decorator
Adds responsibilities to objects dynamically. Prefer over subclassing for feature composition.

### Facade
Provides a simplified interface to a complex subsystem. Use to hide complexity from callers.

### Repository
Abstracts data access behind an interface. Decouples business logic from persistence technology.

### Proxy
Controls access to an object (lazy loading, caching, access control, logging).

---

## Behavioral Patterns

### Strategy
Defines a family of algorithms and makes them interchangeable. Use when behavior varies and should be swappable at runtime.

### Observer
Defines a one-to-many dependency so that when one object changes state, its dependents are notified. Use for event-driven systems.

### Command
Encapsulates a request as an object. Enables undo, queuing, and logging of operations.

### Chain of Responsibility
Passes a request through a chain of handlers. Use for pipelines (middleware, validation chains).

### Template Method
Defines the skeleton of an algorithm, deferring steps to subclasses. Use when multiple implementations share a common process.

---

## Domain-Driven Patterns

### Value Object
Immutable object defined by its attributes, not identity. Use for things like Money, Email, Address.

### Entity
Object with a unique identity that persists over time. Has a lifecycle (create, update, delete).

### Aggregate
Cluster of entities and value objects treated as a unit. Defines a consistency boundary.

### Service
Stateless operation that doesn't naturally belong to an entity or value object.

### Repository (DDD)
Provides collection-like access to aggregates. Hides storage details.

---

## Anti-Patterns to Avoid

| Anti-Pattern | Problem |
|-------------|---------|
| God Object | One class knows too much / does too much |
| Spaghetti Code | Unstructured, hard-to-follow control flow |
| Magic Numbers | Unnamed numeric literals — use named constants |
| Premature Optimization | Optimizing before profiling proves a bottleneck |
| Cargo Cult | Copying patterns without understanding why |
| Anemic Domain Model | Entities with no behavior — just getters/setters |

---

## Composition Root

The single place in the application where all object graphs are assembled. Every dependency binding happens here and nowhere else — services never instantiate their own dependencies.

Load `references/composition-root.md` when setting up DI wiring, designing a service layer, or evaluating whether a DI container is appropriate for the project.

---

## Choosing a Pattern

1. Identify the problem: creation? structure? behavior?
2. Check if the pattern fits the context, not just the structure
3. Prefer the simplest solution — patterns add complexity
4. Document the choice in an ADR if it's non-obvious