# アーキテクチャ設計書

## 概要

本ドキュメントはInvenTreeプロジェクトのアーキテクチャ設計書です。InvenTreeはオープンソースの在庫管理システムであり、Python/Djangoバックエンドと、React/TypeScriptフロントエンドから構成されるモダンなWebアプリケーションです。REST APIを通じて外部アプリケーションとの連携が可能であり、プラグインシステムにより機能拡張も実現しています。

## システム全体構成

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

システム全体のアーキテクチャ構成図は別途 [アーキテクチャ構成図.md](./アーキテクチャ構成図.md) を参照してください。

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

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| PostgreSQL / MySQL / SQLite | Django ORM | メインデータベース |
| Redis | django-redis | キャッシュ、バックグラウンドワーカーブローカー |
| SMTP / Anymail ESP | Email Backend | メール送信（通知、パスワードリセット等） |
| OAuth2/OIDC Provider | django-allauth | SSO認証（Google, GitHub等） |
| LDAP Server | django-auth-ldap | LDAP認証 |
| Sentry | sentry-sdk | エラートラッキング・監視 |
| OpenTelemetry Collector | opentelemetry-sdk | トレーシング・メトリクス |
| S3互換ストレージ / SFTP | django-storages | メディアファイル保存 |
| InvenTree Mobile App | REST API | モバイルアクセス |
| 外部プラグイン | Plugin System | カスタム機能拡張 |

## レイヤー構成

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

InvenTreeは **レイヤードアーキテクチャ** を採用しており、Django MVT（Model-View-Template）パターンをベースとしています。ただし、フロントエンドはSPA（Single Page Application）として分離されており、バックエンドはヘッドレスAPIサーバーとして機能します。

主な特徴：
- バックエンド: Django + Django REST Framework によるAPI中心設計
- フロントエンド: React + TypeScript による独立したSPA
- プラグインシステム: Mixin Pattern による拡張可能な設計
- 非同期処理: Django-Q によるバックグラウンドタスク処理

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Presentation (Frontend) | UI表示、ユーザーインタラクション | React コンポーネント、Mantine UI、Zustand状態管理 |
| API Gateway | リクエストルーティング、認証・認可 | Django URL Dispatcher、DRF ViewSet、Middleware |
| Application Service | ビジネスロジック、API実装 | Django Views、DRF Serializers、API endpoints |
| Domain | ドメインモデル、ビジネスルール | Django Models、Validators、Business Logic |
| Infrastructure | 外部サービス連携、データ永続化 | Django ORM、Cache、Plugin Registry |

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

```
Frontend (React SPA)
    ↓ HTTP/REST API
API Gateway (Django Middleware)
    ↓
Application Service (DRF Views/Serializers)
    ↓
Domain (Django Models)
    ↓
Infrastructure (ORM, Cache, External Services)
```

**許可される参照：**
- 上位レイヤーから下位レイヤーへの参照
- 同一レイヤー内のモジュール間参照
- プラグインからコアモジュールへの参照

**禁止される参照：**
- 下位レイヤーから上位レイヤーへの直接参照
- フロントエンドからバックエンド内部実装への直接アクセス（API経由のみ）

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| Part | 部品・製品マスタ管理 | `part/` - 部品定義、カテゴリ、パラメータ、BOM |
| Stock | 在庫管理 | `stock/` - 在庫アイテム、ロケーション、追跡 |
| Order | 注文管理 | `order/` - 発注、販売、返品注文 |
| Build | 製造管理 | `build/` - 製造オーダー、作業指示 |
| Company | 取引先管理 | `company/` - サプライヤー、顧客、メーカー |
| Report | 帳票・レポート | `report/` - ラベル印刷、レポート生成 |
| Users | ユーザー・認証 | `users/` - ユーザー管理、認証、権限 |
| Plugin | プラグイン管理 | `plugin/` - 拡張機能、カスタムプラグイン |
| Common | 共通機能 | `common/` - 設定、通知、共有モデル |
| Machine | マシン連携 | `machine/` - 外部機器連携 |
| Importer | データインポート | `importer/` - CSV/Excel インポート |

