BFF 概要

システム概要

mloca6-bff は MLoca6 の BFF（Backend for Frontend）です。 フロントエンド（Web）からのリクエストを受け付け、複数のバックエンドサービスへのアクセスを集約・変換して返します。

GraphQL を主インターフェースとして採用しており、認証・認可・データ取得・変換のロジックをここに集約することで、フロントエンドが複数のバックエンドを直接意識しなくて済む構成になっています。

アーキテクチャ図

graph TB
    FE[フロントエンド]

    subgraph BFF[mloca6-bff]
        direction TB
        GQL["/graphql  GraphQL"]
        REST["/api/v1/...  REST"]
        AUTH[認証ミドルウェア JWT / API Key]
        GQL --> AUTH
        REST --> AUTH
    end

    DAPR[Dapr 経由\nmloca-api / geo-api / voip-api / chat-api]
    HTTP[HTTP 直接\nvpt / chat / realtime-event / linebus / mobustation\nKeycloak / mfa / auditLog / p2relay / ext-api]
    INFRA[インフラ\nAWS S3 / DynamoDB / SQS / MCNS Server]

    FE -->|GraphQL| GQL
    FE -->|REST| REST
    AUTH --> DAPR
    AUTH --> HTTP
    AUTH --> INFRA

エンドポイント一覧

メソッド	パス	認証方式	用途
POST	/graphql	JWT Bearer（@isAuthenticated ディレクティブ）	GraphQL メインエンドポイント
GET	/playground	なし（非本番環境のみ）	GraphQL Playground
GET	/.well-known/jwks.json	なし	JWT 公開鍵（JWK）取得
POST	/api/v1/DrivingReport/GenerateCallback	API キー（x-api-key ヘッダー）	運転日報生成コールバック
POST	/api/v1/UserAccount/BulkOperationCallback	API キー（x-api-key ヘッダー）	ユーザーアカウント一括操作コールバック
POST	/api/v1/Mobile/BulkUpdateCallback	API キー（x-api-key ヘッダー）	移動局一括更新コールバック
GET	/health/ready	なし	ヘルスチェック（依存サービス含む）
GET	/health/live	なし	ヘルスチェック（自身の死活）

/playground は環境変数 ENVIRONMENT_NAME が production 以外のときのみ有効。

リクエストフロー

GraphQL リクエスト（@isAuthenticated あり）

sequenceDiagram
    participant FE as フロントエンド
    participant BFF as BFF
    participant AUTH as 認証ミドルウェア
    participant MLOCA as mloca-api
    participant BE as バックエンドサービス

    FE->>BFF: POST /graphql<br/>Authorization: Bearer <token>
    BFF->>AUTH: @isAuthenticated ディレクティブで検証
    AUTH->>MLOCA: 公開鍵取得（JWK）
    MLOCA-->>AUTH: RSA 公開鍵
    AUTH->>AUTH: JWT 検証（RS256）<br/>クレーム検証（org:id, region, iss 等）
    AUTH-->>BFF: auth_user をコンテキストに格納
    BFF->>BE: バックエンドAPI呼び出し
    BE-->>BFF: レスポンス
    BFF-->>FE: GraphQL レスポンス

コールバック REST リクエスト（API キー認証）

sequenceDiagram
    participant CALLER as 呼び出し元サービス
    participant BFF as BFF

    CALLER->>BFF: POST /api/v1/DrivingReport/GenerateCallback<br/>x-api-key: <key>
    BFF->>BFF: API キー検証
    alt 認証失敗
        BFF-->>CALLER: 401 Unauthorized
    else 認証成功
        BFF->>BFF: 運転報告書生成処理
        BFF-->>CALLER: 200 OK
    end

依存サービス一覧

詳細は data-sources.md を参照。

サービス	通信方式	ヘルスチェック対象
mloca-api	Dapr	✅
geo-api	Dapr	✅
voip-api	Dapr	✅
chat-api	Dapr / HTTP	❌
vpt-api	HTTP	❌
realtime-event-api	HTTP	❌
linebus-api	HTTP	❌
mobustation-api	HTTP	❌
Keycloak	HTTP	❌
mfa-api	HTTP	❌
auditLog-api	HTTP	❌
p2relay-api	HTTP	❌
ext-api	HTTP	❌
AWS S3	AWS SDK	❌
AWS DynamoDB	AWS SDK	❌
AWS SQS	AWS SDK	❌
MCNS Server	TCP	❌

ヘルスチェック対象のサービスは /health/ready エンドポイントで確認できます。 geo-api・mloca-api・voip-api のいずれかが NG の場合、status: NG を返します。

技術スタック

項目	内容
言語	Go 1.24
Web フレームワーク	Gin
GraphQL ライブラリ	gqlgen v0.17
サービス間通信	Dapr
JWT 検証	RS256（dgrijalva/jwt-go）
AWS SDK	aws-sdk-go / aws-sdk-go-v2
ログ	zerolog

開発リソース

環境	URL
ステージング Playground	https://stg-mloca6-bff.mcapps.jp/playground