System Design

Step 2: Assumption Ledger (MANDATORY)

Every design is built on assumptions. Document them explicitly so they can be validated.

### Assumptions

| # | Assumption | Impact if wrong | Confidence | Validation method |
|---|---|---|---|---|
| A1 | Peak traffic is 500 req/s | Over-/under-provisioned infra | Medium | Load test before launch |
| A2 | Users are in US/EU only | CDN and data residency design | High | Product confirms |
| A3 | Write volume is 10% of reads | Read replica strategy changes | Low | Instrument and measure |

Flag assumptions with confidence below "High" — these are design risks.

Step 3: Boundary Definition

Define what is inside the system and what is outside.

• In scope: Components you will design and build
• External dependencies: Existing services, third-party APIs, infrastructure you consume
• Trust boundaries: Where does trusted code call untrusted code? Where does user input enter?
• Team boundaries: Which team owns which component? (affects API design and deployment)

Step 4: Component Design

Each component has ONE responsibility. For every component, specify:

1. Purpose — one sentence describing what it does (if you need two sentences, it's two components)
2. API surface — how other components interact with it
3. Data ownership — what data does it own? What is its source of truth?
4. Failure mode — what happens when this component fails? Who is affected? What degrades?
5. Scaling strategy — horizontal (stateless, behind LB) or vertical (stateful, shard by key)?

Step 5: Data Flow Mapping

For every key workflow, trace the data path:

sequenceDiagram
    participant Client
    participant API Gateway
    participant Service A
    participant Database
    participant Queue
    participant Service B

    Client->>API Gateway: POST /orders
    API Gateway->>Service A: Validate + create order
    Service A->>Database: Write order (ACID)
    Service A->>Queue: Publish OrderCreated
    Queue->>Service B: Process async
    Service B->>Database: Update inventory

For each data flow, annotate:

• Consistency model — strong (ACID), eventual, or causal?
• Failure handling — what if this step fails? Retry? Compensate? Alert?
• Latency budget — how much of the total latency budget does this step consume?

Step 6: Storage Design

For each data store:

Step 7: Options Analysis (MANDATORY for key decisions)

For every significant design decision, present at least 2 options:

### Decision: Message broker selection

| Criterion | Option A: RabbitMQ | Option B: Kafka | Option C: SQS |
|---|---|---|---|
| Ordering guarantee | Per-queue FIFO | Per-partition | FIFO (with dedup) |
| Throughput | 10K msg/s | 100K+ msg/s | Variable (managed) |
| Operational cost | Self-managed | Self-managed | Fully managed |
| Replay capability | No | Yes (log retention) | No |
| Team expertise | Low | Medium | High |
| **Recommendation** | | **Selected** | |

**Rationale:** [Why this option wins given our specific constraints]
**Trade-off acknowledged:** [What we sacrifice by choosing this]

Step 8: Change Impact Mapping

Before finalising, assess what happens when things change:

• What if traffic 10x? — which components break first? Where are the bottlenecks?
• What if a new client type is added? — how much of the design needs to change?
• What if a third-party dependency goes down? — graceful degradation or total failure?
• What if a data schema needs to evolve? — additive changes easy? Breaking changes planned?
• What if the team doubles? — can components be worked on independently?

Step 9: Confidence Scoring

Rate confidence in each component of the design:

Rule: Any component with confidence below 60 must have a spike or prototype planned before implementation begins.

Diagrams (MANDATORY)

Every system design includes at minimum:

1. Component diagram — boxes and arrows showing services, data stores, queues, external systems
2. Sequence diagram — for the top 2-3 most critical workflows
3. Data flow diagram — showing trust boundaries and data classification

Use Mermaid syntax for all diagrams.

C4 Model Levels

Structure diagrams using the C4 model by Simon Brown. Each level zooms in from the previous:

• Level 1 (Context): The system as a single box, surrounded by external actors (users, roles) and external systems it interacts with. Shows who uses the system and what it depends on
• Level 2 (Container): Zoom into the system boundary. Show the applications, databases, message brokers, and other containers that make up the system. Each container is a separately deployable unit
• Level 3 (Component): Zoom into a single container. Show the major components (modules, services, controllers) within that container and their responsibilities

Every system design should include at least Level 1 and Level 2 diagrams. Level 3 is recommended for complex or high-risk containers.

Anti-Patterns (NEVER do these)

• Premature microservices — start with a modular monolith unless you have proven scaling needs at component boundaries
• Distributed monolith — microservices that must deploy together are a monolith with network calls
• Shared database — if two services share a database, they are one service. Data ownership is singular
• Synchronous chains — A calls B calls C calls D synchronously. One failure kills everything. Use async where possible
• No failure modes — every design must answer "what happens when X fails?" for every component
• Buzzword architecture — choosing Kafka, Kubernetes, or event sourcing because they're trendy, not because requirements demand them
• Unquantified NFRs — "fast" and "scalable" are not requirements. Numbers or it doesn't count

Output Structure

The output format aligns with arc42 architecture documentation, covering context, building blocks, runtime views, deployment, and cross-cutting concerns. Use the system-design template (templates/system-design.md) for arc42-aligned output structure.

Output Format

# System Design: [name]

## Requirements
### Functional
[Bulleted list]
### Non-Functional
[Table with quantified targets]

## Assumptions
[Assumption ledger table]

## Architecture
### Component Diagram
[Mermaid diagram]
### Components
[For each: purpose, API, data, failure mode, scaling]

## Data Flows
[Sequence diagrams for key workflows]

## Storage Design
[Per-store specification table]

## Key Decisions
[Options analysis for each major decision]

## Change Impact
[What-if analysis]

## Confidence Assessment
[Component confidence table]

## Risks and Mitigations
[Prioritised list]

## Recommended ADRs
[List of decisions that warrant an ADR — suggest via `/architect:write-adr`]