architecture-patterns

Architecture Patterns

Reference for architectural design and documentation. Use this skill when:

• Architect reviews system design
• Planner considers architectural constraints
• Analyst investigates integration approaches
• Critic evaluates architectural alignment

Architecture Decision Records (ADR)

ADR Format

Every significant architectural decision should be documented:

# ADR-[NNN]: [Decision Title]

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

## Context
[What is the situation? What forces are at play?]

## Decision
[What is the change being proposed or decided?]

## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Tradeoff 1]
- [Tradeoff 2]

### Neutral
- [Side effect]

## Alternatives Considered
1. [Alternative 1]: [Why rejected]
2. [Alternative 2]: [Why rejected]

## Related
- ADR-XXX: [Related decision]
- [External reference]

When to Write ADRs

Scenario	ADR Required?
New external dependency	Yes
New architectural pattern	Yes
Technology switch	Yes
Module boundary change	Yes
Performance tradeoff	Yes
Bug fix	No
Refactoring (same behavior)	Usually no

---

Common Patterns

Layered Architecture

┌─────────────────────────────────┐
│         Presentation            │  UI, API endpoints
├─────────────────────────────────┤
│          Application            │  Use cases, orchestration
├─────────────────────────────────┤
│           Domain                │  Business logic, entities
├─────────────────────────────────┤
│        Infrastructure           │  DB, external services
└─────────────────────────────────┘

Rules:

• Dependencies point downward only
• Lower layers never import from higher
• Domain has no external dependencies

Use when: Enterprise apps, clear separation needed

Repository Pattern

Purpose: Abstract data access, enable testability

// Interface in domain layer
interface UserRepository {
  findById(id: string): Promise<User | null>;
  save(user: User): Promise<void>;
}

// Implementation in infrastructure layer
class PostgresUserRepository implements UserRepository {
  async findById(id: string): Promise<User | null> {
    const row = await db.query('SELECT * FROM users WHERE id = $1', [id]);
    return row ? mapToUser(row) : null;
  }
}