System Design

System Design

Architectural thinking for systems that need to scale, evolve, and be maintained by teams.

Core principle: Good architecture makes change cheap. Bad architecture makes every change expensive.

When to Use

• Designing a new system or major subsystem
• Evaluating whether to split a monolith
• Choosing between architectural patterns
• Writing an ADR for a significant decision
• Designing service boundaries and communication patterns
• Planning event-driven vs synchronous architecture

When NOT to Use

• Single feature planning (use feature-planning skill)
• Database schema design (use database-design skill)
• API endpoint design (use api-design skill)

Architectural Decision Records (ADRs)

Document significant architectural decisions. An undocumented decision is a mystery for the next engineer.

When to Write an ADR

• Decision is hard to reverse
• Affects multiple teams or components
• Has meaningful trade-offs worth recording
• Future engineers would otherwise be confused by the choice

ADR Template

# ADR-[N]: [Short title of decision]

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-[M]
**Date:** YYYY-MM-DD
**Deciders:** [Names or teams]

## Context
[What situation are we in? What problem needs solving? What forces are at play?]

## Decision
[What have we decided to do?]

## Rationale
[Why this option? What alternatives were considered and why rejected?]

## Consequences
**Good:** [Benefits of this decision]
**Bad:** [Downsides, constraints, or risks introduced]
**Neutral:** [Changes that are neither good nor bad]

System Decomposition

Start with Business Domains

Before technical decomposition, map business domains:

1. Identify core domains — what the business does (e.g., Order Management, Inventory, Payments)
2. Identify supporting domains — what enables core (e.g., Notifications, Auth, Analytics)
3. Identify generic domains — solved by external tools (e.g., Email, Billing, Auth providers)

Invest engineering effort proportional to business value. Core domains get custom solutions. Generic domains get third-party tools.

Bounded Contexts (DDD)

A bounded context is a clear boundary within which a model has a specific meaning.

Order Context:          "Order" means a customer purchase with items, payment, address
Inventory Context:      "Order" means a replenishment request to a supplier
Fulfillment Context:    "Order" means a pick-pack-ship job in the warehouse

The same word means different things in different contexts. That's normal. Don't force one unified model.

Context Map: Draw how contexts relate:

• Partnership — teams coordinate closely, ship together
• Customer-Supplier — one context depends on another's API
• Anti-corruption Layer — translation between incompatible models
• Published Language — shared, well-documented interface (OpenAPI spec)

Aggregate Design

An aggregate is a cluster of objects treated as a unit for data consistency:

Order (aggregate root)
  └── OrderItem (entity, belongs to Order)
  └── ShippingAddress (value object)
  └── PaymentReference (value object, ID only — no details)

Rules:

• Only aggregate roots have repositories
• External references use IDs only (not embedded objects)
• Aggregates enforce their own invariants (business rules)
• Keep aggregates small — one aggregate per transaction

Architectural Patterns

Monolith vs Services

Rule: Extract to services only when you have real pain — deploy coupling, scaling divergence, team autonomy issues. Not before.

Communication Patterns

Sync vs Async Decision

Use async (events/queues) when:

• Caller doesn't need the result immediately
• Operation might take >500ms
• Multiple consumers of the same event
• Downstream failures shouldn't block the caller

Use sync (REST/gRPC) when:

• Caller needs immediate response
• Transaction must be atomic
• One consumer only

Trade-off Analysis Framework

For every significant architectural decision, evaluate:

CAP theorem: In a distributed system, you can only guarantee 2 of: Consistency, Availability, Partition Tolerance.

Design Principles

Single Responsibility

Every module, service, and component has one reason to change. If you need to change a module for two different business reasons, split it.

Dependency Rule (Clean Architecture)

Dependencies point inward:

UI → Application Logic → Domain → (nothing)
Infrastructure → Domain

Domain never depends on infrastructure. Infrastructure adapters implement domain interfaces.

Anti-Corruption Layer

When integrating with legacy systems or external APIs with messy models, translate at the boundary:

// External: messy legacy schema
interface LegacyOrder { ord_no: string; cust_id: number; itm_list: string }

// Internal: clean domain model
interface Order { id: OrderId; customerId: CustomerId; items: OrderItem[] }

// Anti-corruption layer translates
class LegacyOrderAdapter {
  toDomain(legacy: LegacyOrder): Order {
    return {
      id: new OrderId(legacy.ord_no),
      customerId: new CustomerId(String(legacy.cust_id)),
      items: this.parseItems(legacy.itm_list),
    };
  }
}

Verification Checklist

Before finalizing architecture:

• Business domains identified and mapped
• Bounded contexts defined with explicit boundaries
• ADR written for each significant decision
• Trade-offs explicitly listed (not just benefits)
• Dependency directions are intentional (no circular deps)
• Integration points use anti-corruption layers where models differ
• Communication pattern chosen with justification (sync vs async)
• Operational complexity realistic for team size
• Rollback plan exists if the architecture decision proves wrong