### パッケージ構造

```
src/
├── backend/
│   ├── InvenTree/                    # Djangoプロジェクトルート
│   │   ├── InvenTree/                # コアアプリケーション
│   │   │   ├── settings.py           # Django設定
│   │   │   ├── urls.py               # URLルーティング
│   │   │   ├── api.py                # コアAPI
│   │   │   ├── models.py             # 基底モデル
│   │   │   ├── serializers.py        # 基底シリアライザー
│   │   │   ├── middleware.py         # カスタムミドルウェア
│   │   │   ├── permissions.py        # 権限管理
│   │   │   └── tasks.py              # バックグラウンドタスク
│   │   ├── part/                     # 部品管理アプリ
│   │   ├── stock/                    # 在庫管理アプリ
│   │   ├── order/                    # 注文管理アプリ
│   │   ├── build/                    # 製造管理アプリ
│   │   ├── company/                  # 取引先管理アプリ
│   │   ├── report/                   # レポート管理アプリ
│   │   ├── users/                    # ユーザー管理アプリ
│   │   ├── plugin/                   # プラグインシステム
│   │   │   ├── base/                 # プラグイン基底クラス
│   │   │   ├── builtin/              # ビルトインプラグイン
│   │   │   ├── samples/              # サンプルプラグイン
│   │   │   └── registry.py           # プラグインレジストリ
│   │   ├── common/                   # 共通機能アプリ
│   │   ├── machine/                  # マシン連携アプリ
│   │   ├── importer/                 # インポート機能アプリ
│   │   └── templates/                # HTMLテンプレート
│   └── requirements.txt              # Python依存関係
│
├── frontend/
│   ├── src/
│   │   ├── components/               # Reactコンポーネント
│   │   ├── pages/                    # ページコンポーネント
│   │   │   ├── Auth/                 # 認証ページ
│   │   │   ├── part/                 # 部品関連ページ
│   │   │   ├── stock/                # 在庫関連ページ
│   │   │   ├── build/                # 製造関連ページ
│   │   │   ├── purchasing/           # 購買関連ページ
│   │   │   └── sales/                # 販売関連ページ
│   │   ├── tables/                   # テーブルコンポーネント
│   │   ├── forms/                    # フォームコンポーネント
│   │   ├── hooks/                    # カスタムReactフック
│   │   ├── states/                   # Zustand状態管理
│   │   ├── contexts/                 # Reactコンテキスト
│   │   ├── functions/                # ユーティリティ関数
│   │   ├── locales/                  # 国際化ファイル
│   │   ├── router.tsx                # ルーティング設定
│   │   └── main.tsx                  # アプリケーションエントリ
│   ├── lib/                          # 共有ライブラリ
│   │   ├── types/                    # TypeScript型定義
│   │   ├── enums/                    # 列挙型
│   │   ├── components/               # 共有コンポーネント
│   │   └── functions/                # 共有ユーティリティ
│   └── package.json                  # フロントエンド依存関係
│
└── performance/                      # パフォーマンステスト
```

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

**バックエンドアプリケーション間の依存関係：**
- `part` → `company` (サプライヤー部品、メーカー部品)
- `stock` → `part`, `company` (在庫アイテム、ロケーション)
- `order` → `part`, `stock`, `company` (発注、販売)
- `build` → `part`, `stock` (製造オーダー)
- `report` → `part`, `stock`, `order`, `build` (レポート生成)
- `plugin` → 全アプリケーション (拡張機能)
- `common` ← 全アプリケーション (設定、共通モデル)

