Cobytelabs.Modulus.Data.SqlServer 1.3.0

Modulus Framework

An enterprise-grade modular monolith framework for .NET 10, built with an ABP-style [DependsOn] 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 31 focused NuGet packages (published as Cobytelabs.Modulus.*) plus a dotnet tool CLI for scaffolding complete solutions, modules, and CRUD code.

Solution layout

src/                    31 projects across:
  core/          Modulus.Core (abstractions+impl merged), Modulus.AspNetCore,
                 Modulus.AspNetCore.Redis (Redis-backed idempotency store)
  data/          Modulus.Data.Abstractions, Modulus.EntityFrameworkCore,
                 EF Core providers (SqlServer, PostgreSQL, MySQL, SQLite, MongoDB)
  identity/      Modulus.Identity (OpenIddict server + 6 IdP adapters +
                 EF Core mapping merged into one package)
  messaging/     Modulus.Events (abstractions merged), Modulus.Mediator
                 (abstractions merged), Modulus.Inbox (+ MongoDB), Modulus.Outbox,
                 Modulus.Outbox.Abstractions (kept — circular-dep seam),
                 Outbox.MongoDB, EventBus.RabbitMQ, EventBus.Kafka,
                 Modulus.Sagas (Rebus-based)
  platform/      Modulus.Platform (MultiTenancy + Authorization +
                 BackgroundJobs + in-memory Caching + local Storage +
                 in-process SignalR — NO heavy cloud SDKs), cloud providers
                 opt-in: Storage.S3, Storage.AzureBlobs, Caching.Redis,
                 SignalR.Backplane, MultiTenancy.EntityFrameworkCore,
                 Authorization.EntityFrameworkCore + Authorization.Management
                 (EF grant store + management API)
  observability/ Modulus.Observability (Diagnostics + OpenTelemetry merged)
  testing/       Modulus.Testing (WebApplicationFactory-based integration harness)
  cli/           Modulus.Cli (Spectre.Console.Cli scaffolding tool)
tests/                  16 projects
  unit/          xUnit + NSubstitute + FluentAssertions
  integration/   xUnit + Testcontainers (Docker required)

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 Cobytelabs.Modulus.* packages aren't on nuget.org yet, so 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
dotnet tool install -g --add-source ./nupkg Cobytelabs.Modulus.Cli

# Generate a new application (SQLite by default) and run it
modulus app MyApp
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/ProcureFlow — a reference application (API host + Users module) showing the framework's recommended shape: module system, CQRS via Modulus.Mediator, per-module EF Core persistence, Serilog, Sentry, and forwarded-headers hardening. Ships a NuGet.config pointing at the repo's local nupkg/ feed, so it builds straight after dotnet pack modulus.slnx -c Release.

Module system

Modules implement IModule or inherit from ModulusModule. Dependencies are declared via [DependsOn(typeof(OtherModule))] attributes (ABP-style). AddModulus<TStartupModule>(configuration) auto-discovers the full module graph via topological sort.

[DependsOn(typeof(IdentityModule), typeof(DataModule))]
public sealed class ShopModule : ModulusModule
{
    public override void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        // Register module-specific services
    }
}

// Program.cs
builder.Services.AddModulus<AppHostModule>(builder.Configuration);

Features

• Modular architecture — ABP-style [DependsOn] module system with topological-sort discovery and AddModulus<TStartupModule>() wiring.
• 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.