# アーキテクチャ設計書

## 概要

本ドキュメントは、Laravel Framework 12.x（illuminate/framework）のアーキテクチャ設計を記述したものである。Laravel Frameworkは、PHPで構築されたフルスタックWebアプリケーションフレームワークであり、MVCアーキテクチャパターンをベースに、サービスコンテナを中心とした依存性注入（DI）、サービスプロバイダによるモジュール化、Facadeパターンによる簡潔なAPIアクセスを特徴とする。

## システム全体構成

### アーキテクチャ概要図

システム全体のアーキテクチャ構成図は [アーキテクチャ構成図.md](./アーキテクチャ構成図.md) を参照。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| RDB（MySQL/PostgreSQL/SQLite/SQL Server/MariaDB） | PDO | データ永続化、Eloquent ORM |
| Redis | phpredis / Predis | キャッシュ、セッション、キュー、リアルタイム通信 |
| Memcached | PECL memcached | キャッシュストア |
| Amazon SQS | AWS SDK | 分散キュー処理 |
| Amazon DynamoDB | AWS SDK | キャッシュ、セッション、キュー |
| Beanstalkd | Pheanstalk | キュー処理 |
| SMTP / Mailgun / Postmark / SES / Resend | Symfony Mailer | メール送信 |
| Pusher / Ably | WebSocket | リアルタイムブロードキャスト |
| Amazon S3 / FTP / SFTP | Flysystem | ファイルストレージ |

## レイヤー構成

### アーキテクチャスタイル

Laravel Frameworkは **サービスコンテナ中心のモジュラーアーキテクチャ** を採用している。主要な設計パターンとして以下を組み合わせている：

- **サービスコンテナ（IoC Container）**: 依存性注入とライフサイクル管理の中核
- **サービスプロバイダパターン**: モジュールの登録・初期化メカニズム
- **Facadeパターン**: 静的APIを通じたサービスコンテナへのアクセス
- **MVCパターン**: Webアプリケーションの構造化（Model-View-Controller）
- **リポジトリパターン**: Eloquent ORMによるデータアクセス抽象化
- **パイプラインパターン**: HTTPミドルウェアとリクエスト処理

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Foundation | アプリケーションのブートストラップ、コンテナ管理、カーネル | `Application`, `Kernel`, `Bootstrap/*` |
| Http | HTTPリクエスト/レスポンス処理、ミドルウェア | `Request`, `Response`, `Middleware/*`, `FormRequest` |
| Routing | URL解決、コントローラーディスパッチ | `Router`, `Route`, `RouteCollection`, `UrlGenerator` |
| Auth | 認証・認可機構 | `AuthManager`, `Guard`, `Gate`, `Middleware/*` |
| Database | データベース接続、クエリビルダ、マイグレーション | `DatabaseManager`, `Connection`, `Query\Builder` |
| Eloquent | ORM、モデル、リレーション | `Model`, `Builder`, `Relations/*`, `Casts/*` |
| Queue | 非同期ジョブ処理、ワーカー | `Queue`, `Job`, `Worker`, `Dispatcher` |
| Cache | キャッシュ抽象化、ストアドライバ | `CacheManager`, `Repository`, `Store/*` |
| Events | イベント駆動アーキテクチャ | `Dispatcher`, `Listener`, `Subscriber` |
| Mail | メール送信抽象化 | `Mailer`, `Mailable`, `Transport/*` |
| Notifications | 通知システム（マルチチャネル） | `NotificationSender`, `Notification`, `Channel/*` |
| Console | CLIコマンド、Artisan | `Kernel`, `Command`, `Application` |
| View | テンプレートエンジン、Blade | `Factory`, `View`, `BladeCompiler` |
| Validation | 入力バリデーション | `Validator`, `Factory`, `Rule/*` |
| Session | セッション管理 | `SessionManager`, `Store`, `Handler/*` |
| Filesystem | ファイルシステム抽象化 | `FilesystemManager`, `Filesystem`, `Adapter/*` |
| Support | ユーティリティ、ヘルパー、コレクション | `Collection`, `Str`, `Arr`, `ServiceProvider` |
| Container | サービスコンテナ、DI | `Container`, `BoundMethod`, `ContextualBindingBuilder` |
| Contracts | インターフェース定義（契約） | 全コンポーネントのインターフェース群 |

