Synvro.Modulus.AspNetCore 1.5.0

Modulus Framework

<p align="center"> <img src="logo.png" alt="Modulus logo" width="160" /> </p>

An enterprise-grade modular monolith framework for .NET 10, built with an explicit-registration module system, CLI scaffolding, a transactional outbox/inbox, and first-class multi-tenancy.

Overview

Modulus is designed for teams who need the architectural rigour of ABP or eShop without the heavyweight abstractions. It provides proven building blocks that compose cleanly — pick only what your application needs. The framework ships as 44 focused NuGet packages (published as Synvro.Modulus.*; the analyzer is packed inside Synvro.Modulus.AspNetCore) plus a dotnet tool CLI for scaffolding complete solutions, modules, and CRUD code.

Solution layout

src/                    45 projects across:
  core/          Modulus.Core (abstractions+impl merged), Modulus.AspNetCore
  analyzers/     Modulus.Analyzers (Roslyn MOD0001/MOD0002/MOD0003; packed in Modulus.AspNetCore)
  data/          Modulus.Data.Abstractions, Modulus.EntityFrameworkCore,
                 EF Core providers (SqlServer, PostgreSQL, MySQL, SQLite), Data.MongoDB
  identity/      Modulus.Identity (OpenIddict server, 6 IdP adapters, EF Core mapping,
                 SAML, LDAP, passkeys, sessions, SCIM 2.0)
  messaging/     Modulus.Events, Modulus.Mediator, Modulus.Inbox (+ MongoDB),
                 Modulus.Outbox, Modulus.Outbox.Abstractions (kept: circular-dep seam),
                 Modulus.Outbox.Management, Modulus.Outbox.MongoDB, EventBus.RabbitMQ,
                 EventBus.Kafka, Modulus.Sagas (Rebus), Modulus.Webhooks (signed outgoing
                 webhooks), Modulus.Realtime (SSE / SignalR) + Realtime.Redis
  platform/      Modulus.Platform (MultiTenancy, Authorization, BackgroundJobs, Caching,
                 Storage, SignalR, Networking), opt-in providers: Storage.S3,
                 Storage.AzureBlobs, Caching.Redis, SignalR.Backplane,
                 MultiTenancy.EntityFrameworkCore, Authorization.EntityFrameworkCore,
                 Authorization.Management, AuditLogging.EntityFrameworkCore,
                 AspNetCore.Redis (idempotency store), BackgroundJobs.Quartz,
                 Bff (per-client backends on YARP), Grpc,
                 GraphQL (GraphQL.NET)
  ai/            Modulus.AI.Connector (external AI platform connector), .EntityFrameworkCore
                 (change journal), .Testing (conformance kit)
  observability/ Modulus.Observability (Diagnostics + OpenTelemetry merged)
  testing/       Modulus.Testing (WebApplicationFactory harness), Modulus.Testing.Architecture
  cli/           Modulus.Cli (Spectre.Console.Cli scaffolding tool)
tests/                  42 projects
  unit/          xUnit + NSubstitute + FluentAssertions (Category=Unit)
  integration/   xUnit + Testcontainers (Docker required; Category=Integration)
  benchmarks/    BenchmarkDotNet (Modulus.Benchmarks)

Getting started

Prerequisites

• .NET SDK 10.0.109 or newer (dotnet --version)
• Docker (only for the Testcontainers-based integration tests)

Create a new application

The Synvro.Modulus.* packages are published to nuget.org on release (tags v* via .github/workflows/release.yml, requires NUGET_API_KEY), but you can also use a local feed built from this repo. Pack the local feed first, then install the CLI tool and scaffold a complete modular-monolith solution:

# Pack and install the CLI tool
dotnet pack modulus.slnx -c Release -o ./nupkg
dotnet tool install -g --add-source ./nupkg Synvro.Modulus.Cli

# Generate a new application (SQLite by default) and run it.
# --package-source wires the generated NuGet.config's modulus-local source
# (with Synvro.Modulus.* source mapping) to your local feed; omit it once the
# framework version you need is on nuget.org.
modulus app MyApp --package-source "<abs-path-to>/nupkg"
cd MyApp
dotnet restore
dotnet run --project src/API/MyApp.Api

CLI commands

The modulus CLI (Spectre.Console.Cli + Scriban) is a dotnet tool that generates complete solutions, modules, commands, queries, and CRUD code:

