バックエンド概要

Bazbiiのバックエンドは、クリーンアーキテクチャに基づいた3層構造になっています。

全体構成

server-apps/
├── gateway/          # HTTP/JSON API (Connect RPC)
└── api/              # gRPC API Server

server-core/          # ドメインモデルとビジネスロジック
├── post/             # 投稿ドメイン
├── auth/             # 認証ポート定義
└── shared/           # 共通型・イベント

server-platform/     # インフラ実装
├── datastore/        # PostgreSQL実装
├── observability/    # ログ・トレース・メトリクス
└── security/         # 認証実装

各コンポーネントの役割

Gateway (server-apps/gateway)

• 役割: 外部APIのエントリーポイント
• 技術: Connect RPC, gRPC-Go
• 主要機能:
  • HTTP/JSON ↔ gRPC 変換
  • JWT認証・認可
  • レート制限
  • トレース開始
  • エラーフォーマット統一

API Server (server-apps/api)

• 役割: ビジネスロジックの実行
• 技術: gRPC, Go
• 主要機能:
  • gRPCハンドラー実装
  • ドメインサービス呼び出し
  • データ永続化
  • ドメインイベント発行

server-core

• 役割: ビジネスロジックの実装
• 技術: 純粋なGo（外部ライブラリ最小限）
• 主要機能:
  • ドメインモデル定義
  • ユースケース実装
  • ポート（インターフェース）定義

server-platform

• 役割: インフラストラクチャの実装
• 技術: PostgreSQL, OpenTelemetry, JWT
• 主要機能:
  • Repository実装
  • 観測実装
  • 認証実装

通信フロー

リクエスト処理の流れ

1. Gateway がHTTP/JSONを受信
2. Gateway がJWT検証、gRPC変換
3. API Server がgRPCリクエスト受信
4. API Server がドメインサービス呼び出し
5. platform のRepositoryがDB操作実行
6. platform のEventPublisherがイベント発行
7. レスポンスを逆順で返却

開発時の注意点

依存方向の遵守

• server-coreは外部依存を持たない
• 実装はplatformに、使用はappsで

テスト容易性

• インターフェース経由でモック可能
• ドメインロジックを独立してテスト可能

変更への耐性

• ビジネスロジックと技術的詳細を分離
• 実装を差し替えやすい設計

関連ドキュメント

• ドメイン設計 - ドメインモデルの詳細
• 実装パターン - よく使うパターン
• アーキテクチャ概要