BookWorm: an Aspire microservices reference that ships an AI agent layer

The gap BookWorm is aimed at: Aspire plus agents, in one repo

Most .NET microservice samples stop at the plumbing. They show you a service, a database, maybe a message bus. BookWorm's stated goal list goes further: Aspire for orchestration, Vertical Slice Architecture combined with Domain-Driven Design and CQRS, gRPC between services, outbox and inbox patterns, saga orchestration and choreography, event sourcing, and a microservices chassis for cross-cutting concerns. On top of that it adds an AI layer with Azure OpenAI for LLM and embeddings, multi-agent orchestration through Agent Framework, Model Context Protocol for tooling, A2A for agent-to-agent communication, AG-UI for agent interactions, and A2UI for agent-generated interfaces. The intended reader is a .NET engineer who already knows what a bounded context is and wants to see how these pieces are wired when Aspire owns the composition. It is not a tutorial for someone learning C#. The README opens with a warning block stating the project is for demo purposes only and is not production-ready, and that sentence should govern how you read everything else.

What the repository actually contains, service by service

The repository layout implied by the README is a backend of .NET services, a Next.js frontend monorepo managed by Turborepo, and a Keycloak theme built with Keycloakify, each with its own GitHub Actions workflow (backend-ci.yml, frontend-ci.yml, keycloak-ci.yml). Cross-service calls use gRPC, and the prerequisite list mentions Buf CLI for gRPC schema and codegen, which tells you the protobuf contracts are generated rather than hand-maintained. Authentication uses Keycloak with Authorization Code Flow plus PKCE for users and Token Exchange for service-to-service calls, so there is no bespoke token minting in the application code. Caching goes through FusionCache. Documentation is generated rather than written by hand: OpenAPI for REST endpoints, AsyncAPI for event-driven ones, and EventCatalog as a central architecture reference. The frontend is split into a customer-facing storefront and an admin backoffice dashboard, and the goal list claims WCAG 2.1 AA support. The architecture image at assets/BookWorm.png is the authoritative diagram, and it is worth opening before reading any source file.

Running it locally: mise, Docker, and Aspire secrets

The README gives a six-step local sequence. Clone the repository, cd into it, then run mise install to install the .NET SDK, Bun, the JDK and other pinned tools, skipping that step if you already have them globally. Two Aspire secret values are required before anything else: aspire secret set "Azure:SubscriptionId" "your-subscription-id" and aspire secret set "Azure:Location" "your-location". Those are the only config keys the README names explicitly, and they matter because the AI components target Azure OpenAI. Then mise run prepare for first-time setup and mise run run to start the application. Docker must be running before you start, and the README notes that on first run you will be prompted for the required environment variables. Email is handled by SendGrid in production and Mailpit locally, so local mail never leaves the machine. A Codespaces quickstart badge is provided, which is the lowest-friction path if you do not want to install mise and Bun yourself. Deployment is a separate flow: az login, then aspire deploy, then az containerapp show with --query properties.configuration.ingress.fqdn to read back the URL. The README lists the cleanup command twice, which is harmless but tells you the deployment section was edited in place rather than reviewed.

The AI layer is the interesting part, and the least portable

The agent stack is where BookWorm diverges from the usual Aspire sample. Agent Framework handles orchestration, MCP standardises the tools the agents can call, A2A carries messages between agents, and AG-UI plus A2UI cover how an agent renders an interface back to the user. The goal list also claims agent governance with policy-based controls and monitoring, though the README does not describe what those policies look like or where they are configured, so treat that line as a promise rather than a documented mechanism. The practical constraint is the dependency on Azure OpenAI for both the LLM and the embeddings, combined with the required Azure subscription noted in the prerequisites. Anyone wanting to run the agents against a local model, or against a different vendor, has no documented path in this material. The same applies to cost: nothing in the README estimates token spend, and there is no mention of a mock or stub mode for the model calls. If your interest is the microservices side, you can read the code without ever provisioning Azure; if your interest is the agents, Azure is on the critical path.

Testing coverage is broad but explicitly incomplete

The testing strategy checkbox list is unusually honest. Service unit tests, snapshot tests, architecture tests, k6 load testing, frontend unit and component tests, and BDD end-to-end tests are all marked done. Integration tests are the one unchecked item, annotated as planned. That single gap changes what the repository can teach you. The patterns BookWorm is proudest of, outbox and inbox, saga orchestration and choreography, event sourcing, are exactly the patterns whose correctness shows up at the seams between services, and the seams are where integration tests live. You can read how the outbox is implemented, but the repository does not currently demonstrate that the outbox and the downstream consumer agree under failure. SonarCloud badges for coverage and duplicated lines are present, and the README also carries SLSA level 2 and OpenSSF Scorecard badges, which speak to supply-chain hygiene rather than to application correctness. Do not read a passing badge set as evidence that the distributed flows are verified.

When BookWorm is the wrong choice, and what to read instead

BookWorm is the wrong tool if you need a production commerce backend, if your team is not on .NET, or if you want a minimal starting template you can strip down. The Aspire dependency alone is a commitment: the run flow assumes the Aspire CLI for secrets and deployment, and the orchestration model shapes how services discover each other. The stated alternative in the .NET world is the official eShop sample from Microsoft, which is also a microservices reference but takes a different position on several of these choices: it is oriented around a single reference application with a documented deployment target rather than a catalogue of patterns, and it does not carry an agent layer at all. If your question is how to structure DDD aggregates and CQRS handlers in .NET, eShop answers it with less surface area. If your question is how an MCP tool server, an A2A hop, and an AG-UI surface sit alongside sagas and event sourcing inside one Aspire host, BookWorm is the sample that attempts it, and I have not seen the equivalent elsewhere in this material. Pick based on which question you actually have.

Maintenance, licensing, and what the MIT grant does and does not cover

BookWorm is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That covers the code in the repository. It does not cover the services the code talks to: Azure OpenAI, SendGrid, Keycloak, and whichever container images Aspire pulls are governed by their own terms, and the README's prerequisite note about needing an Azure subscription is the practical expression of that boundary. This is not legal advice; read LICENSE and the upstream terms yourself. On maintenance, the repository is not archived and the last push is recent, with two release tags, dotnet9.0 and dotnet8.0, published roughly a month apart in late 2025. That tag pattern suggests parallel support for two .NET major versions rather than a single rolling main, which raises a question the README does not answer: which branch receives the AI work, and whether the .NET 8 line will keep receiving it. Before you fork, check which tag the documentation and the Wiki describe, because the Aspire, MCP and Agent Framework surface moves faster than the .NET release cadence, and a pinned tag can drift from the APIs it calls.

Editorial conclusion

Adopt BookWorm as a study repository if you are a .NET engineer who wants to see Aspire, DDD vertical slices, outbox/inbox and saga patterns, and an MCP/A2A/AG-UI agent layer assembled in one place, and you accept the README's own warning that it is for demo purposes and not production-ready. Do not adopt it as the starting skeleton of a real storefront: integration tests are still marked planned, the AI path depends on Azure OpenAI, and the local run expects Docker plus mise. Before committing time, read the GitHub Wiki, check the two release tags (dotnet9.0 and dotnet8.0) against the branch you intend to track, and confirm you can run mise run prepare and mise run run on your machine.

Official sources

1. foxminchan/BookWorm on GitHub
2. License: MIT
3. Project website
4. README
5. Releases