**フロントエンド依存関係：**
- `pages/` → `components/`, `tables/`, `forms/`
- `components/` → `hooks/`, `states/`, `functions/`
- `states/` → `lib/types/`, `lib/enums/`

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| RDB | PostgreSQL | 最新安定版推奨 | 本番環境向け主データベース |
| RDB | MySQL | 最新安定版 | 代替RDBオプション |
| RDB | SQLite | 3.x | 開発・小規模環境向け |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| Redis | 6.x以上 | セッション、APIキャッシュ、タスクブローカー | 設定により可変 |
| LocMem | Django内蔵 | 開発環境向けインメモリキャッシュ | リクエスト単位 |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Django-Q | 最新 | バックグラウンドタスク、スケジュールタスク |
| Redis | 6.x以上 | タスクキューブローカー（本番環境） |
| ORM | Django内蔵 | タスクキューブローカー（開発環境） |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Django ORM Filter | 内蔵 | テキスト検索、フィルタリング |
| PostgreSQL Full-text | 内蔵 | 全文検索（PostgreSQL使用時） |

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

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Gunicorn | 最新 | WSGI HTTPサーバー |
| WhiteNoise | 最新 | 静的ファイル配信 |
| django-cors-headers | 最新 | CORS対応 |
| django-allauth | 最新 | 認証・SSO |
| django-rest-framework | 最新 | REST API |
| django-filter | 最新 | APIフィルタリング |

## データフロー

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

同期リクエスト（API呼び出し）の処理フロー：

1. **クライアント** がHTTPリクエスト送信（React SPA / Mobile App / 外部システム）
2. **Gunicorn** がリクエストを受信、WSGIアプリケーションに転送
3. **Django Middleware Chain** が順次処理
   - `SecurityMiddleware`: セキュリティヘッダー設定
   - `SessionMiddleware`: セッション管理
   - `CorsMiddleware`: CORS処理
   - `AuthenticationMiddleware`: 認証処理
   - `AuthRequiredMiddleware`: 認証要求チェック
   - `Check2FAMiddleware`: MFA強制チェック
4. **URL Dispatcher** がURLパターンマッチング
5. **DRF View/ViewSet** がリクエスト処理
   - `get_queryset()`: データ取得
   - `get_serializer()`: シリアライズ/デシリアライズ
   - Permission/Throttle チェック
6. **Django Model** がORMを通じてデータベースアクセス
7. **Response** がクライアントに返却

### 非同期処理の流れ

非同期処理（バックグラウンドタスク）のフロー：

1. **トリガー**：スケジュール実行 / APIリクエスト / イベント発火
2. **Django-Q Scheduler** がタスクをキューに登録
3. **Redis / ORM Broker** がタスクをキューで管理
4. **Django-Q Worker** がタスクを取得・実行
   - タスク例：在庫更新通知、レポート生成、メール送信
5. **実行結果** がデータベースに記録
6. **リトライ処理**：失敗時は設定回数まで再試行

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

1. **フォーム/APIリクエスト** でデータ受信
2. **DRF Serializer** がバリデーション実行
   - フィールドバリデーション
   - カスタムバリデーション（`validate_*`メソッド）
3. **Django Model** でモデルレベルバリデーション
   - `clean()` メソッド
   - `save()` 前処理
4. **Django ORM** がSQLクエリ生成・実行
5. **データベース** にコミット
6. **シグナル** による後処理（`post_save`等）
7. **キャッシュ** 無効化/更新

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| セッション認証 | `django.contrib.auth` | Webブラウザ |
| トークン認証 | `users.authentication.ApiTokenAuthentication` | API/外部アプリ |
| OAuth2 | `oauth2_provider` | OAuth2クライアント |
| BasicAuth | `rest_framework.authentication.BasicAuthentication` | 開発/テスト |
| SSO (OIDC) | `allauth.socialaccount` | 外部IdP連携 |
| LDAP | `django_auth_ldap` | 企業ディレクトリ連携 |
| MFA/2FA | `allauth.mfa`, `django_otp` | 多要素認証 |
| リモート認証 | `InvenTreeRemoteUserMiddleware` | プロキシ認証 |

**権限モデル：**
- Django標準のModel Permission（add, change, delete, view）
- カスタムRolePermission（`InvenTree.permissions.RolePermission`）
- オブジェクトレベル権限（ModelPermission）

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | structlog | コンソール / ファイル / JSON |
| 監査ログ | Django Admin History | データベース |
| アクセスログ | Gunicorn / Nginx | ファイル |
| エラーログ | error_report / Sentry | データベース / Sentry |
| トレーシング | OpenTelemetry | OpenTelemetry Collector |
| バーコードスキャンログ | `BarcodeScanResult` | データベース |

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

