dotnet-core

.NET Core Architecture

House architecture conventions for .NET 8 backend services. This covers how a service is structured; for language-level conventions see the csharp skill.

Layering

Dependencies point inward only. Domain knows nothing about anything else, and Infrastructure is the one layer allowed to reference a database or an SDK — which is what lets the inner layers be tested without either.

Domain          entities, value objects, domain events, interfaces  → no dependencies
Application     use cases, CQRS handlers, DTOs, validators          → Domain
Infrastructure  EF Core, external APIs, implementations of Domain interfaces → Domain + Application
Api             endpoints, DI wiring, middleware                    → all of the above

The test that keeps this honest: if Domain compiles with no package references beyond the BCL, the boundary is intact.

Entities enforce their own invariants: private setters, a private parameterless constructor for EF Core's materialiser, and a static factory that validates. Public setters mean any layer can put the entity into an invalid state, and then "the domain guarantees X" is just a comment.

public class Product
{
    public string Name { get; private set; } = string.Empty;
    public decimal Price { get; private set; }

    private Product() { } // EF Core materialisation only

    public static Product Create(string name, decimal price) =>
        price <= 0
            ? throw new DomainException("Price must be greater than zero")
            : new Product { Name = name, Price = price };
}

Conventions

CQRS with MediatR when reads and writes genuinely differ — different models, different consistency, different scaling. On a CRUD service it is ceremony; adopt it because the domain asked for it, not by default.
Cross-cutting concerns go in pipeline behaviours, not in handlers. Validation, logging, and transactions written once as a behaviour apply to every handler and can't be forgotten in a new one.
Minimal APIs grouped with MapGroup, one file per feature area. A single Program.cs holding every endpoint stops being readable at about twenty routes.
Validation at the Application boundary (FluentValidation in a behaviour), so the same rules apply no matter which entry point invoked the use case. Validation in the endpoint only guards HTTP.
DbContext stays in Infrastructure, behind an interface the Application layer owns. Leaking DbContext into handlers ties your use cases to EF and makes them untestable without a provider.
Secrets never in appsettings.json — user-secrets locally, environment or a vault in production. Anything committed is compromised, and rotating it means a redeploy.
Health checks (/health/live, /health/ready) and structured logging with correlation IDs from the start. Retrofitting observability into a running incident is the wrong time to discover you have none. Keep the two probes genuinely different: readiness may check the database and downstream APIs, liveness must check only that the process itself is alive. A liveness probe that pings the database restarts every pod during a brief database blip, turning a recoverable dependency failure into a full outage.
Containers run as a non-root user. Add a USER line — the default root container turns a process-level compromise into host-level reach, and it costs one line to prevent.
Integration tests over WebApplicationFactory with a real database (Testcontainers). They exercise the DI graph, routing, serialisation, and EF mapping — the layers where mocked unit tests report success on a broken service.
AOT only where startup time or footprint justifies it. It rules out runtime reflection, which quietly breaks some serialisers and DI patterns; verify the whole stack tolerates it before committing.

About this skill

Layering

Conventions