.NET Modular Monolith Starter

A production-ready starter template for building modular monolith applications using .NET 9.0, implementing the Backend-For-Frontend (BFF) pattern with Keycloak authentication.

If you’re not familiar with the modular monolith concept, you can find an explanation for this choice in the Evolutionary Architecture’s documentation.

Features

🏗️ Modular Monolith Architecture

• Clean separation of concerns

• Module-based structure

• Easy to extend and maintain

🔐 Authentication & Authorization

• BFF (Backend-For-Frontend) pattern implementation

• Keycloak integration

🚌 Event-Driven Architecture

• Transactional Outbox Pattern implementation

• Message-driven communication between modules

📊 Observability

• OpenTelemetry integration

• Grafana dashboards

• Jaeger for tracing

• Prometheus metrics

🧪 Testing

• Unit testing setup with xUnit

• Integration testing with TestContainers

Prerequisites

• .NET SDK 9.0

• Docker

Getting Started

1. Clone the repository

2. Navigate to the source directory

cd src

3. Build the Docker images

docker-compose build

4. Start the application

docker-compose up

Important

For local development with Docker Compose, additional setup is required to handle Keycloak authentication properly. Please refer to the Local Development Guide for detailed instructions.

Note	Integrating the BFF with a front-end requires special attention, I recommend reading this detailed article: https://wrapt.dev/blog/standalone-duende-bff-for-any-spa

The application will be available at:

• BFF: http://localhost:8081

• API: http://localhost:8080

• Swagger UI: http://localhost:8080/swagger/index.html

Project Structure

src/
├── Starter/              # Main API application
├── Starter.BFF/          # Backend-For-Frontend application
├── Starter.Common/       # Shared libraries and utilities
├── Starter.UnitTests/    # Unit tests
└── Starter.IntegrationTests/ # Integration tests

Authentication Flow

The project uses Keycloak as the identity provider with the BFF pattern:

1. Frontend applications communicate with the BFF

2. BFF Authenticates user by cookie

3. If user is not authenticated, BFF challenges the user to Keycloak & deals a cookie[secure, http only and SameSite strict] to the front-end

4. BFF proxies authenticated requests to the main API

5. API validates JWT tokens and handles authorization

Running Tests

Unit Tests

dotnet test src/Starter.UnitTests

Integration Tests

dotnet test src/Starter.IntegrationTests

Note	Integration tests require Docker to be running as they use TestContainers.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

This project is based on the excellent work from the Evolutionary Architecture by Example repository. Special thanks to all the creators and contributors of the original project for providing such a great foundation for building modern .NET applications.

Original repository maintainers and contributors can be found at: https://github.com/evolutionary-architecture/evolutionary-architecture-by-example/graphs/contributors

License

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