エラーハンドリングの方針と実装箇所：

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| バリデーションエラー | DRF Serializer Validation | 400 Bad Request (JSON) |
| 認証エラー | AuthenticationMiddleware | 401 Unauthorized |
| 権限エラー | PermissionDenied | 403 Forbidden |
| リソース未発見 | Http404 | 404 Not Found |
| サーバーエラー | `InvenTreeExceptionProcessor` | 500 Internal Server Error |
| メンテナンスモード | `MaintenanceModeMiddleware` | 503 Service Unavailable |

**エラー処理の流れ：**
1. 例外発生
2. `InvenTree.exceptions.exception_handler` がDRFレベルでキャッチ
3. `InvenTreeExceptionProcessor` がミドルウェアレベルでキャッチ
4. `error_report` / Sentry に記録
5. 適切なHTTPレスポンスを返却

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

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| API View | `ATOMIC_REQUESTS`（デフォルト無効） | DB設定依存 |
| Model Save | 自動トランザクション | DB設定依存 |
| バッチ処理 | `transaction.atomic()` 明示指定 | READ_COMMITTED |
| PostgreSQL | psycopg設定 | READ_COMMITTED / SERIALIZABLE（設定可能） |
| MySQL | MySQLクライアント設定 | REPEATABLE_READ / SERIALIZABLE（設定可能） |

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

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

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| DRY (Don't Repeat Yourself) | 基底クラス、Mixin | `InvenTreeModelSerializer`, `DataImportMixin` |
| SOLID - Single Responsibility | アプリケーション分割 | 各Djangoアプリ（part, stock, order等） |
| SOLID - Open/Closed | プラグインシステム | `plugin.base` Mixinによる拡張 |
| SOLID - Dependency Inversion | 設定の外部化 | `config.yaml`, 環境変数 |
| Separation of Concerns | フロントエンド/バックエンド分離 | React SPA + Django API |
| Convention over Configuration | Django設定 | 規約ベースのURL、モデル命名 |

### コーディング規約

**Python (Backend):**
- PEP 8準拠（Ruff/Flake8でリント）
- Google Style Docstring
- 型ヒント使用推奨
- import順序: 標準ライブラリ → Django → サードパーティ → ローカル

**TypeScript/React (Frontend):**
- Biome によるフォーマット・リント
- 関数コンポーネント + Hooks パターン
- Mantine UIコンポーネントライブラリ使用
- Zustand による状態管理
- TanStack Query によるサーバー状態管理

## 備考

### 開発・デプロイメント

- **コンテナ化**: Docker / Docker Compose サポート
- **CI/CD**: GitHub Actions による自動テスト・ビルド
- **テスト**: pytest (Backend), Playwright (E2E)
- **ドキュメント**: ReadTheDocs によるドキュメントホスティング
- **国際化**: Crowdin による翻訳管理（35言語以上対応）

### プラグインシステム

InvenTreeは強力なプラグインシステムを提供し、以下のMixinによる拡張が可能：
- `BarcodeMixin`: バーコードスキャン機能
- `ReportMixin`: レポート・ラベル生成
- `ScheduleMixin`: スケジュールタスク
- `EventMixin`: イベントハンドリング
- `UrlsMixin`: カスタムURLエンドポイント
- `NavigationMixin`: ナビゲーション拡張
- `AppMixin`: アプリケーション拡張
- `SettingsMixin`: カスタム設定

### セキュリティ考慮事項

- CSRF保護（Django標準）
- XSS対策（テンプレートエスケープ、DOMPurify）
- SQLインジェクション対策（ORM使用）
- セッション管理（Secure Cookie設定可能）
- MFA/2FA強制オプション
- API レート制限（allauth rate limits）
- Sentry/OpenSSF セキュリティスコアカード対応
