https://github.com/youssefbennour/aspnetcore.starter
A modular-monolith asp.net core starter inspired by Evolutionary-architecture
https://github.com/youssefbennour/aspnetcore.starter
asp-net-core csharp eventbus grafana jaeger localization mediatr modular-monolith opentelemetry postgresql prometheus test-containers xunit
Last synced: 3 months ago
JSON representation
A modular-monolith asp.net core starter inspired by Evolutionary-architecture
- Host: GitHub
- URL: https://github.com/youssefbennour/aspnetcore.starter
- Owner: youssefbennour
- License: mit
- Created: 2024-04-02T01:25:12.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-28T08:53:58.000Z (11 months ago)
- Last Synced: 2024-05-28T21:52:57.218Z (11 months ago)
- Topics: asp-net-core, csharp, eventbus, grafana, jaeger, localization, mediatr, modular-monolith, opentelemetry, postgresql, prometheus, test-containers, xunit
- Language: C#
- Homepage:
- Size: 200 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= .NET Modular Monolith Starter
:toc: macro
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 https://github.com/evolutionary-architecture/evolutionary-architecture-by-example/blob/main/README.adoc#-modular-monolith[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
[source,bash]
----
cd src
----
=== 3. Build the Docker images
[source,bash]
----
docker compose build
----
=== 4. Start the application
[source,bash]
----
docker compose up
----
[IMPORTANT]
====
For local development with Docker Compose, additional setup is required to handle Keycloak authentication properly. Please refer to the link:LOCAL_DEVELOPMENT.adoc[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
[source]
----
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:
[source,bash]
----
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
[source,bash]
----
dotnet test src/Starter.UnitTests
----
=== Integration Tests
[source,bash]
----
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 https://github.com/evolutionary-architecture/evolutionary-architecture-by-example[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 link:LICENSE[LICENSE] file for details.