Monolito modular en .NET: 10 reglas para que los límites no se rompan

Reglas prácticas para construir un monolito modular en .NET con EF Core. Un schema por módulo, API pública como única puerta, tests de arquitectura, transacciones, consistencia y cómo dejar listo el camino a servicios.

Un monolito modular tiene un solo deploy pero módulos con fronteras reales. La parte difícil no es dibujar los módulos: es evitar que, tres meses después, alguien los atraviese "solo por hoy". Estas son diez reglas para que no pase, con ejemplos en .NET y EF Core.

Inspirado en 20 Laws of Modular Monoliths, de Anton Martyniuk. Acá elegí diez, las reescribí con mis ejemplos y agregué los matices que me parecen importantes. Para el concepto general, mirá Modulith.

#1. Empezá modular y extraé solo con motivo

Arrancá con un solo deploy y módulos separados. Extraé un módulo a un servicio únicamente cuando necesite algo que el monolito no le da: su propio equipo, su propio calendario de releases o su propio escalado.

La razón de fondo: los límites los vas a errar la primera vez, como todos. En un monolito modular, corregir un límite es un refactor dentro de una solución. En microservicios es una migración entre servicios, contratos y equipos.

Para decidir con criterio, mirá la comparativa de estilos.

#2. Un schema por módulo, no una base por módulo

No necesitás cuatro bases de datos para cuatro módulos. Alcanza con una base y un schema por módulo, y un DbContext por módulo que solo ve sus tablas:

public sealed class SalesDbContext(DbContextOptions<SalesDbContext> options) : DbContext(options)
{
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("sales");
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(SalesDbContext).Assembly);
    }
}

// Registro: tabla de historial de migraciones propia del módulo
services.AddDbContext<SalesDbContext>(options =>
    options.UseNpgsql(connectionString, npgsql =>
        npgsql.MigrationsHistoryTable("__EFMigrationsHistory", "sales")));

Con su propia tabla de historial, cada módulo migra de forma independiente. La regla: ningún módulo toca las tablas de otro, ni siquiera para leer.

#3. La API pública es la única puerta

Cada módulo expone un proyecto PublicApi con una interfaz y unos pocos DTOs (records). Todo lo demás es internal:

// Sales.PublicApi
public interface ISalesModule
{
    Task<OrderSummary?> GetOrderAsync(Guid orderId, CancellationToken ct);
}

public sealed record OrderSummary(Guid Id, decimal Total, string Status);

// Sales (proyecto interno)
internal sealed class SalesModule(SalesDbContext db) : ISalesModule
{
    public async Task<OrderSummary?> GetOrderAsync(Guid orderId, CancellationToken ct) =>
        await db.Orders
            .Where(o => o.Id == orderId)
            .Select(o => new OrderSummary(o.Id, o.Total, o.Status.ToString()))
            .SingleOrDefaultAsync(ct);
}

Dejar la implementación internal hace que el compilador oculte los detalles. Y si más adelante extraés el módulo a un servicio, esta misma interfaz pasa a ser un cliente HTTP sin que cambie quien la usa.

Es el mismo principio de los puertos de Hexagonal, aplicado entre módulos.

#4. Los límites los cuida un test, no el compilador

El compilador no te protege de una referencia "solo por hoy" al Domain de otro módulo: compila perfecto. Tu agente de IA va a tomar el mismo atajo. La defensa es un test de arquitectura que falla el PR y nombra el tipo que rompió la regla.

[Fact]
public void SalesMustNotDependOnBillingInternals()
{
    TestResult result = Types.InAssembly(typeof(SalesModule).Assembly)
        .ShouldNot()
        .HaveDependencyOnAny("Billing.Domain", "Billing.Infrastructure", "Billing.Features")
        .GetResult();

    Assert.True(result.IsSuccessful,
        $"Forbidden dependencies: {string.Join(", ", result.FailingTypeNames ?? [])}");
}