prasoonsoni/system-design-studio

System Design Studio

ユーザーがシステムの高レベル設計（HLD）の設計、説明、学習を依頼した場合に使用します。例：「Uberを設計して」「Netflixのシステム設計」「ペイメントゲートウェイのHLD」「URL短縮サービスを設計して」「Xを設計する面接対策」。成果物は、ライトモードとダークモードを備え、オプションでインタラクティブなキャンバスコンパニオンも持つ、自己完結型でナビゲーション可能なHTMLデザインドキュメントをアーティファクトとして公開します。ユーザーがローカルで実行するファイルを希望する場合は、ガイドとキャンバスをタブ付きの1つのHTMLページ（§9）として提供します。

このリポジトリの参考例は、品質基準を示しています：examples/stock-broker/（デフォルトテーマ、ガイドとキャンバスは別々のページ）および examples/uber/（プロダクトテーマ、手描きのアーキテクチャSVG、ガイドとキャンバスは1つのファイル）。

1. 対象とテーマを決定する

まずリクエストを分類します。これにより、コンテンツの角度と外観の両方が決まります。

• 名前のある製品または企業（Uber、Netflix、WhatsApp、Swiggy、Zerodha、Airbnb、Spotify、Stripe、Instagramなど）：ガイドは「<企業名>のシステム設計」となり、その製品の世界に合わせたテーマになります（§5.2参照）。企業独自のドメイン用語をすべての場所で使用します（Uber：ライダー、ドライバー、トリップ、ディスパッチ、サーチ、ETA；Netflix：タイトル、再生、CDN、エンコーディングラダー；WhatsApp：チャット、配信確認、最終閲覧など）。
• 汎用的なシステム（URL短縮サービス、チャットアプリ、ペイメントゲートウェイ、レートリミッター、通知サービス、企業名が指定されていない「ライドシェアアプリ」など）、または特定できない不明な製品の場合は、デフォルトのテンプレートテーマ（§5.1）を使用します。
• ユーザーがスタイルを指定した場合（「Stripeのドキュメントのようにして」「シンプルでミニマルに」）：上記のルールよりもその指示に従います。

名前のある企業の場合、設計の前に調査を行います：公開されているエンジニアリングブログ記事や講演についてウェブ検索を実行します（例：Uber：H3地理空間インデックス、Ringpop、Schemaless、Cadence；Netflix：Open Connect、EVCache、Zuul）。公開されている情報を使用し、そのように明記し（「Uber Engineeringのブログより」）、ガイドのフッターに情報源をリストアップし、それ以外はすべて仮定としてラベル付けします。推測に基づく設計を、その企業の実際の内部アーキテクチャとして提示することは決してしないでください。

2. 構築前にブレインストーミングする

HTMLを書く前に、以下の項目を整理し（1つの短いメッセージでユーザーに伝えます）：

• ドメインの支配的な洞察：見逃すと設計全体が間違ってしまう、1つの境界またはアイデア。例：「ブローカーはルーティングし、取引所はマッチングする」「ペイメントゲートウェイは資金を保持せず、アクワイアラーが行う」「Uberのディスパッチは、秒単位のレイテンシ予算内での地理空間マッチング問題である」。概要にコールアウトとして記載します。
• プレーン：どのパスが強い整合性を必要とするか（マネー、注文、在庫、予約 → CP）と、どのパスが可用性を優先するか（フィード、検索、プレゼンス、位置情報ping、分析 → AP）。それらをエッジで分離します。
• 難しい問題：冪等性、順序付け、ファンアウト、ホットキー、地理的パーティショニング、調整、exactly-onceの主張。
• スコープ内 / スコープ外（外部統合として扱われるもの）。
• §1からのテーマの決定：どのプロダクトテーマか、またはデフォルトか。

リクエストが真に曖昧な場合（どの製品か？面接の深さか本番の深さか？）、1つの質問をします。それ以外の場合は開始します。

3. 必要なセクション（番号順、この順序で）

