system-design-generator

システム設計ジェネレーター

要件に基づいて、包括的なシステムアーキテクチャ計画を作成します。

システム設計ドキュメントのテンプレート

# System Design: [Feature/Product Name]

## Overview

Brief description of what we're building and why.

## Requirements

### Functional

- User can upload videos (max 1GB)
- System processes video within 5 minutes
- User receives notification when complete

### Non-Functional

- Handle 1000 uploads/day
- 99.9% uptime
- Process videos in <5 minutes (p95)
- Cost: <$0.50 per video

## High-Level Architecture

┌─────────┐ ┌──────────┐ ┌─────────────┐ │ クライアント │─────▶│ API │─────▶│ アップロード │ │ │ │ ゲートウェイ │ │ サービス │ └─────────┘ └──────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ ストレージ │ │ (S3) │ └─────────────┘ │ ▼ ┌─────────────┐ │ 処理 │◀─┐ │ キュー │ │ └─────────────┘ │ │ │ ▼ │ ┌─────────────┐ │ │ プロセッサー │─┘ │ ワーカー │ └─────────────┘ │ ▼ ┌─────────────┐ │ 通知 │ │ サービス │ └─────────────┘

## Components

### 1. API Gateway
**Responsibilities:**
- Authentication
- Rate limiting
- Request routing

**Technology:** Kong/AWS API Gateway
**Scaling:** Auto-scale based on requests/sec

### 2. Upload Service
**Responsibilities:**
- Generate pre-signed S3 URLs
- Validate file metadata
- Enqueue processing jobs

**API:**

POST /uploads リクエスト：{ filename, size, content_type } レスポンス：{ upload_url, upload_id }

**Technology:** Node.js + Express
**Scaling:** Horizontal (stateless)

### 3. Storage (S3)
**Responsibilities:**
- Store raw videos
- Store processed outputs
- Serve content via CDN

**Structure:**

/uploads/{user_id}/{upload_id}/original.mp4 /processed/{user_id}/{upload_id}/output.mp4

### 4. Processing Queue
**Responsibilities:**
- Buffer processing jobs
- Ensure at-least-once delivery
- DLQ for failed jobs

**Technology:** AWS SQS
**Configuration:**
- Visibility timeout: 15 minutes
- DLQ after 3 retries

### 5. Processor Workers
**Responsibilities:**
- Transcode videos
- Generate thumbnails
- Update database

**Technology:** Python + FFmpeg
**Scaling:** Auto-scale on queue depth

## Data Flow

### Upload Flow
1. Client requests upload URL from Upload Service
2. Upload Service generates pre-signed S3 URL
3. Client uploads directly to S3
4. Client notifies Upload Service of completion
5. Upload Service enqueues processing job
6. Returns upload_id to client

### Processing Flow
1. Worker polls queue for jobs
2. Downloads video from S3
3. Processes video (transcode, thumbnail)
4. Uploads results to S3
5. Updates database status
6. Sends notification
7. Deletes message from queue

## Data Model

```typescript
interface Upload {
  id: string;
  user_id: string;
  filename: string;
  size: number;
  status: 'pending' | 'processing' | 'complete' | 'failed';
  original_url: string;
  processed_url?: string;
  created_at: Date;
  processed_at?: Date;
}

interface ProcessingJob {
  upload_id: string;
  attempts: number;
  error?: string;
}

API コントラクト

アップロードエンドポイント

POST   /uploads           - Request upload URL
GET    /uploads/:id       - Get upload status
DELETE /uploads/:id       - Cancel upload
GET    /uploads           - List user uploads

Webhook

POST {webhook_url}
{
  "event": "upload.completed",
  "upload_id": "...",
  "status": "complete",
  "processed_url": "..."
}

スケーリングに関する考慮事項

現在の処理能力

• 1日あたり1000件のアップロード＝約1分あたり1件
• 単一のワーカーで5分ごとに動画を1本処理できます
• 現在の負荷には5台のワーカーが必要です

10倍の規模（1日あたり10,000件）

• 1分あたり約10件のアップロード
• 50台のワーカーが必要です
• コスト削減のためにスポットインスタンスを使用します
• ステータス確認用にRedisキャッシュを追加します

100倍の規模（1日あたり100,000件）

• 1分あたり約100件のアップロード
• リージョンごとにパーティション分割します
• SQS の代わりに Kafka を使用します
• user_id でデータベースをシャーディングします

障害モード

S3 が利用できない場合

• 影響：アップロードに失敗します
• 緩和策：S3 のマルチリージョンレプリケーション

キューが滞留した場合

• 影響：処理が遅延します
• 緩和策：ワーカーをより迅速に自動スケーリングします

処理中にワーカーがクラッシュした場合

• 影響：ジョブが再試行されます
• 緩和策：冪等な処理

コストの見積もり

月額（1日あたり1000件のアップロード）：

• S3 ストレージ：$50
• S3 転送：$100
• SQS：$10
• ワーカー（EC2）：$300
• データベース：$100 合計：約$560/月

セキュリティ

• 署名付き URL の有効期限は1時間です
• 動画はプライベート S3 バケットに保存します
• 配信には CloudFront の署名付き URL を使用します
• ユーザーごとにレート制限を設けます

モニタリング

メトリクス：

• アップロード成功率
• 処理時間（p50、p95、p99）
• キューの深さ
• ワーカーの CPU／メモリ
• 種類別のエラー率

アラート：

• キューの深さが1000を超えた場合
• 処理時間の p95 が10分を超えた場合
• エラー率が5％を超えた場合

未解決の質問

• 動画の保持ポリシーは？（30日？1年？）
• 動画の最大長は？（処理時間に影響します）
• 地域ごとのデータ保存に関する要件は？

## Component Template

```markdown
### Component Name

**Responsibilities:**
- Primary responsibility
- Secondary responsibility

**Technology Stack:**
- Language: [Python/Node/Go]
- Framework: [Express/FastAPI/Gin]
- Database: [PostgreSQL/MongoDB]

**API/Interface:**
```typescript
interface ComponentAPI {
  method(params): ReturnType;
}

スケーリング戦略：

• 水平：ステートレス、負荷分散
• 垂直：キャッシュレイヤー、コネクションプーリング

依存関係：

• サービス A（X 用）
• データベース B（永続化用）

障害処理：

• 指数バックオフで再試行
• 下流サービス用のサーキットブレーカー
• キャッシュデータへのフォールバック

## Best Practices

1. **Start with requirements**: Functional + non-functional
2. **Draw diagrams first**: Visual clarity
3. **Define boundaries**: What's in scope vs out
4. **Document tradeoffs**: Every choice has costs
5. **Plan for failure**: What breaks and how to handle
6. **Consider scale**: Current, 10x, 100x
7. **Estimate costs**: Build vs buy decisions
8. **Leave open questions**: Don't pretend to know everything

## Output Checklist

- [ ] Requirements documented (functional + non-functional)
- [ ] High-level architecture diagram
- [ ] Component breakdown (3-7 components)
- [ ] Data flow documented
- [ ] Data model defined
- [ ] API contracts specified
- [ ] Scaling considerations (1x, 10x, 100x)
- [ ] Failure modes identified
- [ ] Cost estimate provided
- [ ] Security considerations
- [ ] Monitoring plan