### レイヤー間の依存関係ルール

**依存の方向性**:
- すべてのコンポーネントは `Contracts`（インターフェース）に依存することが推奨される
- 上位レイヤー（Foundation, Http）は下位レイヤー（Container, Support）に依存
- 具象実装は `Contracts` のインターフェースを実装する

**許可される参照**:
- `Foundation` → すべてのIlluminateコンポーネント
- 各コンポーネント → `Container`, `Support`, `Contracts`
- `Eloquent` → `Database`
- `Http` → `Routing`, `Session`, `Cookie`

**禁止される参照**:
- `Container` → 他のIlluminateコンポーネント（`Contracts`を除く）
- `Contracts` → 具象実装クラス
- `Support` → アプリケーション固有のコンポーネント

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| Core | フレームワークの中核機能 | `Container`, `Foundation`, `Support`, `Contracts` |
| Web | Webアプリケーション処理 | `Http`, `Routing`, `View`, `Session`, `Cookie` |
| Data | データアクセス・永続化 | `Database`, `Eloquent`, `Redis`, `Cache` |
| Auth | セキュリティ・認証認可 | `Auth`, `Hashing`, `Encryption` |
| Async | 非同期・バックグラウンド処理 | `Queue`, `Bus`, `Events`, `Broadcasting` |
| Communication | 外部通信・通知 | `Mail`, `Notifications`, `Http\Client` |
| CLI | コマンドライン機能 | `Console`, `Process` |
| Testing | テスト支援 | `Testing` |

### パッケージ構造

```
src/
└── Illuminate/
    ├── Auth/                    # 認証・認可
    ├── Broadcasting/            # リアルタイムイベント配信
    ├── Bus/                     # コマンドバス
    ├── Cache/                   # キャッシュ抽象化
    ├── Collections/             # コレクションクラス
    ├── Concurrency/             # 並行処理
    ├── Conditionable/           # 条件付きメソッドチェーン
    ├── Config/                  # 設定管理
    ├── Console/                 # CLIコマンド（Artisan）
    ├── Container/               # サービスコンテナ（IoC）
    ├── Contracts/               # インターフェース定義
    ├── Cookie/                  # Cookie管理
    ├── Database/                # データベース抽象化
    │   ├── Eloquent/           # ORM
    │   ├── Query/              # クエリビルダ
    │   ├── Schema/             # スキーマビルダ
    │   └── Migrations/         # マイグレーション
    ├── Encryption/              # 暗号化
    ├── Events/                  # イベントシステム
    ├── Filesystem/              # ファイルシステム
    ├── Foundation/              # アプリケーション基盤
    │   ├── Bootstrap/          # ブートストラップ処理
    │   ├── Console/            # Artisanコマンド
    │   ├── Http/               # HTTPカーネル・ミドルウェア
    │   └── Providers/          # コアサービスプロバイダ
    ├── Hashing/                 # ハッシュ化
    ├── Http/                    # HTTPリクエスト/レスポンス
    │   ├── Client/             # HTTPクライアント
    │   └── Middleware/         # HTTPミドルウェア
    ├── JsonSchema/              # JSONスキーマ検証
    ├── Log/                     # ロギング
    ├── Macroable/               # マクロ機能
    ├── Mail/                    # メール送信
    ├── Notifications/           # 通知システム
    ├── Pagination/              # ページネーション
    ├── Pipeline/                # パイプライン処理
    ├── Process/                 # プロセス管理
    ├── Queue/                   # キュー・ジョブ
    ├── Redis/                   # Redis接続
    ├── Reflection/              # リフレクションユーティリティ
    ├── Routing/                 # ルーティング
    │   └── Middleware/         # ルートミドルウェア
    ├── Session/                 # セッション管理
    ├── Support/                 # ユーティリティ・ヘルパー
    │   └── Facades/            # Facadeクラス群
    ├── Testing/                 # テスト支援
    ├── Translation/             # 多言語対応
    ├── Validation/              # バリデーション
    └── View/                    # ビュー・Bladeテンプレート
```

