foxminchan/BookWorm

BookWorm – 最新のマイクロサービスシステムに AI エージェントを組み込む方法を示すデモ用クラウドネイティブアプリ

概要

• 典型的な e コマースストアフロント/バックオフィスと、AI を活用した一連のエージェントを組み合わせたリファレンス実装です。Aspire（Microsoft のクラウドネイティブアプリケーションフレームワーク）と、一連のエンタープライズパターン（DDD、垂直スライスアーキテクチャ、CQRS、イベントソーシング、サガ、アウトボックス/インボックスなど）を説明するために構築されています。
• AI 側では、大規模言語モデルと埋め込みに Microsoft Foundry を使用し、Agent Framework を使用して、Model Context Protocol (MCP)、A2A（エージェント間）、AG-UI（エージェント生成 UI）プロトコルを介して相互に通信できる複数のエージェントを調整します。
• リポジトリは デモのみ として明示的にマークされています – 本番用ではありません。

主な機能

領域	デモに含まれるもの
アーキテクチャ	Aspire で構築されたクラウドネイティブマイクロサービス、垂直スライスアーキテクチャ、CQRS、イベントソーシング、サガオーケストレーション、アウトボックス/インボックスパターン、横断的関心事のためのシャーシ。
セキュリティ	Keycloak による認証/認可。OAuth2 認可コードフロー（PKCE 付き）とサービス間呼び出しのためのトークン交換を使用。
AI 統合	• LLM 呼び出しとベクトル埋め込み用の Microsoft Foundry • Agent Framework によって調整されるマルチエージェントワークフロー • MCP、A2A、AG-UI プロトコルによる標準化されたツール • ポリシーベースのガバナンスとエージェントの監視 • エージェントはインタラクティブな UI コンポーネント（A2UI）を生成できます。
API	REST エンドポイント用の OpenAPI 仕様、イベント駆動型契約用の AsyncAPI、Pact ベースの契約テスト。
フロントエンド	Turborepo によるモノレポ。Next.js で構築された顧客ストアフロントと管理バックオフィス、WCAG 2.1 AA アクセシビリティ準拠。
可観測性と運用	キャッシュ用の FusionCache、CI/CD パイプライン（GitHub Actions）、SonarCloud 品質ゲート、SLSA-2 サプライチェーン保護、OpenSSF Scorecard。
テスト	サービスの単体テスト、契約テスト（Pact）、アーキテクチャテスト、フロントエンドの単体/コンポーネントテスト、BDD スタイルのエンドツーエンドテスト。

技術スタックの概要

• バックエンド: .NET 8、Aspire、gRPC、Entity Framework、EventStore（イベントソーシング）、Keycloak、FusionCache。
• AI: Microsoft Foundry（LLM と埋め込み）、Agent Framework、MCP/A2A/AG-UI プロトコル。
• フロントエンド: Next.js (React)、Turborepo、TypeScript、WCAG 準拠 UI。
• インフラストラクチャ: Docker、Azure Container Apps（デプロイメント）、Foundry 用の Azure サブスクリプション、クイックスピンアップ用の GitHub Codespaces。
• 開発ツール: mise（バージョンマネージャー）、Buf（gRPC コード生成）、Spec-Kit、GitHub Copilot CLI（オプション）、Azure CLI。

ローカルで試す方法

# リポジトリをクローンして入る
git clone git@github.com:foxminchan/BookWorm.git && cd BookWorm

# 必要なツールをインストール（dotnet、bun、jdk など）
mise install

# Foundry に必要な Azure シークレットを設定（自分の ID に置き換え）
aspire secret set "Azure:SubscriptionId" "<your-sub-id>"
aspire secret set "Azure:Location" "<your-location>"

# 一度だけの準備（コード生成、コンテナビルドなど）
mise run prepare

# すべてのサービスを起動（Docker が実行されている必要があります）
mise run run

このコマンドで、バックエンドサービス、Next.js フロントエンド、およびメールテスト用のローカル mail-pit インスタンスが起動します。起動後すぐに、ストアフロントを http://localhost:5173（またはコンソールに表示されるポート）で訪問できます。

Azure へのデプロイ

1. az login で Azure アカウントにログインします。
2. aspire deploy – スクリプトがリソースグループ、Container Apps 環境を作成し、Docker イメージをプッシュします。
3. az containerapp show … コマンドで公開 URL を取得します。
4. 完了したら、リソースグループを削除して課金を回避します。

役立つ場面

• 新興標準（MCP、A2A、AG-UI）を使用して AI エージェントをマイクロサービスエコシステムに配線する 方法を学ぶ。
• 同期（gRPC/REST）と非同期（イベントソーシング、サガ）通信の両方を含む フルスタック、DDD 駆動の例 を見る。
• Microsoft の LLM プラットフォームも利用するクラウドネイティブアプリの Azure ファーストのデプロイ を探る。
• 単一のリポジトリで CI/CD、テスト、セキュリティ強化（SLSA-2、OpenSSF Scorecard）のテンプレートを入手する。

制限/注意点

• このプロジェクトは 本番準備ができていません – 堅牢なスケーリング、マルチリージョンの回復力、徹底的なパフォーマンスチューニングが不足しています。
• Microsoft Foundry サブスクリプション に依存しています。これがないと AI コンポーネントは動作しません。
• 一部のオプショナルツール（Buf、Spec-Kit、Copilot CLI）はコアデモには必須ではありませんが、完全なコード生成ワークフローには必要かもしれません。
• UI はシンプルなデモです。実際の e コマース機能（支払い、在庫管理など）はスタブまたは省略されています。

詳細情報

• 完全なドキュメントはリポジトリの GitHub Wiki にあります。
• アーキテクチャ図（assets/BookWorm.png）は、サービスメッシュとエージェントの相互作用を視覚化しています。
• 貢献ガイドライン、行動規範、問題テンプレートが提供されており、デモを拡張したい人向けです。