architect

アーキテクト — システム設計

構築を始める前にシステムの構造を決めましょう。優れたアーキテクチャは、あらゆる作業を容易にします。悪いアーキテクチャは、すべてを作り直すことになります。

ステップ 0：制約を把握する

設計する前に、次の質問に答えましょう。

1. 規模 — ユーザーは 100 人ですか、それとも 100,000 人ですか？あらゆる判断に影響します。
2. チームの規模 — 創業者 1 人ですか、それともエンジニア 10 人ですか？小規模なチームには、よりシンプルなシステムが適しています。
3. 予算 — 自己資金で運営していますか、それとも資金調達済みですか？マネージドサービスか、セルフホスト可能な構成かを左右します。
4. スケジュール — 2 週間で MVP を作りますか、それとも 3 か月で v1 を作りますか？
5. コンプライアンス — HIPAA、SOC 2、GDPR に対応する必要がありますか？アーキテクチャの選択肢が制約されます。

アーキテクチャパターン

パターン	使用する場面	避ける場面
モノリス	エンジニア 10 人未満、単一の製品、迅速な開発	複数のチームが独立したデプロイを必要とする場合
モジュラーモノリス	チームが成長しており、インフラコストをかけずに境界を設けたい場合	サービスごとに独立したスケーリングが必要な場合
マイクロサービス	エンジニア 20 人以上、明確に異なるドメイン、独立したスケーリングが必要な場合	小規模なチーム、初期段階、境界が不明確な場合
サーバーレス	イベント駆動型、トラフィックの変動が激しい、運用をゼロにしたい場合	長時間稼働するプロセス、大規模運用でコストに敏感な場合
イベント駆動型	非同期ワークフロー、疎結合システム、監査証跡が必要な場合	シンプルな CRUD、リアルタイム要件がある場合

基本方針： 問題が生じるまではモノリスを使いましょう。時期尚早なマイクロサービス化は、アーキテクチャにおける最大の失敗です。

データベースの選定

ニーズ	データベース	理由
汎用、リレーショナル	PostgreSQL	ACID、JSON サポート、拡張機能、エコシステム
キー・バリュー、キャッシュ	Redis / Valkey	1 ミリ秒未満の読み取り、TTL、pub/sub
ドキュメントストア、柔軟なスキーマ	MongoDB	迅速なプロトタイピング、ネストされたドキュメント
全文検索	PostgreSQL FTS または Meilisearch	必要になるまでは、Postgres の組み込み機能で十分です
時系列	TimescaleDB（Postgres 拡張機能）	データベースエンジンを 1 つに保てます
グラフ関係	再帰 CTE を備えた PostgreSQL	グラフが製品の中核でない限り、Neo4j を追加しないでください
ベクトル／埋め込み	pgvector（Postgres 拡張機能）	同様に、データベースは 1 つに保ちましょう

ルール：

• まずは Postgres から始めましょう。Postgres では対応できない場合にのみ、専用データベースを追加します。
• 常にマネージドサービスを使いましょう（Supabase、Neon、RDS）。データベースを自分で管理しないでください。
• DBA を雇うまでは、データベースエンジンは 1 つにしましょう。データベースが 2 つあれば、問題も 2 つになります。

プロジェクト構成

まずスタックを特定しましょう。 構成を提案する前に、package.json、go.mod、Gemfile、pyproject.toml、pom.xml、または Cargo.toml を確認してください。以下の原則を、プロジェクトで使用しているスタックに適用します。

すべてのスタックに適用する共通ルール：

• 機能に関するコードはまとめて配置します。1 つの機能を 8 つのディレクトリに分散させないでください。
• サービスにビジネスロジックを記述します。ルートは薄く保ち、検証、サービスの呼び出し、レスポンスの返却を行います。
• 1 つの関数につき 1 つのファイルではなく、ドメインごとに 1 つのサービスを設けます。

