TASHIKA Docs

Appearance

BFF アーキテクチャ設計 ​

本ドキュメントは、TASHIKA プラットフォームの BFF (Backend for Frontend) アーキテクチャ設計を定義します。

→ 採用決定の背景: ADR-004 React SPA + BFF アーキテクチャの採用

概要と設計判断 ​

BFF の役割 ​

BFF は ポータル特化の Presentation 層 であり、React SPA と Application 層の間に位置するデータ変換・集約・セキュリティ制御レイヤーである。

責務説明
ポータル別ビューモデル変換Application 層の Query/Command 結果を、従業員・管理者・代行事業者・システム各ポータルに最適化された形式に変換
認証・セッション管理BFF Proxy パターンによるトークンのサーバーサイド管理。ブラウザには HttpOnly Session Cookie のみ渡す
テナントコンテキスト解決セッションから TenantId / UserId を解決し、Application 層の MediatR ハンドラーに伝播
キャッシュ制御TanStack Query との協調による Cache-Control ヘッダー戦略
ファイルアップロード仲介マルチパートアップロードの受信、ウイルススキャン連携、署名付き URL 発行

アーキテクチャ上の位置づけ ​

BFF (Presentation)バックエンドHTTPHTTPHTTPHTTPin-processISender.Send()in-processISender.Send()従業員ポータル(React SPA)管理者ポータル(React SPA)代行事業者ポータル(React SPA)Backend Presentation(外部連携 API)外部システム(給与/HR)認証・セッション管理テナントコンテキストポータル別ビューモデル変換キャッシュ制御ファイルアップロード仲介Application 層(MediatR)Domain 層Infrastructure 層
BFF (Presentation)バックエンドHTTPHTTPHTTPHTTPin-processISender.Send()in-processISender.Send()従業員ポータル(React SPA)管理者ポータル(React SPA)代行事業者ポータル(React SPA)Backend Presentation(外部連携 API)外部システム(給与/HR)認証・セッション管理テナントコンテキストポータル別ビューモデル変換キャッシュ制御ファイルアップロード仲介Application 層(MediatR)Domain 層Infrastructure 層

重要な設計判断: in-process 呼び出し ​

BFF は Application 層を直接参照する（in-process）。バックエンド API への HTTP 呼び出しではない。

観点in-process（採用）HTTP 呼び出し
レイテンシゼロネットワークホップループバック HTTP でも数ms のオーバーヘッド
MediatR 利用直接 ISender.Send() を呼び出しJSON シリアライズ/デシリアライズが必要
型安全性コンパイル時に Command/Query の型を検証OpenAPI スキーマ経由の間接的な型保証
チーム構成単一チーム開発に最適マイクロサービス分割の場合に有効
将来の分離MediatR のインターフェースが抽象化層として機能。HTTP 呼び出しへの切替が可能—

Clean Architecture レイヤー図（更新版） ​

Presentation 層Application 層Infrastructure 層Domain 層BFF (Presentation)SPA 向けポータル別ビューモデル変換セッション認証・CSRFBackend Presentation外部連携 APIOAuth 2.0ApplicationCommand/Query ハンドラーバリデーションInfrastructureEF Core・Cloud KMSStorageDomainエンティティ・値オブジェクトビジネスロジック
Presentation 層Application 層Infrastructure 層Domain 層BFF (Presentation)SPA 向けポータル別ビューモデル変換セッション認証・CSRFBackend Presentation外部連携 APIOAuth 2.0ApplicationCommand/Query ハンドラーバリデーションInfrastructureEF Core・Cloud KMSStorageDomainエンティティ・値オブジェクトビジネスロジック
  • BFF (Presentation): SPA からのリクエストを処理する Presentation 層。ポータル別ビューモデル変換を担う
  • Backend Presentation: 外部連携 API を提供する Presentation 層。外部システム向けの汎用的なスキーマを採用

両者は同一の Application 層を参照するが、消費者（SPA vs 外部システム）に応じて異なるデータ形式・認証方式・レート制限を適用する。

→ 満たす要件: PE-001 パフォーマンス

プロジェクト構成 ​

bff/ ディレクトリの内部構造 ​

bff/
├── Endpoints/                -- Minimal API エンドポイント定義
│   ├── Employee/             -- 従業員ポータル向けエンドポイント
│   ├── Admin/                -- 管理者ポータル向けエンドポイント
│   ├── Agency/               -- 代行事業者ポータル向けエンドポイント
│   └── System/               -- システム管理向けエンドポイント
├── ViewModels/               -- ポータル別ビューモデル
│   ├── Employee/
│   ├── Admin/
│   ├── Agency/
│   └── System/
├── Transformers/             -- ポータル別データ変換ロジック
│   ├── IPortalTransformer.cs
│   └── Implementations/
├── Middleware/                -- BFF 固有のミドルウェア
│   ├── PortalContextMiddleware.cs
│   └── SessionAuthenticationMiddleware.cs
├── Auth/                     -- BFF Proxy 認証
│   ├── SessionStore/
│   └── CsrfProtection/
├── OpenApi/                  -- BFF OpenAPI 仕様管理
└── Program.cs                -- ホスト構成・ミドルウェア登録

依存関係 ​

プロジェクト参照先目的
Tashika.BffTashika.ApplicationMediatR Command/Query の送信
Tashika.BffTashika.Domainエンティティ・値オブジェクトの型利用（ViewModel 変換時）
Tashika.BffTashika.InfrastructureDI 登録（EF Core、Cloud KMS 等のサービス解決）

BFF は Application 層のインターフェース（ISender、IQuery<T> 等）を経由してビジネスロジックにアクセスする。Domain 層のエンティティを直接操作することはない。

Backend と BFF の共通/分離の境界 ​

層共通BFF 固有Backend 固有
Domainエンティティ、値オブジェクト——
ApplicationCommand/Query、バリデーション、ハンドラー——
InfrastructureEF Core、Cloud KMS、Storage——
Presentation—ポータル別 ViewModel、セッション認証、CSRF外部 API エンドポイント、OAuth 2.0
ミドルウェアGlobalExceptionHandler、TraceIdPortalContext、SessionAuthExternalApiAuth

サブページ ​

ドキュメント内容
リクエストパイプラインミドルウェア登録順序、ポータル別ビューモデル変換パターン
認証アーキテクチャBFF Proxy パターン、セッション管理、CSRF 保護、SSO/OIDC 統合
テナントコンテキスト・代理ログインテナントコンテキスト伝播、Impersonation フロー、データマスキング
キャッシュ・OpenAPITanStack Query 協調キャッシュ戦略、二層スキーマ管理
自動保存・ファイルアップロード自動保存エンドポイント設計、ファイルアップロード・ウイルススキャン
デプロイ方針MVP 単一サービスデプロイ、ヘルスチェック、将来のサービス分離