GitHub - youssefbennour/AspNetCore.Starter: A modular-monolith ASP.NET Core starter inspired by Evolutionary-architecture (original) (raw)

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

Features

🏗️ Modular Monolith Architecture

Clean separation of concerns
Module-based structure
Easy to extend and maintain
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

3. Build the Docker images

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:

Frontend applications communicate with the BFF
BFF Authenticates user by cookie
If user is not authenticated, BFF challenges the user to Keycloak & deals a cookie[secure, http only and SameSite strict] to the front-end
BFF proxies authenticated requests to the main API
API validates JWT tokens and handles authorization

Direct API Access

If you need to bypass the BFF and access the APIs directly, you can obtain an access token from Keycloak using the following command:

curl --location 'http://localhost:7002/realms/starter-realm/protocol/openid-connect/token'
--header 'Content-Type: application/x-www-form-urlencoded'
--data-urlencode 'grant_type=password'
--data-urlencode 'username={your username}'
--data-urlencode 'password={your password}'
--data-urlencode 'client_id=starter-client'
--data-urlencode 'client_secret=2UxRNf8TY7jwycJCWcEWTWz3joSqQlLO'

The response will contain an access token that can be used to authenticate direct API calls by including it in the Authorization header as a Bearer token.

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.

License

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