1. 概要：システムの説明、支配的な洞察のコールアウト、スコープ内/スコープ外のリスト。
2. 要件：機能テーブル（ドメイン → 機能、ドメインの実際の語彙と列挙型を使用）および非機能テーブル（属性 → ターゲット → 備考）。常にレイテンシ、可用性、整合性（パスごとのCP/AP）、耐久性、スケーラビリティ、セキュリティ、冪等性を含めます。
3. キャパシティ見積もり：前提 → 導出された数値（ユーザー数、DAU、ピーク同時接続数、平均およびピークの書き込み数/秒、読み取り数/秒、ファンアウト出力、ストレージ/日）のテーブル。計算式を示して確認可能にし、各プレーンがどの軸でスケールするかについての要点をコールアウトで締めくくります。実際の企業の場合、公開されている規模に基づいて数値を固定し、引用します。
4. アーキテクチャ：レンダリングされた図（§6参照）と、各プレーンおよびイベントバックボーンに関する散文。
5. コンポーネント詳細解説：コアサービスごとに、責任、動作メカニズム（ステートマシン、プロトコル、アルゴリズム）、所有データ、障害処理。
6. コアフローライフサイクル：製品の代表的エンドツーエンドフロー（Uber：ライドをリクエスト → マッチング → トリップ；Netflix：再生を押す → ストリーム；WhatsApp：メッセージ送信 → 配信 → 既読）をステップテーブル（#、ステップ、所有者、状態/イベント）で示し、同期 vs 非同期の境界に関するコールアウトを追加します。
7. データモデルとスキーマ：ER/クラス図（§6参照）、次に非リレーショナルストア（キャッシュキーパターン、時系列レイアウト、地理インデックス、検索インデックス）、次にイベントトピック（トピック、パーティションキー、イベント）と1つのサンプルイベントJSON。メインのスキーマビューとして生のSQL DDLをダンプしないでください。
8. API設計：規約テーブル（認証、冪等性、エラーエンベロープ、レート制限、ページネーション、バージョン管理）、色付きメソッドピルを含むエンドポイントテーブル、主要な書き込み操作の1つの動作済みリクエスト/レスポンスペア（ステータスコードのセマンティクス、例：非同期の場合は202）、ステータスコードテーブル、およびストリーミングプロトコル（該当する場合、WebSocket/SSE/gRPCストリーム）。
9. 整合性と信頼性：各保証が適用される場所、サーガと補償、冪等性レイヤー、障害シナリオテーブル。
10. スケーリングとパフォーマンス：シャーディングキー、ステートレスオートスケーリング、パーティショニング、キャッシング、スパイク処理。
11. セキュリティとコンプライアンス：認証/認可、データ保護、規制による保持、不正利用対策。
12. 可観測性：ゴールデンメトリクス、トレーシング、調整ダッシュボード、アラート。
13. トレードオフ：決定 → 選択と理由のテーブル、最後に「覚えておくべき5つのこと」コールアウト。

4. 正確性基準（公開前に確認すること）

• キャパシティのすべての数値は、明示された前提から導出されており、内部で整合性があります（平均 vs ピークの倍率が明記されています）。
• アーキテクチャ図のすべてのコンポーネントは、詳細解説またはフローに登場し、その逆も同様です。
• ER図のすべてのエンティティは、いくつかのフローまたはAPIで使用されています。すべてのAPIの書き込みパスは、実際のエンティティに触れています。
• スキーマセクションのKafka/キュートピックは、アーキテクチャ図のエッジラベルと一致します。
• マネーが存在する場合、マネーは複式簿記の元帳としてモデル化されます。冪等性キーはスキーマ（一意制約）とAPI（ヘッダー）の両方に登場します。
• ドメインの実際の用語（注文タイプ、FIX/ISO 8583などのプロトコル、規制）を使用し、何かが仮定である場合はその旨を明記します。
• 名前のある企業の場合：実際のスタックに関するすべての主張には情報源があり、それ以外はすべて仮定としてマークされています。
• 真のexactly-onceを主張しないでください。冪等性と調整について説明します。

5. テーマ設定、ライトモード、ダークモード

すべてのガイドにはライトモードとダークモードの両方が含まれます：デフォルトでは読者のシステム設定に従い、ヘッダーのトグルで上書きできます（ブラウザごとに記憶されます）。ページを作成する前に、artifact-design スキルを読み込んでください。

5.0 トークンシステム（両モード）

