designing-architecture

アーキテクチャの設計

読み込むタイミング

• トリガー：システム設計、モジュール構成、新規プロジェクトのひな形作成、アーキテクチャパターンの選定
• スキップ：アーキテクチャに影響しない、単純なバグ修正や小規模なコード変更

アーキテクチャ決定のワークフロー

このチェックリストをコピーして、進捗を記録します。

Architecture Design Progress:
- [ ] Step 1: Understand requirements and constraints
- [ ] Step 2: Assess project size and team capabilities
- [ ] Step 3: Select architecture pattern
- [ ] Step 4: Define directory structure
- [ ] Step 5: Document trade-offs and decision
- [ ] Step 6: Validate against decision framework

パターン選択ガイド

プロジェクト規模別

規模	推奨パターン
小規模（<10K LOC）	シンプルな MVC／レイヤード
中規模（10K-100K）	クリーンアーキテクチャ
大規模（>100K）	モジュラーモノリスまたはマイクロサービス

チーム規模別

チーム	推奨パターン
開発者 1～3 人	明確なモジュールを持つモノリス
開発者 4～10 人	モジュラーモノリス
開発者 10 人以上	マイクロサービス（正当な理由がある場合）

一般的なパターン

1. レイヤードアーキテクチャ

┌─────────────────────────────┐
│       Presentation          │  ← UI, API Controllers
├─────────────────────────────┤
│       Application           │  ← Use Cases, Services
├─────────────────────────────┤
│         Domain              │  ← Business Logic, Entities
├─────────────────────────────┤
│      Infrastructure         │  ← Database, External APIs
└─────────────────────────────┘

使用する場面：シンプルな CRUD アプリ、小規模チーム、迅速なプロトタイプ

2. クリーンアーキテクチャ

┌─────────────────────────────────────┐
│            Frameworks & Drivers      │
│  ┌─────────────────────────────┐    │
│  │     Interface Adapters       │    │
│  │  ┌─────────────────────┐    │    │
│  │  │   Application       │    │    │
│  │  │  ┌─────────────┐    │    │    │
│  │  │  │   Domain    │    │    │    │
│  │  │  └─────────────┘    │    │    │
│  │  └─────────────────────┘    │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

使用する場面：複雑なビジネスロジック、長期運用するプロジェクト、テスト容易性が重要な場合

3. ヘキサゴナル（ポートとアダプター）

        ┌──────────┐
        │ HTTP API │
        └────┬─────┘
             │ Port
    ┌────────▼────────┐
    │                 │
    │   Application   │
    │     Core        │
    │                 │
    └────────┬────────┘
             │ Port
        ┌────▼─────┐
        │ Database │
        └──────────┘

使用する場面：外部依存関係の差し替えが必要な場合、複数のエントリーポイントがある場合

4. イベント駆動アーキテクチャ

Producer → Event Bus → Consumer
              │
              ├─→ Consumer
              │
              └─→ Consumer

使用する場面：疎結合が必要な場合、非同期処理、スケーラビリティ

5. CQRS（コマンドクエリ責務分離）

┌─────────────┐      ┌─────────────┐
│  Commands   │      │   Queries   │
│  (Write)    │      │   (Read)    │
└──────┬──────┘      └──────┬──────┘
       │                    │
       ▼                    ▼
  Write Model          Read Model
       │                    │
       └────────┬───────────┘
                ▼
           Event Store

使用する場面：読み取りと書き込みで異なるスケーリングが必要な場合、複雑なドメイン、イベントソーシング

ディレクトリ構造のパターン

機能ベース（中規模以上に推奨）

src/
├── features/
│   ├── users/
│   │   ├── api/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types/
│   └── orders/
│       ├── api/
│       ├── components/
│       └── ...
├── shared/
│   ├── components/
│   ├── hooks/
│   └── utils/
└── app/
    └── ...

レイヤーベース（シンプルなアプリ）

src/
├── controllers/
├── services/
├── models/
├── repositories/
└── utils/

判断のフレームワーク

アーキテクチャを決定する際は、次の基準に照らして評価します。

1. シンプルさ - まずはシンプルに始め、必要に応じて発展させます
2. チームのスキル - チームの能力に合ったアーキテクチャを選びます
3. 要件 - ビジネスニーズに基づいて決定します
4. スケーラビリティ - 成長の見通しを考慮します
5. 保守性 - 変更しやすさを優先します

トレードオフ分析テンプレート

このテンプレートを使って、アーキテクチャ上の決定を記録します。

## Decision: [What we're deciding]

### Context

[Why this decision is needed now]

### Options Considered

1. Option A: [Description]
2. Option B: [Description]

### Trade-offs

| Criteria         | Option A | Option B |
| ---------------- | -------- | -------- |
| Complexity       | Low      | High     |
| Scalability      | Medium   | High     |
| Team familiarity | High     | Low      |

### Decision

We chose [Option] because [reasoning].

### Consequences

- [What this enables]
- [What this constrains]

検証チェックリスト

アーキテクチャを選択した後、次の項目に照らして検証します。

Architecture Validation:
- [ ] Matches project size and complexity
- [ ] Aligns with team skills and experience
- [ ] Supports current requirements
- [ ] Allows for anticipated growth
- [ ] Dependencies flow inward (core has no external deps)
- [ ] Clear boundaries between modules/layers
- [ ] Testing strategy is feasible
- [ ] Trade-offs are documented

検証に失敗した場合は、パターンの選択を再検討するか、実装方針を調整します。