📖 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 (see here)
• 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
  • Established architecture testing strategy
  • Performed load testing with k6 (see testing suite)
  • Planned integration tests

Project Architecture

Getting Started

Prerequisites

• .NET 9.0 SDK
• Just
• Gitleaks
• Docker or Podman

Note

Email services use SendGrid in production and Mailpit locally.

Run the Application

1. Clone the repository

   git clone git@github.com:foxminchan/BookWorm.git

2. Navigate to the project directory

   cd BookWorm

3. Run the application

   just run

Important

• Docker or Podman must be running on your machine before starting the application.
• For GPU support with AI components, install GPU drivers and run just gpu 1.
• 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

Event-Driven Architecture

Explore our event catalog for messaging patterns and API details.

Architecture Documentation

For comprehensive architecture documentation, refer to the arc42 documentation.

Contributing

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.