System Design Documents

System design documents describe how a system works at a high level, serving as a reference for development, operations, and onboarding.

Document Structure

# System Design: Order Processing Platform

## 1. Overview
Brief description of the system's purpose and scope.

## 2. Goals and Non-Goals
What the system aims to achieve and explicit exclusions.

## 3. Architecture
High-level system architecture with diagrams.

## 4. Data Model
Key entities, relationships, and storage decisions.

## 5. API Design
External and internal interfaces.

## 6. Scalability
How the system handles growth.

## 7. Reliability
Failure modes and recovery strategies.

## 8. Security
Authentication, authorization, data protection.

## 9. Monitoring
Observability, alerting, dashboards.

## 10. Deployment
Infrastructure, CI/CD, rollout strategy.

Example: Order Processing System

Overview

## Overview

The Order Processing Platform handles the complete lifecycle of 
customer orders from placement through fulfillment. It processes 
approximately 50,000 orders daily with peak loads of 500 orders 
per minute during sales events.

### Key Capabilities
- Real-time order placement and validation
- Payment processing integration
- Inventory reservation and management
- Fulfillment orchestration
- Order tracking and notifications

Architecture Diagram

Data Model

## Data Model

### Order Aggregate

public class Order
{
    public Guid Id { get; private set; }
    public Guid CustomerId { get; private set; }
    public OrderStatus Status { get; private set; }
    public List<OrderItem> Items { get; private set; }
    public Address ShippingAddress { get; private set; }
    public Address BillingAddress { get; private set; }
    public Money Subtotal { get; private set; }
    public Money Tax { get; private set; }
    public Money ShippingCost { get; private set; }
    public Money Total { get; private set; }
    public PaymentInfo Payment { get; private set; }
    public DateTime CreatedAt { get; private set; }
    public DateTime? ShippedAt { get; private set; }
}

public class OrderItem
{
    public Guid ProductId { get; private set; }
    public string ProductName { get; private set; }
    public string Sku { get; private set; }
    public int Quantity { get; private set; }
    public Money UnitPrice { get; private set; }
}

### Storage Decisions

| Data | Store | Rationale |
|------|-------|-----------|
| Orders | PostgreSQL | ACID transactions, complex queries |
| Order Events | EventStoreDB | Event sourcing, audit trail |
| Inventory | PostgreSQL + Redis | Strong consistency + fast reads |
| Sessions | Redis | Fast access, TTL support |
| Search | Elasticsearch | Full-text search, faceting |

API Design

## API Design

### REST Endpoints

#### Create Order
```
POST /api/v1/orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "items": [
    { "productId": "uuid", "quantity": 2 }
  ],
  "shippingAddress": { ... },
  "paymentMethodId": "pm_xxx"
}

Response: 201 Created
{
  "orderId": "uuid",
  "status": "pending_payment",
  "estimatedDelivery": "2024-02-15"
}
```

#### Get Order
```
GET /api/v1/orders/{orderId}
Authorization: Bearer {token}

Response: 200 OK
{
  "orderId": "uuid",
  "status": "shipped",
  "items": [...],
  "tracking": {
    "carrier": "FedEx",
    "trackingNumber": "xxx",
    "estimatedDelivery": "2024-02-15"
  }
}
```

### Events Published

| Event | Trigger | Consumers |
|-------|---------|-----------|
| OrderCreated | Order placed | Inventory, Analytics |
| OrderPaid | Payment confirmed | Fulfillment, Notification |
| OrderShipped | Shipment created | Notification, Analytics |
| OrderDelivered | Delivery confirmed | Notification, Reviews |

Scalability

## Scalability

### Current Capacity
- 500 orders/minute sustained
- 2000 orders/minute peak (tested)
- 10M orders stored

### Scaling Strategy

#### Horizontal Scaling
- Order Service: Stateless, scale to 10+ instances
- Database: Read replicas for queries, primary for writes
- Cache: Redis Cluster with 6 nodes

#### Bottleneck Analysis
| Component | Current | Limit | Scale Strategy |
|-----------|---------|-------|----------------|
| API Gateway | 5K rps | 10K rps | Add instances |
| Order Service | 1K rps | 5K rps | Add instances |
| Database writes | 500 tps | 2K tps | Sharding by customer |
| Payment API | 100 tps | 200 tps | Queue + rate limit |

### Growth Projections
| Metric | Current | 6 months | 12 months |
|--------|---------|----------|-----------|
| Orders/day | 50K | 100K | 200K |
| Database size | 500GB | 1TB | 2TB |
| Events/day | 500K | 1M | 2M |

Reliability

## Reliability

### SLOs
- Availability: 99.9% (8.7 hours downtime/year)
- Order placement latency: P99 < 500ms
- Order query latency: P99 < 100ms

### Failure Modes

| Failure | Impact | Mitigation |
|---------|--------|------------|
| Database down | Orders fail | Multi-AZ, automatic failover |
| Payment API down | Payments fail | Queue orders, retry |
| Inventory service down | Can't check stock | Cache last known, degrade gracefully |

### Recovery Procedures
1. **Database failover**: Automatic, RTO < 1 minute
2. **Service crash**: Kubernetes restarts, RTO < 30 seconds
3. **Region failure**: DNS failover to DR region, RTO < 15 minutes

Security

## Security

### Authentication
- JWT tokens via Auth0
- Token lifetime: 1 hour
- Refresh tokens: 7 days

### Authorization
- RBAC with roles: customer, support, admin
- Resource-level permissions (users see only their orders)

### Data Protection
- PII encrypted at rest (AES-256)
- TLS 1.3 for all connections
- PCI DSS compliance for payment data
- GDPR: Data export/deletion APIs

### Secrets Management
- HashiCorp Vault for secrets
- Rotated every 90 days
- No secrets in code or config files

Monitoring

## Monitoring

### Key Metrics
- Order creation rate
- Order processing time
- Payment success rate
- Inventory reservation failures
- Error rates by endpoint

### Alerts
| Alert | Condition | Severity |
|-------|-----------|----------|
| High error rate | >1% 5xx errors for 5 min | Critical |
| Slow orders | P99 > 1s for 5 min | Warning |
| Payment failures | >5% failures for 10 min | Critical |
| Low inventory | <10 units for popular items | Warning |

### Dashboards
- Real-time order flow
- Service health
- Business metrics (revenue, conversion)

Document Maintenance

## Document History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2024-01-01 | @jsmith | Initial version |
| 1.1 | 2024-02-15 | @jdoe | Added payment retry logic |
| 2.0 | 2024-03-01 | @jsmith | Event sourcing migration |

## Review Schedule
- Quarterly review by architecture team
- Update required for any significant changes
- Last reviewed: 2024-03-15

Key Takeaways

1. Be Comprehensive: Cover all aspects from API to deployment
2. Use Diagrams: Visual representations aid understanding
3. Include Numbers: Capacity, SLOs, and growth projections
4. Document Decisions: Link to ADRs for major choices
5. Keep Updated: Stale docs are worse than no docs

---

💡 Flashcard

What are the essential sections of a system design document?

Click to reveal answer

✅ Answer

Overview, Goals/Non-Goals, Architecture (with diagrams), Data Model, API Design, Scalability, Reliability, Security, Monitoring, and Deployment. Include specific numbers for capacity and SLOs.

Click to see question

💡 Flashcard

How often should system design documents be reviewed?

Click to reveal answer

✅ Answer

At minimum quarterly, and immediately when significant changes are made. Include a document history section tracking versions and a last-reviewed date to ensure the document stays current.

Click to see question

Loading quiz...