例：TypeScript / Next.js

src/
├── app/                    # Next.js app router — pages and layouts
│   ├── (auth)/             # Route groups for auth pages
│   ├── (dashboard)/        # Route groups for app pages
│   └── api/                # API routes
├── lib/                    # Shared utilities, config, constants
│   ├── db/                 # Database client, schema, migrations
│   ├── auth/               # Auth config and helpers
│   └── utils/              # Pure utility functions
├── services/               # Business logic — one file per domain
├── components/             # React components
│   ├── ui/                 # Primitives (button, input, card)
│   └── features/           # Feature-specific composites
└── types/                  # Shared TypeScript types

例：Python / FastAPI

src/
├── api/
│   ├── v1/                 # Versioned endpoints
│   └── deps.py             # Shared dependencies (auth, db session)
├── core/                   # Config, security, constants
├── models/                 # ORM models
├── schemas/                # Request/response schemas
├── services/               # Business logic — one file per domain
├── repositories/           # Data access layer
└── tests/
    ├── unit/
    └── integration/

例：Go

cmd/
├── api/                    # Application entrypoint
internal/
├── handler/                # HTTP handlers (thin — validate + call service)
├── service/                # Business logic
├── repository/             # DB access layer
├── model/                  # Domain types
└── config/                 # Config loading
pkg/                        # Shared, importable packages

例：Ruby on Rails

app/
├── controllers/            # Thin — params, call service, render
├── models/                 # ActiveRecord + domain logic
├── services/               # Complex business logic extracted from models
├── views/                  # Templates or JSON serializers
└── jobs/                   # Background jobs (Sidekiq)
config/
db/
├── migrate/                # Migrations
└── schema.rb

その他のスタック（Java/Spring、.NET、Rust、Elixir）でも、同じ原則を適用してください。ルートは薄く保ち、ビジネスロジックにはサービスを、データアクセスにはリポジトリを使い、テスト対象のコードとテストを同じ場所に配置します。

API 設計

判断事項	基本設定
プロトコル	CRUD には REST、型安全なフルスタック開発には tRPC、複数のクライアントで異なるデータ形式が必要な場合に限り GraphQL
バージョン管理	URL パス：/api/v1/ — シンプルで明確
認証	Authorization ヘッダー内のベアラートークン
ページネーション	フィードにはカーソル方式、管理用テーブルにはオフセット方式
エラー	{ error: { code: "NOT_FOUND", message: "User not found" } }
レート制限	デフォルトは 100 req/min、認証エンドポイントではより低く設定

キャッシュ戦略

レイヤー	ツール	TTL	使用する場面
ブラウザー	Cache-Control ヘッダー	変動	静的アセット、API レスポンス
CDN	Cloudflare / Vercel Edge	1～60 分	公開ページ、画像
アプリケーション	Redis / インメモリー	5～60 分	コストの高いクエリ、セッションデータ
データベース	マテリアライズドビュー	書き込み時に更新	集計、ダッシュボード

ルール：

• 書き込みではなく、読み取りをキャッシュします。変更時に無効化します。
• まずはキャッシュなしで始めます。ボトルネックを測定してから、キャッシュを追加します。
• すべてのキャッシュには無効化戦略が必要です。「TTL を設定して期待する」方法は、通用しなくなるまでは機能します。

スケーリングのチェックリスト

問題に直面したときだけ最適化します。

ユーザー数	想定されるボトルネック	対処法
0～1K	なし	最適化しない
1K～10K	データベースクエリ	インデックスを追加し、N+1 問題を最適化する
10K～100K	データベース接続	コネクションプーリング（PgBouncer）
100K～1M	読み取りスループット	Redis のキャッシュレイヤーを追加する
1M 以上	書き込みスループット	リードレプリカ、シャーディング、書き込みキュー

最適なアーキテクチャは、現在の規模の 10 倍に対応できる最もシンプルなものです。