すべての色はCSSカスタムプロパティです。ルール、SVG、図で色をハードコードせず、常にトークンを使用します。:root にライト値を定義し、次にダーク値を2回（システム設定がダークで読者がライトを選択していない場合、および明示的なダーク選択の場合）定義します：

:root{ color-scheme:light; /* ライトトークン */ }
@media (prefers-color-scheme: dark){
  :root:not([data-theme="light"]){ color-scheme:dark; /* ダークトークン */ }
}
:root[data-theme="dark"]{ color-scheme:dark; /* ダークトークン、繰り返し */ }
body{ background:var(--bg); color:var(--ink); }

必要なトークンロール（各テーマは両モードですべてを設定します）。プレーンな16進値を使用します（rgba(...) は不可）。図レンダラーがカンマで分割するためです：

トークン	ロール
--bg, --surface, --surface-2, --line, --line-soft	ページ、カード、浮き出たカード、境界線
--ink, --ink-mid, --ink-dim	見出し/強調テキスト、本文、キャプション
--accent, --accent-ink	テーマのシグネチャカラー、およびその上に描画されるテキスト
--svc, --svc-bg	図のサービス
--bus, --bus-bg	キュー / イベントバス
--ext, --ext-bg	外部システム
--store, --store-bg	データストア
--ok, --warn, --danger, --info	コールアウト、メソッドピル、CP/APピル
--code-bg, --code-ink, --code-key, --code-str, --code-num, --code-com	コードブロック
--font-display, --font-body, --font-mono	フォントファミリー

コントラスト：本文テキスト（--bg と --surface 上の --ink-mid）は、両モードで少なくとも4.5:1。--surface 上のアクセントテキストは少なくとも4.5:1。ダークで機能する明るいアクセントは、通常ライトモードではより暗い色合いが必要なため、値を再利用するのではなく、各モードの値を個別に選択します。

スタイルシートの前に <head> にこれを配置し、保存された選択がフラッシュなしで適用されるようにします：

<script>
(function(){var t=null;try{t=localStorage.getItem('sdg-theme')}catch(e){}
if(t==='light'||t==='dark')document.documentElement.dataset.theme=t;})();
</script>

ヘッダーのトグルボタン（<button class="theme-toggle" id="themeToggle" aria-label="カラーテーマを切り替える"></button>）とそのスクリプトを <body> の終わり近くに配置します：

<script>
(function(){
  var root=document.documentElement, mq=matchMedia('(prefers-color-scheme: dark)');
  function current(){return root.dataset.theme||(mq.matches?'dark':'light');}
  function label(){var b=document.getElementById('themeToggle');if(b)b.textContent=current()==='dark'?'☀ Light':'☾ Dark';}
  document.getElementById('themeToggle').addEventListener('click',function(){
    var next=current()==='dark'?'light':'dark';root.dataset.theme=next;
    try{localStorage.setItem('sdg-theme',next)}catch(e){}
    label();document.dispatchEvent(new Event('themechange'));});
  mq.addEventListener('change',function(){if(!root.dataset.theme){label();document.dispatchEvent(new Event('themechange'));}});
  label();
})();
</script>

5.1 デフォルトテンプレートテーマ（汎用システム）

名前のある製品に紐づかないものに対するハウススタイル：

• フォント：Space Grotesk（表示用）、Inter（本文）、JetBrains Mono（識別子、列挙型、トピック、パス用）。
• ダーク：ミッドナイトベース。--bg #0a0e17, --surface #141b2c, --surface-2 #1a2336, --line #28324e, --ink #eaf0fb, --ink-mid #aab6d2, --ink-dim #7a86a4, --accent #5ec7df, --svc #4fd0e0/--svc-bg #152036, --bus #f3ab54/--bus-bg #241d12, --ext #fb7f95/--ext-bg #2a1622, --store #93a3c0/--store-bg #131b2c。
• ライト：クールなペーパー。--bg #f6f8fc, --surface #ffffff, --surface-2 #eef2f8, --line #d6deea, --ink #0f1729, --ink-mid #45536b, --ink-dim #5f6c85, --accent #0b7287, --svc #0b7287/--svc-bg #e3f3f7, --bus #a35a00/--bus-bg #fdf0dd, --ext #b4234a/--ext-bg #fde7ec, --store #55627a/--store-bg #eef1f6。
• レイアウト：ヒーロー（アイブロウ、タイトル、支配的な洞察を含む1段落の概要、4つのTL;DRカード：ピークスケール、接続、CPパス、APパス）、次にデスクトップではスティッキーな目次とスクロールスパイを備えた2カラム本文、モバイルではフローティング「☰ 目次」ドロワー。

