技術選定 ADR (Architecture Decision Records)
ADR-001: Frontend フレームワーク - React 19 + Vite
ステータス
承認済み
コンテキスト
管理画面のフロントエンド技術を選定する必要がある。カンバンUI、リアルタイム更新、複雑なダッシュボード表示が求められる。
決定
React 19 + Vite + TypeScript を採用する。
選定理由
- React 19: Server Components、改善されたSuspense、use() hookなど最新機能により開発効率が向上
- Vite: HMRの高速性、ビルド速度の優位性、Cloudflare Pagesとの相性が良い
- TypeScript: 型安全性によるバグ削減、IDE補完による開発効率向上
代替案との比較
| 項目 | React 19 + Vite | Next.js 15 | Vue 3 + Vite | SvelteKit |
|---|---|---|---|---|
| エコシステム | ◎ 最大 | ◎ 最大 | ○ 大 | △ 中 |
| 学習コスト | ○ 低（広く普及） | ○ 低 | ○ 低 | △ やや高 |
| SSR必要性 | 不要（SPA） | 標準搭載（過剰） | 不要 | 標準搭載 |
| CF Pages互換性 | ◎ | △ 追加設定必要 | ◎ | ○ |
| カンバンUI | ◎ ライブラリ豊富 | ◎ | ○ | △ |
| 業務委託エンジニア確保 | ◎ | ◎ | ○ | △ |
トレードオフ
- SSR/SSGが不要な管理画面SPAのため、Next.jsのフルスタック機能は過剰
- React 19は比較的新しいが、後方互換性が高くリスクは限定的
- SPAのため初回ロードがやや遅いが、管理画面用途では許容範囲
ADR-002: Backend フレームワーク - FastAPI
ステータス
承認済み
コンテキスト
REST APIサーバーの技術を選定する必要がある。GitLab API連携、Webhook処理、認証、データベースアクセスが主要な責務。
決定
FastAPI + SQLAlchemy 2.x + Python 3.12+ を採用する。
選定理由
- FastAPI: 自動OpenAPIドキュメント生成、型ヒントによる入出力バリデーション、非同期処理サポート
- SQLAlchemy 2.x: 成熟したORM、非同期対応、マイグレーションツール（Alembic）との統合
- Python: AI/Claude Code との親和性が高く、業務委託エンジニアの開発効率が向上
代替案との比較
| 項目 | FastAPI (Python) | Express/Hono (Node.js) | Go (Echo/Gin) | NestJS (Node.js) |
|---|---|---|---|---|
| API自動ドキュメント | ◎ 標準搭載 | △ 要追加 | △ 要追加 | ○ Swagger連携 |
| 型安全性 | ◎ Pydantic | ○ TypeScript | ◎ 静的型付 | ○ TypeScript |
| 非同期処理 | ◎ async/await | ◎ | ◎ goroutine | ◎ |
| ORM成熟度 | ◎ SQLAlchemy | ○ Prisma/Drizzle | △ GORM | ○ TypeORM |
| AI連携容易性 | ◎ | ○ | △ | ○ |
| 開発速度 | ◎ | ◎ | △ | ○ |
| パフォーマンス | ○ | ○ | ◎ | ○ |
トレードオフ
- Node.js統一（Frontend/Backend同一言語）のメリットを放棄
- PythonのランタイムパフォーマンスはGoに劣るが、管理画面の規模では問題にならない
- FastAPIの非同期処理でI/Oバウンド処理は十分高速
ADR-003: データベース - PostgreSQL
ステータス
承認済み
コンテキスト
プロジェクト、Issue、報酬、ユーザー情報を永続化するデータベースを選定する必要がある。
決定
PostgreSQL 16.x を採用する。
選定理由
- リレーショナルデータモデルが業務ドメイン（プロジェクト→Issue→報酬の関係）に適合
- JSONB型によりGitLab Webhookの生データ保存にも対応
- トランザクション整合性が報酬確定処理に必要
- SQLAlchemyとの相性が最も良い
代替案との比較
| 項目 | PostgreSQL | MySQL | SQLite | MongoDB |
|---|---|---|---|---|
| リレーション | ◎ | ◎ | ◎ | △ |
| JSON対応 | ◎ JSONB | ○ JSON | △ | ◎ ネイティブ |
| トランザクション | ◎ | ◎ | ○ | △ |
| 運用実績 | ◎ | ◎ | △ 小規模 | ○ |
| CF Workers互換 | △ 外部接続 | △ 外部接続 | ◎ D1 | △ |
| 全文検索 | ◎ | ○ | △ | ◎ |
トレードオフ
- Cloudflare D1（SQLite互換）を使えばEdgeでDB運用可能だが、機能制約が大きい
- 外部DB接続のためレイテンシが増えるが、管理画面用途では許容範囲
- MongoDBはスキーマレスの柔軟性があるが、報酬管理に必要な厳密なリレーションが弱い
ADR-004: Frontend Hosting - Cloudflare Pages
ステータス
承認済み
コンテキスト
SPAの静的ファイルをホスティングする環境を選定する必要がある。
決定
Cloudflare Pages を採用する。
選定理由
- 無料枠が充実（帯域無制限、月500ビルド）
- グローバルCDN配信によりレスポンスが高速
- GitLab CI連携でのデプロイが容易（Wrangler CLI）
- Cloudflare Accessによるプライベート公開が可能（社内限定公開）
代替案との比較
| 項目 | Cloudflare Pages | Vercel | Netlify | AWS S3 + CloudFront |
|---|---|---|---|---|
| 無料枠 | ◎ 帯域無制限 | ○ 制限あり | ○ 制限あり | △ 従量課金 |
| CDN性能 | ◎ | ◎ | ◎ | ◎ |
| アクセス制御 | ◎ CF Access | △ 要課金 | △ 要課金 | ○ IAM |
| GitLab CI連携 | ◎ Wrangler | △ GitHub向き | △ GitHub向き | ○ AWS CLI |
| 設定の簡易さ | ◎ | ◎ | ◎ | △ |
トレードオフ
- Cloudflareエコシステムへのロックイン
- Vercel/Netlifyと比較してプレビュー環境の機能がやや劣る
- SPAモードでの動的ルーティング設定が必要（
_redirectsファイル）
ADR-005: Backend Hosting - VPS（Cloudflare Workers併用）
ステータス
承認済み
コンテキスト
FastAPI バックエンドのホスティング環境を選定する必要がある。
決定
- メインAPI: VPS上にデプロイ（Docker Compose）
- Webhook Receiver: Cloudflare Workers（低レイテンシ受信）
選定理由
- FastAPIはPythonランタイムが必要で、Cloudflare Workersのネイティブ実行に非対応
- VPSであればDocker Composeでアプリ+DB+リバースプロキシを一括管理可能
- Webhook受信のみWorkersに配置し、応答速度と信頼性を確保
代替案との比較
| 項目 | VPS + Workers | Cloudflare Workers全面 | AWS Lambda | Railway/Render |
|---|---|---|---|---|
| Python対応 | ◎ | △ Pyodide制約 | ◎ | ◎ |
| DB接続 | ◎ ローカル接続 | △ 外部のみ | ○ VPC内 | ○ |
| コスト | ○ 月額固定 | ◎ 従量課金 | ○ 従量 | ○ 月額 |
| スケーラビリティ | △ 手動 | ◎ 自動 | ◎ 自動 | ◎ 自動 |
| 運用負荷 | △ 自己管理 | ◎ マネージド | ○ | ◎ マネージド |
| 柔軟性 | ◎ | △ 制約多 | ○ | ○ |
トレードオフ
- VPSの運用（セキュリティパッチ、監視）は自己責任
- スケーラビリティは手動対応が必要（初期段階では問題なし）
- マネージドサービスと比較して運用コストは低いが運用負荷は高い
- 将来的にユーザー規模拡大時はRailway/Renderへの移行も選択肢
ADR-006: 認証方式 - GitLab OAuth 2.0
ステータス
承認済み
コンテキスト
ユーザー認証・認可の方式を選定する必要がある。対象ユーザーは全員GitLabアカウントを保有している。
決定
GitLab OAuth 2.0 によるSSO認証を採用する。
選定理由
- 全ユーザーがGitLabアカウントを保有しており、追加の認証情報管理が不要
- GitLab API操作に必要なアクセストークンを認証フローで取得可能
- ユーザーのGitLab上の権限（Role）をそのまま認可に利用可能
代替案との比較
| 項目 | GitLab OAuth | 独自認証(JWT) | Auth0/Clerk | SAML |
|---|---|---|---|---|
| 実装コスト | ◎ 低 | △ 中 | ○ 低 | △ 高 |
| UX | ◎ SSO | △ 別途登録 | ◎ SSO | ◎ SSO |
| GitLab連携 | ◎ トークン取得 | × 別途必要 | △ 別途必要 | △ |
| コスト | ◎ 無料 | ◎ 無料 | △ 有料 | △ IdP必要 |
トレードオフ
- GitLabに強く依存（GitLab障害時にログイン不可）
- GitLab以外のプラットフォーム（GitHub等）への拡張時に追加対応が必要
- OAuth 2.0のセキュリティベストプラクティス（PKCE、state parameter）の実装が必要
ADR-007: CI/CD - GitLab CI
ステータス
承認済み
コンテキスト
ビルド・テスト・デプロイのCI/CDパイプラインを選定する必要がある。
決定
GitLab CI を採用する。
選定理由
- ソースコードリポジトリがGitLabにあり、
.gitlab-ci.ymlで完結する - GitLab Issue/MRとの統合が自然
- Runner自前運用で柔軟なビルド環境を構築可能
代替案との比較
| 項目 | GitLab CI | GitHub Actions | Jenkins | CircleCI |
|---|---|---|---|---|
| リポジトリ統合 | ◎ ネイティブ | × 別サービス | △ | △ |
| 設定の容易さ | ◎ | ◎ | △ | ○ |
| MR連携 | ◎ | × | △ | △ |
| 無料枠 | ◎ セルフホスト | ○ | ◎ セルフ | ○ |
トレードオフ
- GitLabエコシステムへのロックイン
- Self-hosted Runnerの運用負荷
- GitLab.comのShared Runnerは無料枠に制限あり（セルフホストで解消）
ADR-008: 通知基盤 - Slack / Discord Bot
ステータス
承認済み
コンテキスト
Issue関連イベントの通知手段を選定する必要がある。
決定
Slack Bot + Discord Bot のデュアル通知を採用する。共通のNotification Dispatcher層を設け、配信先を抽象化する。
選定理由
- チーム内でSlackとDiscord両方が利用されている
- Adapter パターンにより通知先の追加・変更が容易
- Webhook/Bot APIでリッチメッセージ（Embed、Button）が送信可能
代替案との比較
| 項目 | Slack + Discord | Slackのみ | Emailのみ | 独自通知UI |
|---|---|---|---|---|
| 即時性 | ◎ | ◎ | △ | ◎ |
| 到達率 | ◎ | ○ | ◎ | △ |
| インタラクション | ◎ ボタン操作 | ◎ | × | ◎ |
| 実装コスト | △ 2つ実装 | ◎ | ◎ | △ |
| ユーザー導線 | ◎ 既存ツール | ○ | △ | △ 新規習得 |
トレードオフ
- 2つのプラットフォーム向けBot開発・保守が必要
- Adapter パターンで共通化することで保守コストを軽減
- 将来的にメール通知等の追加もAdapter追加で対応可能