booking-microservices README

The project's README from github.com/evangelosvlachos96-dotcom/booking-microservices. As one markdown file: README.md.

booking-microservices

ci-status

Booking Microservices

A practical flight-booking system built as microservices with .NET 10, using Vertical Slice Architecture, DDD, CQRS, Event Sourcing, gRPC, RabbitMQ, Wolverine, PostgreSQL, MongoDB and .NET Aspire.

Developed by Evangelos Vlachos.

Table of Contents

Overview

This repository demonstrates how to design and run a production-style microservices system end to end: independent services with their own databases, asynchronous messaging with durable inbox/outbox, synchronous gRPC calls between services, an API gateway, centralized identity, observability and container/Kubernetes deployment.

Key goals:

Architecture

architecture diagram

Each service owns its data and exposes a small REST surface through minimal APIs. Commands mutate the write store (PostgreSQL or EventStoreDB) and publish integration events through Wolverine's durable outbox to RabbitMQ. Consumers process those events through the durable inbox and project them into MongoDB read models. Queries read from MongoDB only. Cross-service reads that must be synchronous (for example Booking validating a flight or passenger) go over gRPC.

vertical slice architecture

Services

Service Responsibility Write store Read store
Identity Users, roles, tokens (IdentityServer) PostgreSQL -
Flight Flights, airports, aircraft, seats PostgreSQL MongoDB
Passenger Passenger profiles PostgreSQL MongoDB
Booking Booking a seat on a flight for a passenger EventStoreDB MongoDB
ApiGateway Single public entry point (YARP) - -
Aspire AppHost Local orchestration and dashboard - -

Technology Stack

Project Structure

.
├── src
│   ├── ApiGateway/            # YARP gateway
│   ├── Aspire/                # Aspire AppHost and service defaults
│   ├── BuildingBlocks/        # Shared cross-cutting code (Core, EFCore, Mongo, Wolverine, Jwt, Logging, OpenTelemetry, Polly, TestBase, ...)
│   └── Services
│       ├── Booking/           # src/Booking, src/Booking.Api, tests/
│       ├── Flight/
│       ├── Identity/
│       └── Passenger/
├── deployments
│   ├── configs/               # otel-collector, prometheus, grafana configs
│   ├── docker-compose/        # infrastructure and full-stack compose files
│   └── kubernetes/            # manifests + cert-manager
├── assets/                    # diagrams and logo
├── booking.rest               # REST Client requests for manual API testing
└── booking-microservices.sln

Inside every service, code is grouped by feature (for example Flights/Features/CreatingFlight/V1/) rather than by technical layer. Each feature folder holds its endpoint, command/query, handler, validator and any events it raises, so a change to one use case touches only that folder.

Getting Started

Prerequisites

Dev Certificate

Create and trust a development HTTPS certificate so the containers can serve TLS.

Windows (PowerShell):

dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p password
dotnet dev-certs https --trust

macOS / Linux:

dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p password
dotnet dev-certs https --trust

Run with Aspire

The fastest way to get everything up locally, with a dashboard for logs, traces and metrics:

aspire run

The Aspire dashboard is available at http://localhost:18888.

Run with Docker Compose

Infrastructure only (RabbitMQ, PostgreSQL, EventStoreDB, MongoDB, Redis, Jaeger, Zipkin, OTel Collector, Prometheus, Grafana):

docker-compose -f ./deployments/docker-compose/docker-compose.infrastructure.yaml up -d

Full stack including the services:

docker-compose -f ./deployments/docker-compose/docker-compose.yaml up -d

Run with Kubernetes

Install cert-manager first, then apply the TLS issuer and the application manifests:

kubectl apply -f ./deployments/kubernetes/booking-cert-manager.yml
kubectl apply -f ./deployments/kubernetes/booking-microservices.yml

The manifests reference images under the evangelosvlachos96/ Docker Hub namespace. Build and push the service images there (or change the image names) before deploying.