5.2 プロダクトテーマ（名前のある企業）

ページは、明確に独立した調査でありながら、そのプロダクトの世界に属しているように感じられるべきです。プロダクトの公開されているビジュアルキャラクター（パレット、フォントの雰囲気、シェイプ言語（シャープ vs ラウンド）、密度、および1つのシグネチャモチーフ）から、完全なトークンセット（両モード）を導出します。出発点（概算、コピーではなく喚起する）：

プロダクト	パレットの方向性	フォント（無料代替）	シェイプとモチーフ
Uber	モノクロ黒/白、1つのグリーンアクセント	Inter Tight、太めの表示用ウェイト	シャープな角、ハイコントラスト；マップのルートラインと乗車/降車地点のドット
Netflix	ニアブラック＋深いレッドアクセント；ライトモードは暖かい白＋赤	Bebas Neue（表示用）、Inter（本文）	シネマティックな大きな見出し、ポスターカードの行
WhatsApp	ソフトなニュートラルにティールグリーン；ダークモードは深いグリーングレー	Inter / システムUI	チャットバブルのコールアウト、複数チェックのステータスマーク
Airbnb	暖かい白＋コーラルアクセント	Nunito Sans	たっぷりとしたラウンド、ソフトなシャドウ、フレンドリーな間隔
Spotify	黒＋ブライトグリーン；ライトモードは白＋グリーン	Figtree または DM Sans	ピルボタン、ウェーブフォーム/プログレスバーモチーフ
Stripe	ライトファースト、インディゴ/バイオレットアクセント、ソフトグラデーション	Inter	鮮明なヘアライン、コードブロックが第一級
Swiggy / Zomato	クリームに暖かいオレンジまたはレッド；ダークはダークブラウンブラック	Poppins	ラウンドカード、注文追跡タイムライン
Zerodha	クリーンな白＋ブルーアクセント；ダークはダークスレート	Inter	高密度データテーブル、ティッカーストリップ

テーブルにない企業の場合も、同じ方法を適用します：シグネチャカラー、ムード、モチーフを特定し、両モードを構築します。

プロダクトテーマのガードレール：

• インスパイアされたものであり、決してコピーしないこと。 ロゴ、ワードマーク、アプリアイコン、マスコット、スクリーンショット、コピーされたUI画面、およびプロプライエタリな書体（Uber Move、Netflix Sans、Circular、Cereal）は使用しないでください。代わりに無料の代替フォントを使用します。モチーフは一般的に描画されます（ルートライン、チャットバブル）。プロダクトからそのまま引用しないでください。
• タイトルは調査として表記します：「Uberのシステム設計」や「Uber規模のライドヘイリングプラットフォームの設計」とし、Uber自身が公開したかのように見せないでください。
• フッターには常に：「独立した教育目的の調査。<企業名>とは提携しておらず、その承認も受けていません。アーキテクチャは公開情報と明示された前提から再構築されました。」と情報源リストを記載します。
• 図、テーブル、コールアウト、ピルは、デフォルトテンプレートと同じコンポーネント構造を、トークンを通して色を変えて使用します。プロダクトテーマは外観を変更しますが、13セクションの構造は変更しません。

5.3 共通コンポーネント

• テーブルはラウンドされたスクロールラッパー内に配置。コールアウト（key / warn / info / note）は色付きの左バー付き。メソッドピル（GET --ok, POST --info, PUT --warn, DELETE --danger）、CP/APピル。
• コードブロックはJSONペイロード、キーパターン、プロトコルメッセージのみに使用し、言語またはエンドポイントを示すヘッダーバーと、--code-* トークンからのシンタックスカラーを付けます。
• 電話幅…

…（以降も同様に翻訳）