System Design

Design systems, APIs, data models, and service architectures. Start from requirements and constraints, work through trade-offs, and produce a concrete design with diagrams, schemas, and interface definitions.

Workflow

Step 1: Clarify Requirements

Before designing anything, establish what the system needs to do.

Functional Requirements

• What are the core use cases? List them explicitly.
• What are the inputs and outputs for each use case?
• What are the user-facing operations (reads vs. writes)?
• What are the non-obvious requirements (search, analytics, notifications)?

Non-Functional Requirements

• Scale: How many users? Requests per second? Data volume?
• Latency: What response times are acceptable? (p50, p99)
• Availability: What uptime is required? (99.9% = 8.7 hours downtime/year)
• Consistency: Can we tolerate eventual consistency, or do we need strong?
• Durability: What data loss is acceptable? (zero for financial, some for analytics)
• Compliance: GDPR, HIPAA, SOC 2, PCI-DSS constraints?

Constraints

• Team size and expertise.
• Budget (infrastructure, third-party services).
• Timeline (MVP vs. production-grade).
• Existing infrastructure to integrate with.

If the user hasn't specified these, ask the most critical questions before proceeding. Don't design in a vacuum.

Step 2: High-Level Architecture

Sketch the major components and how they interact:

• Client layer: What clients exist (web, mobile, API consumers)?
• API layer: How do clients communicate with the backend?
• Service layer: What are the core services and their responsibilities?
• Data layer: What data stores are needed and why?
• Infrastructure: CDN, load balancer, message queue, cache, search.

Represent this as a text-based diagram:

[Client] --> [API Gateway / Load Balancer]
                    |
         +----------+----------+
         |          |          |
    [Auth Svc]  [Core Svc]  [Notification Svc]
         |          |          |
    [User DB]  [Main DB]   [Queue]
                [Cache]

Step 3: Data Model

Design the core data entities and their relationships:

-- Example: E-commerce order system
CREATE TABLE users (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email       VARCHAR(255) UNIQUE NOT NULL,
    name        VARCHAR(255) NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE orders (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id     UUID NOT NULL REFERENCES users(id),
    status      VARCHAR(50) NOT NULL DEFAULT 'pending',
    total_cents BIGINT NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_status ON orders(status) WHERE status != 'completed';

Consider:

• Primary keys: UUID vs. auto-increment (distributed systems favor UUIDs).
• Indexes: Design for your query patterns, not just the schema.
• Denormalization: Where is read performance more important than write simplicity?
• Partitioning: Will any table grow beyond what a single node can handle?
• Soft deletes vs. hard deletes: Compliance and audit trail requirements.

Step 4: API Design

Define the interface between components:

## API: Order Service

### Create Order
POST /api/v1/orders
Auth: Bearer token (required)
Rate limit: 10 req/min per user

Request:
{
  "items": [
    { "product_id": "uuid", "quantity": 1 }
  ],
  "shipping_address_id": "uuid"
}

Response: 201 Created
{
  "id": "uuid",
  "status": "pending",
  "total_cents": 4999,
  "created_at": "2024-01-15T10:30:00Z"
}

Errors:
- 400: Invalid input (missing items, invalid product_id)
- 401: Not authenticated
- 409: Insufficient stock
- 429: Rate limit exceeded

Design principles:

• Use consistent naming conventions (snake_case or camelCase, pick one).
• Version your API from the start (/v1/).
• Use standard HTTP status codes correctly.
• Design for idempotency on write operations.
• Include pagination for list endpoints.
• Document error responses as carefully as success responses.

Step 5: Analyze Trade-offs

For each significant design decision, document:

• What are the alternatives?
• Why did we choose this option?
• What are we giving up?
• Under what conditions would we revisit this decision?

Step 6: Address Cross-Cutting Concerns

• Authentication and authorization: How are users identified? What access control model?
• Observability: Logging, metrics, tracing, alerting.
• Error handling: Retry strategies, circuit breakers, dead letter queues.
• Security: Encryption at rest and in transit, input validation, rate limiting.
• Deployment: CI/CD, blue-green, canary, rollback strategy.
• Disaster recovery: Backup strategy, failover, RTO/RPO targets.

Output Format

# System Design: <System Name>

## Requirements

### Functional
- <requirement 1>
- <requirement 2>

### Non-Functional
- Scale: <numbers>
- Latency: <targets>
- Availability: <target>

### Constraints
- <constraint>

## Architecture

<text-based diagram>

### Components
| Component       | Responsibility           | Technology    | Why            |
|-----------------|--------------------------|---------------|----------------|
| API Gateway     | Routing, rate limiting   | Kong / Nginx  | Team expertise |
| Order Service   | Order lifecycle          | Node.js       | Existing stack |
| PostgreSQL      | Transactional data       | PostgreSQL 16 | ACID needed    |
| Redis           | Session cache, rate limits | Redis 7     | Low latency    |

## Data Model

<schema with key indexes and relationships>

## API Design

<endpoint definitions with request/response examples>

## Key Design Decisions

### Decision 1: <Title>
**Choice**: <what we chose>
**Alternatives**: <what else we considered>
**Rationale**: <why>
**Trade-off**: <what we gave up>

## Scalability Plan

How the system grows from current scale to 10x and 100x.

## Open Questions

- <unresolved question that needs more input>

Examples

User: "Design a URL shortener" Action: Clarify scale (how many URLs/day, read:write ratio), design a simple service with hash-based short codes, a key-value store for lookups, and a redirect service. Address analytics, expiration, and abuse prevention.

User: "How should we architect our notification system?" Action: Clarify notification types (email, push, in-app, SMS), volume, latency requirements. Design a fan-out architecture with a message queue, delivery services per channel, and user preference management.

User: "Design the API for our billing service" Action: Focus on API design: endpoints for subscriptions, invoices, payments, and webhooks. Include idempotency keys, error handling, and webhook retry logic.

Best Practices

• Start with requirements, not technology. "We need Kafka" is a solution. "We need to process 50k events/sec with at-least-once delivery" is a requirement.
• Design for the scale you'll have in 12 months, not 5 years. Over-engineering is as costly as under-engineering.
• Every component should justify its existence. Each new service adds operational overhead, network hops, and failure modes.
• Favor boring technology. Mature, well-understood tools have fewer surprises than cutting-edge ones.
• Make the common case fast, the uncommon case possible. Optimize for your actual traffic patterns.
• Design for failure. Every network call can fail. Every service can go down. Plan for it explicitly.
• Document your assumptions. When they change, you'll know which parts of the design to revisit.
• Start with a monolith, extract services when you have clear boundaries. Premature microservices create distributed monoliths.