### コンポーネント依存関係

**サービスコンテナ（Container）を中心とした依存関係**:

- `Application`（Foundation）は `Container` を継承し、フレームワーク全体のサービスを管理
- 各コンポーネントは `ServiceProvider` を通じてコンテナに登録される
- `Facade` はコンテナからサービスを解決する静的プロキシを提供

**主要な依存チェーン**:

1. `Http\Kernel` → `Router` → `Controller` → `Model` → `Database\Connection`
2. `Queue\Worker` → `Job` → `Bus\Dispatcher` → `Events\Dispatcher`
3. `Mail\Mailer` → `Transport` → `Symfony\Mailer`
4. `Cache\Repository` → `Store` → `Connection`（Redis/Database/File）

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| RDB | MySQL | 5.7+ / 8.0+ | メインデータストア |
| RDB | PostgreSQL | 12.0+ | メインデータストア |
| RDB | SQLite | 3.35.0+ | 軽量データストア、テスト用 |
| RDB | SQL Server | 2017+ | エンタープライズデータストア |
| RDB | MariaDB | 10.3+ | MySQL互換データストア |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| Redis | 6.0+ | アプリケーションキャッシュ、セッション | 設定可能 |
| Memcached | 1.6+ | 分散キャッシュ | 設定可能 |
| Database | - | 永続キャッシュ | 設定可能 |
| File | - | ローカルキャッシュ | 設定可能 |
| DynamoDB | - | AWSスケーラブルキャッシュ | 設定可能 |
| Octane | - | メモリ内キャッシュ（Swoole/RoadRunner） | リクエストライフサイクル |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Redis | 6.0+ | 高速キュー、リアルタイム処理 |
| Database | - | シンプルなキュー、永続化 |
| Amazon SQS | - | AWSマネージドキュー、スケーラブル |
| Beanstalkd | 1.12+ | 軽量キューサーバー |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Laravel Scout | - | フルテキスト検索抽象化（別パッケージ） |

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Monolog | 3.0+ | ロギングライブラリ |
| Symfony Components | 7.2+ | HTTP Foundation, Console, Mailer等 |
| Flysystem | 3.25+ | ファイルシステム抽象化 |
| Carbon | 3.8+ | 日時処理 |
| Guzzle | 7.8+ | HTTPクライアント |

## データフロー

### リクエスト処理の流れ

HTTPリクエストの処理は、パイプラインパターンを使用したミドルウェアスタックを通じて行われる。

1. **エントリーポイント** (`public/index.php`)
   - Composerオートローダーの読み込み
   - `Application` インスタンスの作成

2. **ブートストラップ処理** (`Kernel::bootstrap()`)
   - 環境変数の読み込み (`LoadEnvironmentVariables`)
   - 設定ファイルの読み込み (`LoadConfiguration`)
   - 例外ハンドラの設定 (`HandleExceptions`)
   - Facadeの登録 (`RegisterFacades`)
   - サービスプロバイダの登録 (`RegisterProviders`)
   - サービスプロバイダのブート (`BootProviders`)

3. **リクエスト処理** (`Kernel::handle()`)
   - `Request` オブジェクトの生成
   - グローバルミドルウェアの実行
   - ルートマッチング (`Router::findRoute()`)
   - ルートミドルウェアの実行
   - コントローラーメソッドの実行
   - `Response` オブジェクトの生成

4. **レスポンス送信** (`Response::send()`)
   - HTTPヘッダーの送信
   - レスポンスボディの出力

5. **終了処理** (`Kernel::terminate()`)
   - Terminatingコールバックの実行
   - セッションの保存
   - 遅延コールバックの実行

### 非同期処理の流れ

キューを使用した非同期ジョブ処理のフロー：

