foxminchan/BookWorm

BookWorm – a demo cloud‑native app that shows how to weave AI agents into a modern micro‑service system

What it is

• A reference implementation that combines a typical e‑commerce storefront/back‑office with a suite of AI‑powered agents. It is built to illustrate Aspire (Microsoft’s cloud‑native application framework) together with a whole stack of enterprise patterns (DDD, vertical‑slice architecture, CQRS, event sourcing, saga, outbox/inbox, etc.).
• The AI side uses Microsoft Foundry for large language models and embeddings, and the Agent Framework to orchestrate multiple agents that can talk to each other via the Model Context Protocol (MCP), A2A (agent‑to‑agent) and AG‑UI (agent‑generated UI) protocols.
• The repo is explicitly marked as a demo only – it is not meant for production use.

Key capabilities

Area	What the demo includes
Architecture	Cloud‑native micro‑services built with Aspire, vertical‑slice architecture, CQRS, event sourcing, saga orchestration, outbox/inbox patterns, and a chassis for cross‑cutting concerns.
Security	Keycloak for authentication/authorization, using OAuth2 Authorization Code Flow with PKCE and token‑exchange for service‑to‑service calls.
AI integration	• Microsoft Foundry for LLM calls and vector embeddings • Multi‑agent workflows orchestrated by the Agent Framework • Standardised tooling via MCP, A2A, AG‑UI protocols • Policy‑based governance and monitoring of agents • Agents can generate interactive UI components (A2UI).
APIs	OpenAPI spec for REST endpoints, AsyncAPI for event‑driven contracts, Pact‑based contract testing.
Front‑end	Monorepo powered by Turborepo; customer storefront and admin back‑office built with Next.js, WCAG 2.1 AA accessibility compliance.
Observability & Ops	FusionCache for caching, CI/CD pipelines (GitHub Actions), SonarCloud quality gates, SLSA‑2 supply‑chain protection, OpenSSF Scorecard.
Testing	Unit tests for services, contract tests (Pact), architecture tests, frontend unit/component tests, BDD‑style end‑to‑end tests.

Tech stack snapshot

• Backend: .NET 8, Aspire, gRPC, Entity Framework, EventStore (event sourcing), Keycloak, FusionCache.
• AI: Microsoft Foundry (LLM & embeddings), Agent Framework, MCP/A2A/AG‑UI protocols.
• Frontend: Next.js (React), Turborepo, TypeScript, WCAG‑compliant UI.
• Infrastructure: Docker, Azure Container Apps (deployment), Azure subscription for Foundry, GitHub Codespaces for quick spin‑up.
• Dev tools: mise (version manager), Buf (gRPC codegen), Spec‑Kit, GitHub Copilot CLI (optional), Azure CLI.

How to try it locally

# clone & enter repo
git clone git@github.com:foxminchan/BookWorm.git && cd BookWorm

# install required tools (dotnet, bun, jdk, etc.)
mise install

# set Azure secrets needed for Foundry (replace with your own IDs)
aspire secret set "Azure:SubscriptionId" "<your‑sub-id>"
aspire secret set "Azure:Location" "<your‑location>"

# one‑time preparation (generates code, builds containers, etc.)
mise run prepare

# start all services (Docker must be running)
mise run run

The command brings up the backend services, the Next.js front‑ends, and a local mail‑pit instance for email testing. After a short startup you can visit the storefront at http://localhost:5173 (or the port shown in the console).

Deploying to Azure

1. az login to your Azure account.
2. aspire deploy – the script creates a resource group, a Container Apps environment, and pushes the Docker images.
3. Retrieve the public URL with the az containerapp show … command.
4. When you’re done, delete the resource group to avoid charges.

When it’s useful

• Learning how to wire AI agents into a micro‑service ecosystem using emerging standards (MCP, A2A, AG‑UI).
• Seeing a full‑stack, DDD‑driven example that includes both synchronous (gRPC/REST) and asynchronous (event sourcing, saga) communication.
• Exploring Azure‑first deployment of a cloud‑native app that also consumes Microsoft’s LLM platform.
• Getting a template for CI/CD, testing, and security hardening (SLSA‑2, OpenSSF Scorecard) in a single repo.

Limitations / caveats

• The project is not production‑ready – it lacks robust scaling, multi‑region resilience, and thorough performance tuning.
• It depends on a Microsoft Foundry subscription; without that the AI components will not work.
• Some optional tooling (Buf, Spec‑Kit, Copilot CLI) is not required for the core demo but may be needed for full code‑generation workflows.
• The UI is a simple demo; real‑world e‑commerce features (payments, inventory management, etc.) are stubbed or omitted.

Where to find more

• Full documentation lives in the repo’s GitHub Wiki.
• The architecture diagram (assets/BookWorm.png) visualises the service mesh and agent interactions.
• Contribution guidelines, code of conduct, and issue templates are provided for anyone who wants to extend the demo.