バックエンドアーキテクチャ¶

KanjiIQバックエンドは、フラッシュカードコンテンツの配信、ロケール設定の管理、管理分析を提供するDart Frog REST APIです。

API構造¶

/api/v1/
├── config/
│   └── locale/[locale]              # GET - Locale configuration
├── kanji/
│   ├── index                        # GET - List with filtering
│   ├── [id]                         # GET - Single kanji
│   └── random/index                 # GET - Random batch
├── vocabulary/
│   ├── index                        # GET - List with filtering
│   ├── [id]                         # GET - Single vocabulary
│   └── random/index                 # GET - Random batch
└── admin/                           # Protected routes (API key required)

ミドルウェアスタック¶

すべてのリクエストは_middleware.dartで定義された階層化されたミドルウェアパイプラインを通過します：

graph TD
    R[Incoming Request] --> M1[ipBlocklistCheck]
    M1 -->|Blocked IP| R404[404 Response]
    M1 -->|Allowed| M2[securityMiddleware]
    M2 -->|Malicious Path| R404
    M2 -->|Clean| M3[corsHeaders]
    M3 --> M4[regionalAnalytics]
    M4 --> M5[requestLogger]
    M5 --> M6[databaseProvider]
    M6 --> H[Route Handler]

ミドルウェア詳細¶

ミドルウェア	用途
`ipBlocklistCheck`	ブロックされたIPアドレスからのリクエストを拒否（手動＋自動ブロック）
`securityMiddleware`	悪意のあるファイル拡張子プローブをブロック、SQLインジェクションパターンの検出、パストラバーサルの防止
`corsHeaders`	クロスオリジンリクエスト用のCORSヘッダーを追加
`regionalAnalytics`	リクエスト発信元（国、デバイスタイプ、IPハッシュ）を追跡、不審なアクティビティをフラグ、繰り返し違反者を自動ブロック
`requestLogger`	タイミング情報付きですべてのリクエストをログ
`databaseProvider`	PostgreSQL接続プールを初期化

管理ミドルウェア¶

管理ルート（/api/v1/admin/*）には追加の保護があります：

X-API-KeyヘッダーによるAPIキー認証
より厳格なレート制限（Traefik経由で50リクエスト/分）
自動ブロックから除外（管理者のロックアウトを防止）

データベース接続¶

バックエンドは以下の優先順位でデータベース認証情報を解決します：

DATABASE_URL環境変数（本番環境 — Kubernetes Secretから注入）
個別の環境変数：DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASSWORD
デフォルト：localhost:5432

セキュリティ機能¶

悪意のあるパス検出¶

このスタックに存在しないサーバーサイドスクリプト、機密設定ファイル、一般的なフレームワークエンドポイントを探索するリクエストに404を返します。

自動ブロック¶

分析ミドルウェアは自動IPブロッキングを実装しています：

各不審なリクエストはregional_analyticsテーブルにフラグが付けられます
設定可能なしきい値を超える不審なリクエストを蓄積したIPは、自動的にブロックリストに追加されます
自動ブロックは設定可能な期間後に期限切れになります
セルフロックアウトを防ぐため、管理パスは除外されます

プライバシーコンプライアンス¶

分析データはGDPR/CCPA要件に準拠しています：

生のIPアドレスは7日間のみ保持
7日後、IPはSHA-256ハッシュに置換
国レベルのジオロケーションはCloudflareのCF-IPCountryヘッダーを使用（IPジオロケーションデータベースなし）
ユーザーは管理APIを通じてデータ削除をリクエスト可能