System Design Skill

Purpose

Produce complete, structured, opinionated architecture proposals that teams can act on immediately.

Output Format (always follow this structure)

1. Problem Restatement

One paragraph. Confirm what is being built, the scale expectations, and the main constraints. Forces clarity before designing.

2. Architecture Overview

A high-level Mermaid diagram showing all major components and their relationships.

graph TD
    Client --> APIGateway
    APIGateway --> ServiceA
    APIGateway --> ServiceB
    ServiceA --> DB[(Database)]
    ServiceB --> Cache[(Cache)]

3. Component Breakdown

For each component:

• Role: what it does
• Technology choice: specific tool/language/framework with brief justification
• Interfaces: how it communicates (REST, gRPC, events, etc.)
• Scaling strategy: horizontal / vertical / stateless / etc.

4. Data Flow

Describe the main request/response flows (happy path + at least one failure path). Use a sequence diagram if helpful.

sequenceDiagram
    User->>API: Request
    API->>Service: Process
    Service->>DB: Query
    DB-->>Service: Result
    Service-->>API: Response
    API-->>User: Result

5. Key Design Decisions

A table of the most important trade-offs made:

6. Non-Functional Requirements Coverage

Address explicitly:

• Scalability: how the system scales under load
• Availability: SLA target, redundancy approach
• Latency: expected p50/p99 for critical paths
• Security: auth, encryption, attack surface
• Observability: logging, metrics, tracing strategy

7. Risks & Open Questions

List 3–5 unresolved concerns or assumptions that need validation before implementation.

8. Next Steps

Ordered list of what the team should do first to begin implementation.

Design Principles to Always Apply

• Prefer boring technology for core infrastructure; reserve novelty for differentiating parts
• Design for failure: every external call can fail — show how the system handles it
• Explicit over implicit: no magic, no hidden coupling
• Start with data: model the data before the services
• Avoid premature optimization: design for current scale × 10, not × 1000
• Single responsibility: each component/service does one thing well

Scale Heuristics

Always state the target scale and design accordingly. Do not over-architect.