System Design

# Skill: System Design (Cross-Cutting)

## Purpose

Evaluate architectural decisions, design API endpoints, model data schemas, and analyze trade-offs.

## When to Use

- When architecting a new microservice, system, or database model
- When defining API boundaries and integration contracts between components
- When scaling system capacities and outlining horizontal/vertical tradeoffs

## Step-by-Step Process

### Step 1: Gather Requirements & Constraints
- List functional requirements (what the system must do)
- List non-functional requirements (throughput, scale, latency, availability)
- Identify technical constraints (team skill set, budget, timeline, existing stack)

### Step 2: High-Level Design
- Map out system components (services, clients, data stores)
- Outline data flow and request/response lifecycles
- Choose datastores (SQL, NoSQL, Cache, Document store)

### Step 3: Deep Dive & Contract Design
- Define database schema models and indexing strategies
- Design concrete API contracts (REST endpoints, GraphQL query structures, gRPC specs)
- Design error-handling patterns, caching strategies, and event queue definitions

### Step 4: Trade-off Analysis
- Document choices explicitly using architectural trade-offs (e.g. Read latency vs Write latency)
- Formulate scaling strategies (sharding, replication, failover mechanisms)

## Required Input

- Architecture goals, specifications, or user stories
- Expected load (requests per second, data size)
- Pre-existing tech stack constraints

## Expected Output

- System design document containing:
  - Architecture diagram (ASCII or Mermaid)
  - Data model and DB schema
  - API endpoint specifications
  - Cache/Queue strategy
  - Explicit trade-off analysis

## Tone & Rules

- Every design decision must have a corresponding trade-off analyzed.
- Keep designs modular and explain service boundaries clearly.
- Avoid over-engineering. Design for 10x scale, but build for 1.5x scale.

## Available Templates

- None

## Available Scripts

- None

## Examples

See `examples/` directory.

## Links to Other Skills

- **documents**: Use to generate product and technical specification documents.
- **suggestion**: Use to analyze existing systems and suggest architectural improvements.