# System Design

## 1. System Overview

{One paragraph describing what this system does, who it serves, and its primary value proposition.}

## 2. Component Diagram

```
┌────────────────┐     ┌─────────────┐
│ Client App     │────>│ API Gateway │
└────────────────┘     └──────┬──────┘
                              │
                    ┌─────────┼─────────┐
                    v                   v
             ┌────────────┐     ┌──────────┐
             │ Auth Service│     │Core Service│
             └────────────┘     └─────┬────┘
                                      │
                        ┌─────────┬───┴───┬──────────┐
                        v         v       v          v
                  ┌──────────┐ ┌─────┐ ┌─────────┐ ┌────────┐
                  │ Database │ │Cache│ │Msg Queue│ │ Worker │
                  └──────────┘ └─────┘ └─────────┘ └───┬────┘
                                                       │
                                                       v
                                                 ┌──────────┐
                                                 │ Database │
                                                 └──────────┘
```

## 3. Component Responsibilities

### {Component Name}
- **Purpose**: {what this component does}
- **Technology**: {language, framework, runtime}
- **Owns**: {what data/domain this component is responsible for}
- **Depends on**: {what other components it calls}
- **Depended on by**: {what components call it}
- **Scaling**: {how this component scales — horizontal, vertical, auto}

### {Component Name}
- **Purpose**: {what this component does}
- **Technology**: {language, framework, runtime}
- **Owns**: {what data/domain this component is responsible for}
- **Depends on**: {what other components it calls}
- **Depended on by**: {what components call it}
- **Scaling**: {how this component scales}

## 4. Data Flow

### Primary Flow: {flow name, e.g., "User creates an order"}
```
Client          API             Service         Database
  │               │               │               │
  │──POST /resource──>│               │               │
  │               │──validate + process──>│               │
  │               │               │──INSERT──>│
  │               │               │<──confirmation──│
  │               │<──result──│               │
  │<──201 Created──│               │               │
```

### Secondary Flow: {flow name}
{Describe or diagram the flow.}

## 5. API Boundaries

| Boundary | Protocol | Auth | Rate Limit |
|----------|----------|------|------------|
| Client -> API | HTTPS/REST | JWT | 100 req/min |
| API -> Service | gRPC / HTTP | Service token | None (internal) |
| Service -> Database | TCP | Connection pool | N/A |
| Service -> Cache | TCP | N/A | N/A |

## 6. Infrastructure

### Environments
| Environment | Purpose | URL | Notes |
|-------------|---------|-----|-------|
| Local | Development | localhost:{port} | Docker Compose |
| Staging | Pre-production testing | {url} | Mirrors production |
| Production | Live users | {url} | Auto-scaled |

### Infrastructure Components
- **Compute**: {e.g., Kubernetes, ECS, Lambda, bare VM}
- **Database**: {e.g., PostgreSQL on RDS, MongoDB Atlas}
- **Cache**: {e.g., Redis on ElastiCache}
- **Queue**: {e.g., SQS, RabbitMQ, Kafka}
- **Storage**: {e.g., S3 for file uploads}
- **CDN**: {e.g., CloudFront for static assets}
- **Monitoring**: {e.g., Datadog, Prometheus + Grafana}
- **Logging**: {e.g., CloudWatch, ELK stack}

## 7. Scalability Considerations

### Current Capacity
- Expected concurrent users: {number}
- Expected requests per second: {number}
- Expected data volume: {size over time}

### Scaling Strategy
- **Horizontal**: {which components scale horizontally and how}
- **Vertical**: {which components need vertical scaling}
- **Caching**: {what is cached, invalidation strategy}
- **Database**: {read replicas, sharding, partitioning plans}

### Bottlenecks and Mitigations
| Bottleneck | When It Hits | Mitigation |
|-----------|-------------|------------|
| {component} | {at what scale} | {what to do} |