Each generated module uses a 4-layer Clean-Architecture layout ({App}.Modules.{Module}.{Domain,Application,Infrastructure,Presentation}) with a per-module DbContext, per-module IUnitOfWork, and DTOs/integration events living under Application/Dtos and Application/IntegrationEvents.

Templates are embedded Scriban resources under cli/Templates/.

Sample application

• samples/TradeFlow — a reference application (18 modules, 77 projects) demonstrating the framework's recommended shape: module system, CQRS via Modulus.Mediator, per-module EF Core persistence, Serilog, Sentry, multi-tenancy, and authentication. Ships a NuGet.config pointing at the sample-local nupkg/ feed (with Synvro.Modulus.* source mapping), so it builds straight after dotnet pack modulus.slnx -c Release -o samples/TradeFlow/nupkg. Also includes Dockerfile, docker-compose.yml, and GitHub Actions CI.

Module system

Modules implement IModule or inherit from ModulusModule and are registered explicitly in Program.cs. AddModulus(configuration, configure) invokes a ModulusBuilder callback where each module is added in order — registration order is authoritative for every lifecycle phase (no dependency-attribute discovery, no startup module).

public sealed class ShopModule : ModulusModule
{
    public override void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        // Register module-specific services
    }
}

// Program.cs
builder.Services.AddModulus(builder.Configuration, modules => modules
    .AddModule<IdentityModule>()
    .AddModule<DataModule>()
    .AddModule<ShopModule>());

Features

• Modular architecture — explicit-registration module system where AddModulus(configuration, modules => modules.AddModule<T>()...) wires the app and registration order drives every lifecycle phase.
• CQRS mediator — ICommand<TResult> / IQuery<TResult> with open-generic pipeline behaviors (validation, logging, transaction). No MediatR dependency.
• Domain-Driven Design — AggregateRoot<TId> with domain-event collection, ValueObject base, specifications, auditing interfaces.
• Transactional outbox — domain events implementing IIntegrationEvent are enqueued to the outbox within the same DB transaction via ModuleDbContext.SaveChangesAsync. A background OutboxProcessor claims rows atomically, retries with exponential backoff, and dead-letters after max retries.
• Inbox dedup — idempotent message processing. All IIntegrationEventHandler<T> registrations are wrapped with an atomic claim-by-EventId decorator (EF Core EfInboxStore or MongoDB MongoInboxStore) so redeliveries don't double-execute.
• Multi-tenancy — ICurrentTenant backed by AsyncLocal<TenantInfo?> (flows into background jobs / consumers), resolution from header/claim/subdomain, per-tenant connection-string resolver, and soft-delete+tenant query filters on ModuleDbContext.
• OpenIddict identity — password, client-credentials, and refresh-token grants with deny-by-default credential validation, scope allow-listing, and 6 external IdP adapters (Auth0, Authentik, Azure AD, Duende, Keycloak, Okta) that validate bearer tokens locally via OIDC discovery (signature, issuer, lifetime).
• EF Core providers — SQL Server, PostgreSQL, MySQL, SQLite (EF Core 10), plus MongoDB for document storage.
• Event bus — RabbitMQ (topic exchange, auto-reconnect) and Kafka (idempotent producer, consumer groups); all implement IModuleBus and integrate with the outbox.
• Sagas — Rebus-based long-running orchestration.
• Platform services — permission-based authorization, background job scheduler (in-memory default; replace with Quartz.NET or Hangfire for production multi-replica deployments), caching (memory, tag-based invalidation), file storage (local, S3, Azure Blob), and SignalR hub base classes.
• API hardening — rate limiting, API versioning, health probes (/health/live, /health/ready), CORS, security headers, idempotency keys, feature flags, secrets guard, at-rest PII encryption, forwarded-headers.
• Observability — OpenTelemetry tracing wired to the mediator pipeline and module lifecycle; correlation-ID propagation. Add EF Core and HTTP instrumentation via their respective OpenTelemetry packages.

Build

dotnet build modulus.slnx

The solution compiles with 0 errors, 0 warnings (TreatWarningsAsErrors is enabled globally). Central Package Management is used via Directory.Packages.props.

Common commands

Target framework

• .NET 10 (net10.0)
• SDK 10.0.109 or later

License

Apache License 2.0 — see LICENSE.