Build, Run and Test manually

Build the whole solution from the repository root:

dotnet build

Run a single service from its *.Api project folder (for example src/Services/Flight/src/Flight.Api):

dotnet run

Run all tests (integration and end-to-end tests start their dependencies with Testcontainers, so Docker must be running):

dotnet test

API Documentation

Every service exposes OpenAPI documentation at /swagger (Swagger UI) and /scalar/v1 (Scalar).

For quick manual testing, open booking.rest with the VS Code REST Client extension. Seeded users are van1 / Admin@123456 (admin) and van2 / User@123456 (user).

Development Tooling

.NET tools (CSharpier formatter, dotnet-outdated) are declared in .config/dotnet-tools.json:

dotnet tool restore

Husky + commitlint enforce Conventional Commits and run the formatter before each commit:

npm install

Upgrade NuGet packages across the solution:

dotnet outdated -u

booking-microservices (evangelosvlachos96-dotcom/booking-microservices)

event-sourcing
Searching Database…

756 ·GitHub
Booking-microservices
What is this?A practical flight-booking system built as .NET 10 microservices, using Vertical Slice Architecture, DDD, CQRS, Event Sourcing, gRPC, RabbitMQ, Wolverine, PostgreSQL, MongoDB and .NET Aspire.
Is this a reusable framework or a full sample application?It is a complete, runnable sample system with five independent services (Identity, Flight, Passenger, Booking, ApiGateway), each owning its own database, meant to be run end to end and studied rather than imported as a library.
How do I get the whole stack running?The fastest path is .NET Aspire, which starts every service plus a dashboard for logs, traces and metrics; alternatively use Docker Compose (infra-only or full stack) or apply the Kubernetes manifests after installing cert-manager.
What do I need installed before running it?You need the .NET 10 SDK and Docker Desktop; Node.js is required for the Husky commit hooks, and the .NET Aspire CLI/kubectl are optional extras for those workflows.
Can I deploy the Kubernetes manifests as-is?Not out of the box - the manifests point to Docker images under the author's own 'evangelosvlachos96/' Docker Hub namespace, so you need to build and push your own images (or rename them) before deployment will actually work.
Does the dev HTTPS certificate setup differ by OS?Yes, the README gives separate instructions for trusting the dev certificate on Windows (PowerShell) versus macOS/Linux before the containers can serve TLS.
Why does only the Booking service use Event Sourcing instead of a plain database?Booking is the write side that benefits most from a full history of state changes, so it uses EventStoreDB, while Flight and Passenger use regular PostgreSQL tables; all three project their data into MongoDB for fast reads.
How do reads and writes stay in sync across services?Commands write to PostgreSQL or EventStoreDB and publish events through Wolverine's durable outbox to RabbitMQ; consumers process them via a durable inbox and project the results into MongoDB, which is the only store queries read from.
How can I log in and try the API without creating an account?The system ships two seeded users, van1/Admin@123456 (admin) and van2/User@123456 (user), and every service exposes OpenAPI docs at /swagger and /scalar/v1.
What kinds of automated tests does the project include?It has unit, integration, end-to-end and contract tests built with xUnit, NSubstitute, Testcontainers and PactNet; the integration and e2e tests spin up their own dependencies via Testcontainers, so Docker needs to be running.
What are similar projects?modular-monolith-with-ddd, awesome-software-architecture, AspNetCore-Developer-Roadmap, Smartstore, eShop, nopCommerce, domain-driven-hexagon, eShopOnWeb
Which topics is it in?cqrs, domain-driven-design, ddd, event-sourcing, microservices-architecture, rabbitmq, opentelemetry, event-driven, api-gateway, grpc, oauth2, mongodb
Creator
evangelosvlachos96-dotcom
Size
0.9 MB
Stars
756
Updated
CommitSep 13
Age
1mo
Commits · 90 Days