# BookWorm: a reference implementation of Aspire with microservices and AI agents

> BookWorm is a C# demo that wires .NET Aspire, vertical slice DDD, saga orchestration and multi-agent AI protocols into one bookstore application. It is a teaching artifact, not a product, and the README says so plainly.

**foxminchan/BookWorm** — The practical implementation of Aspire using Microservices, AI-Agents

- Repository: https://github.com/foxminchan/BookWorm
- Website: https://foxminchan.github.io/BookWorm/
- Stars: 506 · Forks: 67
- Language: C#
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/foxminchan-bookworm

## What BookWorm is actually for

BookWorm is a bookstore application built to demonstrate Aspire in a cloud-native shape. The README frames it as a showcase of Aspire with AI integration, built with DDD and VSA, featuring multi-agent orchestration and standardized AI tooling through MCP with A2A and AG-UI protocol support. The audience is engineers who want a working example of those pieces connected, not teams shopping for a commerce backend. The repository carries a warning block that states the project is for demo purposes only and is not production-ready, and that sentence should govern how you read everything else. The topic tags (ai, ddd, dotnet, dotnet-aspire, microservice, multi-agent-systems) match the goal list rather than a product roadmap. Two releases are listed, dotnet9.0 and dotnet8.0, so the codebase has tracked two .NET generations. The last push was on 2026-09-04, which places it inside the last six months of activity, but that says nothing about API stability in a demo repository.

## How the pieces connect: Aspire, gRPC, sagas and the agent layer

The architecture is a set of microservices under src/, orchestrated locally by Aspire, with service-to-service calls over gRPC. Cross-cutting concerns live in a microservices chassis, which is the pattern where logging, health checks and similar plumbing are shared rather than repeated per service. Commands and events pass through outbox and inbox patterns, and the README lists both saga orchestration and choreography, so the repository contains more than one coordination style for you to compare. Domain events are stored with event sourcing. Caching uses FusionCache. Authentication and authorization run through Keycloak, with Authorization Code Flow with PKCE for users and Token Exchange for service-to-service calls, which is the part most sample applications skip. The AI side is separate but connected: Azure OpenAI supplies the LLM and embeddings, an Agent Framework orchestrates multi-agent workflows, MCP standardizes tool exposure, A2A handles agent-to-agent communication, and AG-UI and A2UI cover agent-to-user interaction. Agent governance is described as policy-based controls with monitoring. That is a lot of moving parts in one repository, and the honest reading is that each protocol is present as a demonstration, not as a hardened integration.

## Installing BookWorm and running it locally

The README requires mise as the tool version manager and Docker as the container runtime, and it states Docker must be running before the application starts. Buf CLI, Spec-Kit and GitHub Copilot CLI are optional. Clone the repository and change into it first.

```bash
git clone git@github.com:foxminchan/BookWorm.git
cd BookWorm
mise install
```

The mise install step pulls the .NET SDK, Bun, the JDK and other tools pinned by the repository. The README notes you can skip it if those tools are already installed globally. Next, set the two Aspire secrets the deployment path reads. Replace the placeholder values with your own subscription and region.

```bash
aspire secret set "Azure:SubscriptionId" "your-subscription-id"
aspire secret set "Azure:Location" "your-location"
```

Then run the first-time setup and start the application.

```bash
mise run prepare
mise run run
```

The README states that on first run you will be prompted to enter the required environment variables, so expect an interactive step rather than a silent start. Email is handled by Mailpit locally and SendGrid in production, so a local run should not need a real mail account. Expect the first start to be slow: containers, the Keycloak realm and the Aspire dashboard all come up together.

## Deploying the demo to Azure Container Apps

Deployment targets Azure Container Apps and needs an Azure subscription. The README gives a short sequence. Authenticate, deploy with Aspire, then query the container app for its public URL.

```bash
az login
aspire deploy
az containerapp show --name <app-name> --resource-group <resource-group> \
  --query properties.configuration.ingress.fqdn --output tsv
```

Cleanup is a resource group delete, and the README repeats that step twice, which suggests the author has been billed by a forgotten environment before.

```bash
az group delete --name <resource-group> --yes --no-wait
```

The README does not document rollback, blue-green switching or how to version the deployed services, so treat deployment as a one-shot demonstration. It also does not document cost estimates for the Azure OpenAI usage the AI features depend on, which is the number that would matter most if you ran this beyond a weekend.

## Where BookWorm stops being the right tool

