📖 BookWorm: A Practical .NET Aspire Application

Introduction

⭐ BookWorm demonstrates the practical implementation of .NET Aspire in a cloud-native application. The project employs Domain-Driven Design (DDD) and Vertical Slice Architecture to organize the codebase effectively.

Project Goals

• Developed a cloud-native application using .NET Aspire
• Implemented Vertical Slice Architecture with Domain-Driven Design & CQRS
• Enabled service-to-service communication with gRPC
• Incorporated various microservices patterns
  • Utilized outbox and inbox patterns to manage commands and events
  • Implemented saga patterns for orchestration and choreography
  • Integrated event sourcing for storing domain events
  • Implemented a microservices chassis for cross-cutting concerns and service infrastructure
• Implemented API versioning and feature flags for flexible application management
• Set up AuthN/AuthZ with Keycloak
• Implemented caching with HybridCache
• Incorporated AI components:
  • Text embedding with Nomic Embed Text
  • Integrated chatbot functionality using Gemma 3
  • Standardized AI tooling with Model Context Protocol (MCP)
  • Orchestrated multi-agent workflows using Semantic Kernel
  • Enabled agent-to-agent communication via A2A Protocol
• Configured CI/CD with GitHub Actions
• Created comprehensive documentation:
  • Used OpenAPI for REST API & AsyncAPI for event-driven endpoints
  • Utilized EventCatalog for centralized architecture documentation
• Established a testing strategy:
  • Conducted service unit tests
  • Implemented contract tests
  • Established architecture testing strategy
  • Performed load testing with k6
  • Planned integration tests

Project Architecture

Getting Started

Prerequisites

• .NET 9.0 SDK
• Node.js
• Docker
• Gitleaks
• Bun
• Just
• Aspire CLI

Note

• 📧 Email services use SendGrid in production and Mailpit locally
• 🍎 Mac with Apple Silicon users need Rosetta 2 for grpc-tools compatibility
• 🐳 Docker Desktop must be running before starting the application

Run the Application

Follow these steps to get BookWorm running locally:

# 1. Clone the repository
git clone git@github.com:foxminchan/BookWorm.git

# 2. Navigate to the project directory
cd BookWorm

# 3. Run the application (starts all services)
just run

Tip

• Run just help to see all available commands.

Deploy the application

You can use the Azure Developer CLI to run this project on Azure with only a few commands. Follow the next instructions:

• Install the latest or update to the latest Azure Developer CLI (azd).
• Log in azd (if you haven't done it before) to your Azure account:

azd auth login

• Enable the azd alpha features to support bind mounts:

azd config set alpha.azd.operations on

• Initialize azd from the root of the repository.

azd init

• During initialization, you will be prompted to select the project type and services to expose. Follow these steps:

  • Select Use code in the current directory. Azd will automatically detect the .NET Aspire project.
  • Confirm .NET (Aspire) and continue.
  • Select which services to expose to the Internet (exposing gateway is enough to test the sample).
  • Finalize the initialization by giving a name to your environment.

• Create Azure resources and deploy the sample by running:

azd up

Note

• The operation takes a few minutes the first time it is ever run for an environment.
• At the end of the process, azd will display the url for the webapp. Follow that link to test the sample.
• You can run azd up after saving changes to the sample to re-deploy and update the sample.
• Report any issues to azure-dev repo.
• FAQ and troubleshoot for azd.

• For cleaning up the resources created by azd, run:

az group delete --name rg-<your-environment-name> --yes --no-wait

Documentation

For comprehensive project documentation, visit our GitHub Wiki.

Contribution

Thanks to all contributors, your help is greatly appreciated!

Contributions are welcome! Please read the contribution guidelines and code of conduct to learn how to participate.

Support

• If you like this project, please give it a ⭐ star.
• If you have any issues or feature requests, please create an issue.

License

This project is licensed under the MIT License. See the LICENSE file for details.