EN Architecture

Architecture

Português · English home

This page describes the implementation at commit 8b1d71b. The code and the regular docs/ guides at that commit are canonical; docs/superpowers/** records historical design work and is not the current implementation contract.

Projects and package boundaries

Project / package	Targets	Responsibility
Offside	netstandard2.0, net8.0, net10.0	Error, ErrorKind, Result, Result<T>, JSON catalogs and AddOffside
Offside.AspNetCore	net8.0, net10.0	HTTP status selection, OffsideProblem, Minimal API and MVC adapters
Offside.FluentValidation	netstandard2.0, net8.0, net10.0	Converts validation failures into Offside errors and results
Offside.FastEndpoint	net8.0, net10.0	FastEndpoints validation response, OpenAPI metadata and result sending
Offside.AzureAppConfiguration	netstandard2.0, net8.0, net10.0	Resolves catalogs from an already-built IConfiguration hierarchy
Offside.MediatR	netstandard2.0, net8.0, net10.0	Error notifications and a scoped collector
Offside.Tool	net8.0	offside init, catalog templates and agent-skill installation

flowchart LR
    Core[Offside core]
    Asp[Offside.AspNetCore] --> Core
    FV[Offside.FluentValidation] --> Core
    FE[Offside.FastEndpoint] --> Asp
    FE --> FV
    Azure[Offside.AzureAppConfiguration] --> Core
    Med[Offside.MediatR] --> Core
    Tool[Offside.Tool]
    Asp -. framework .-> ASPNET[Microsoft.AspNetCore.App]
    FE -. package 8.3.0 .-> FastEndpoints
    FV -. package 11.11.0 .-> FluentValidation
    Med -. range 12.0.1 to below 15 .-> MediatR

Loading

The core has no dependency on ASP.NET Core, FastEndpoints, MediatR or Azure. Domain code can therefore return structured failures without knowing how they will be transported. Adapters translate those values at an application boundary.

Offside.FastEndpoint directly references FastEndpoints 8.3.0. In its restored graph, FastEndpoints resolves FluentValidation 12.1.1 transitively, even though Offside.FluentValidation declares 11.11.0 as its minimum/direct package version. Consumers must evaluate the combined NuGet graph, not assume the lower declaration is the final resolved version.

Runtime composition

AddOffside registers the JSON message resolver. AddOffsideAspNetCore registers ASP.NET options. The Azure registration is an alternative resolver registration over configuration supplied by the host. MediatR and FastEndpoints remain opt-in adapters.

Offside does not install a global exception middleware. Normal domain failures must be returned as Result values. DomainException is only an escape hatch for a boundary that cannot return a result; the host remains responsible for catching it and choosing a response.

Continue with error and result lifecycle, message resolution, integrations and adapters, and build, testing and release.