The warning block in the README is the first limitation and the largest: demo purposes only, not production-ready. Beyond that, the testing checklist lists integration tests as planned, so the coverage that exists is unit tests, snapshot tests, architecture tests, k6 load tests and BDD end-to-end tests. A system built on sagas, outbox and event sourcing without integration tests is a system whose failure paths are asserted by design rather than demonstrated by execution. The AI features assume Azure OpenAI, so there is no local-model path described in the README, and the AI sections are unusable without a subscription. Keycloak adds an identity dependency that a simpler demo would not carry, and Token Exchange in particular is easy to misconfigure. If you want a small sample to learn Aspire alone, this repository is heavier than you need: the saga, event sourcing and agent layers are all present at once. If you want a production commerce backend, this is the wrong starting point by the author's own statement.

## How it differs from eShop and the Aspire samples

Microsoft's eShop reference application is the obvious comparison point, and the difference is where each puts its weight. eShop concentrates on a conventional microservices commerce flow with a relational store and a service bus. BookWorm keeps the commerce shell but spends its complexity budget elsewhere: vertical slice architecture with DDD and CQRS per slice, event sourcing for domain events, and both saga styles, plus a full agent layer with MCP, A2A, AG-UI and A2UI. The frontend split is also different: a Turborepo monorepo with a Next.js storefront and a Next.js backoffice, targeting WCAG 2.1 AA, rather than a Blazor or MVC client. Documentation is generated rather than hand-written in places, with OpenAPI for REST, AsyncAPI for event-driven endpoints and EventCatalog for architecture. So the choice is not which one is better but which lesson you want: eShop for service boundaries and messaging, BookWorm for Aspire orchestration plus agent protocols inside a domain-driven codebase.

## Maintenance, licensing and what upgrading costs

BookWorm is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence, and nothing in the README adds field-of-use restrictions. This is not legal advice; read LICENSE before you rely on it. On maintenance, the last push was on 2026-09-04, and the repository is not archived. The releases show dotnet9.0 dated 2025-09-25 and dotnet8.0 dated 2025-10-13, so the project has carried two .NET lines rather than jumping versions. The upgrade cost is dominated by the number of external surfaces: the .NET SDK pinned through mise, Bun and the JDK for the frontend and Keycloakify, Keycloak itself, Azure OpenAI, and the agent protocol libraries. A breaking change in any one of them lands in a codebase whose integration tests are still planned, so you would be verifying the upgrade by hand.

## Conclusion

Adopt BookWorm if you are studying how Aspire, vertical slice DDD and agent protocols fit together in one C# solution, and you accept that integration tests are still listed as planned. Do not adopt it as a base for a production bookstore: the README states it is for demo purposes only and not production-ready, and Azure OpenAI plus an Azure subscription are required for the AI paths. Verify first that Docker is running, that mise install resolves the pinned toolchain in mise.toml, and that you can supply the Azure:SubscriptionId and Azure:Location secrets the Aspire setup expects.

## FAQ

### What is BookWorm by foxminchan?

It is a C# demonstration application that shows Aspire used in a cloud-native bookstore, built with DDD and vertical slice architecture and extended with multi-agent AI features. The README states it is for demo purposes only and not production-ready.

### How do I install and run BookWorm locally?

Install mise and make sure Docker is running, then clone the repository and run mise install, set the Azure:SubscriptionId and Azure:Location secrets with aspire secret set, and finish with mise run prepare and mise run run. The README notes you will be prompted for required environment variables on first run.

### Does BookWorm need an Azure subscription?

Yes. The README states an Azure subscription is required for deploying to Azure Container Apps and for using Azure OpenAI, and the local setup asks for Azure:SubscriptionId and Azure:Location through aspire secret set.

### Which AI protocols does BookWorm demonstrate?

The README lists Model Context Protocol for standardized tooling, A2A for agent-to-agent communication, AG-UI for agent interactions with users, and A2UI for agents generating interactive interfaces, all orchestrated with an Agent Framework on top of Azure OpenAI.

## Sources

- [foxminchan/BookWorm on GitHub](https://github.com/foxminchan/BookWorm)
- [License: MIT](https://github.com/foxminchan/BookWorm/blob/main/LICENSE)
- [Project website](https://foxminchan.github.io/BookWorm/)
- [README](https://github.com/foxminchan/BookWorm/blob/main/README.md)
- [Releases](https://github.com/foxminchan/BookWorm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/foxminchan-bookworm