1. **ジョブのディスパッチ**
   - `dispatch()` または `Bus::dispatch()` でジョブをキューに追加
   - `Queue\Connector` がキューストアに書き込み

2. **ワーカーによる処理** (`queue:work`)
   - `Worker::daemon()` がキューを監視
   - ジョブの取得とデシリアライズ
   - `Job::fire()` によるジョブ実行

3. **完了・失敗処理**
   - 成功時：ジョブの削除
   - 失敗時：リトライまたは失敗テーブルへの記録

### データ永続化の流れ

Eloquent ORMを通じたデータアクセス：

1. **モデル操作**
   - `Model::find()`, `Model::create()`, `Model::update()` 等のメソッド呼び出し

2. **クエリビルダ変換**
   - `Eloquent\Builder` が `Query\Builder` に変換
   - SQL文の生成

3. **接続・実行**
   - `DatabaseManager` から適切な `Connection` を取得
   - PDOを通じてクエリ実行
   - トランザクション管理

4. **結果のハイドレーション**
   - 結果セットから `Model` インスタンスへの変換
   - リレーションの遅延読み込み（Lazy Loading）
   - キャストの適用

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| Session認証 | `Auth\SessionGuard` | Webアプリケーション |
| Token認証 | `Auth\TokenGuard` | API |
| Gate/Policy | `Auth\Access\Gate` | 認可ロジック |
| Remember Me | `Auth\Recaller` | 永続ログイン |
| Password Reset | `Auth\Passwords\*` | パスワードリセット |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | Monolog（PSR-3準拠） | ファイル / Slack / Syslog / Papertrail |
| クエリログ | `Database\Events\QueryExecuted` | メモリ / ファイル |
| スロークエリログ | `Connection::logQuery()` | 設定可能 |
| 例外ログ | `Foundation\Exceptions\Handler` | ファイル / 外部サービス |

### エラーハンドリング

フレームワーク全体のエラーハンドリングは `Contracts\Debug\ExceptionHandler` を実装した `Foundation\Exceptions\Handler` が担当する。

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| HttpException | `render()` メソッド | 適切なHTTPステータスコード |
| ModelNotFoundException | 404変換 | 404 Not Found |
| ValidationException | `render()` メソッド | 422 Unprocessable Entity |
| AuthenticationException | リダイレクト / 401 | ログインページ / 401 Unauthorized |
| AuthorizationException | 403変換 | 403 Forbidden |
| その他の例外 | `report()` + `render()` | 500 Internal Server Error |

### トランザクション管理

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| 単一接続 | `DB::transaction()` | 設定可能（デフォルト: DB依存） |
| ネストトランザクション | Savepoints | 自動管理 |
| コミット後イベント | `afterCommit()` | イベントベース |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 依存性逆転の原則（DIP） | 全コンポーネント | `Contracts` インターフェースへの依存 |
| 単一責任の原則（SRP） | コンポーネント分割 | 各Illuminateパッケージが単一責務 |
| 開放閉鎖の原則（OCP） | サービスプロバイダ | 新機能はプロバイダとして追加 |
| インターフェース分離の原則（ISP） | Contracts | 細かく分割されたインターフェース |
| Liskov置換原則（LSP） | Guard実装 | `SessionGuard`, `TokenGuard` の互換性 |

### コーディング規約

- **PSR-12準拠**: コードスタイルはPSR-12に準拠
- **PHPStan対応**: 静的解析による型安全性の確保
- **Laravel Pint**: コードフォーマッターによる一貫性維持
- **命名規則**:
  - クラス: PascalCase
  - メソッド・変数: camelCase
  - 定数: SCREAMING_SNAKE_CASE
- **ドキュメンテーション**: PHPDoc形式のコメント

## 備考

- 本ドキュメントは Laravel Framework 12.53.0 を基に作成
- フレームワーク本体のアーキテクチャであり、アプリケーション実装のガイドラインは別途参照
- 設定ファイルは `config/` ディレクトリに配置され、環境変数による上書きが可能
- 各コンポーネントは独立したComposerパッケージとしても利用可能（`illuminate/*`）
