Backend Architecture

Requirement An application MUST use Domain, Application.Abstractions, Application, Infrastructure, and WebApi as its five baseline parts.

Rationale Application.Abstractions holds the contracts that more than one module names: pipeline positions, cross-module ports, transport-neutral failures, and published integration events. It depends on Domain and nothing else. No type in it can name a use case, a handler, or a module.

That refusal is the reason it is a part rather than a folder. A folder inside Application cannot decline what a developer puts in it, and the folder that tries becomes the place every unplaced type goes.

An implementation never belongs there. The part name states the test, and a type that cannot pass it belongs to a module under litespec/backend/architecture#place-a-type-at-the-lowest-folder-that-holds-its-consumers.

Hosts support local hosting and diagnostics. They are hosts rather than application parts.

Example

Domain/
Application.Abstractions/
Application/
Infrastructure/
WebApi/

Requirement A project reference MUST point inward, so Domain references no outer layer and WebApi composes the process.

Rationale Application coordinates Domain, and Infrastructure implements the boundaries both declare. The reference matrix in Dependencies applies exactly.

Example Every reference points from an outer project to an inner one, and Domain references none of the others.

Requirement A layer MUST define its own outward contracts rather than reuse an inner layer's type, except for shared-kernel values and aggregate typed identifiers.

Rationale A change to an inner shape then stops rippling through every outer layer. Shared-kernel values cross because the kernel is shared, and aggregate typed identifiers cross because messages name their targets.

Requirement An application MUST place commands, queries, results, validators, handlers, reactions, and module-owned ports in one Application part, and cross-module contracts in Application.Abstractions.

Rationale Separate Write, Read, Contracts, and Event-handler parts are outside this backend. The separation this backend keeps is the one Fowler describes as CQRS, which separates the command and query models rather than the parts holding them. Splitting parts buys a deployment boundary the backend does not use, and costs a dependency that every use case has to cross.

Requirement Every layer MUST use the same module names and order its folders as module, then aggregate, then layer detail.

Rationale An aggregate stays flat only when its plural name equals the single module name. Module is an organization term, not a runtime base type, so no IModule or ModuleRoot contract exists.

Infrastructure holds module folders beside its provider-wide Persistence root, because provider plumbing serves every module and belongs to none.

A folder named for a technical grouping rather than a module defeats the rule, because the next unrelated type fits it. Shared, Common, Util, Helpers, Core, and Misc inside a layer are the names that do this.

Example

# single-aggregate module whose aggregate name matches the module: the aggregate stays flat in every layer
Domain/Posts/
Application/Posts/CreateDraft/
Infrastructure/Posts/
WebApi/Endpoints/Posts/CreateDraft/

# multi-aggregate module: module, then plural aggregate folder, then operation, mirrored in every layer
Domain/Customers/CustomerAccounts/
Domain/Customers/Consents/
Application/Customers/CustomerAccounts/RestrictAccount/
Application/Customers/Consents/GrantConsent/
Infrastructure/Customers/CustomerAccounts/
Infrastructure/Customers/Consents/
WebApi/Endpoints/Customers/CustomerAccounts/RestrictAccount/
WebApi/Endpoints/Customers/Consents/GrantConsent/

# Infrastructure keeps provider-wide plumbing under Persistence, beside the module folders
Infrastructure/Persistence/Postgres/
Infrastructure/Posts/
Infrastructure/Customers/CustomerAccounts/

The architecture test asserts the folder names directly, because a rule only a reviewer checks stops holding at the first missed file.

fail when a type path contains Shared, Common, Util, Helpers, Core, or Misc

Requirement A type MUST live at the lowest folder containing every consumer that names it.

Rationale The lowest folder is the use-case folder when one use case names the type. It is the aggregate folder when several use cases of one aggregate name it. It is the module folder when several aggregates of one module name it. It is Application.Abstractions when more than one module names the type, or when two layers name it with no module between them. A type only Infrastructure names is an Infrastructure type.

Two kinds of type travel with something else rather than by their own consumer count. A type that exists only to shape one contract's input or output stays with that contract, and a closed enumerated set stays whole.

The rule is mechanical, so placement is counted rather than judged. The contracts project is what remains after the count rather than a destination anyone chooses. A folder named for the absence of a reason (Shared, Common, Util, Helpers, Core, Misc) can refuse nothing. Such a folder accumulates until a tenth of the layer sits outside the module tree, unreviewed, and named for no aggregate.

Domain's shared kernel is the one folder of that name a solution keeps. Its membership is closed by litespec/backend/architecture#own-each-layers-contract-types rather than open to whatever needs a home. A service that coordinates several aggregates lives in the module that owns the aggregates it reads and writes, not with whichever module calls it first.

Requirement An application MUST keep each handler, validator, definition, persistence implementation, and endpoint implementation inside its own part and closed to extension.

Rationale Messages, results, and ports stay public only when another part uses them. Automatic discovery is not a reason to widen visibility.

Requirement An aggregate or value object MUST be the only place that enforces a state transition or invariant.

Rationale A rule duplicated in a handler drifts from the aggregate that owns it.

Requirement A command MUST mutate aggregates through repositories while a query projects read results without loading one.

Rationale An enabled persistence extension may replace the read boundary for named aggregate paths. A command still never enforces an invariant from a read projection.

Requirement An application MUST declare the execution host that runs its durable dispatch, queue consumption, and scheduled work.

Rationale The declared host is either the WebApi process or a Worker project. A rule that only restricts when a Worker project may exist never says where the work runs without one. A project can then host four background services inside WebApi, deviate from no rule it can name, and record no decision. Naming the host makes the choice visible whichever way it goes.

The declaration lives in a Decision record following litespec/core/model#keep-one-owner-and-status-on-every-record. Durable dispatch and queue consumption follow the outbox extension, and scheduled work follows the jobs extension.

The host is a composition decision, not a code-placement decision. The background service classes live in Infrastructure either way, because they hold provider and scheduling concerns. The host registers them.

Example A Decision naming WebApi as the execution host states that durable dispatch shares the request process, and states what an unavailable process costs.

Requirement An application MUST create a Worker project when background work needs independent scaling, independent deployment, or isolation from request-path resource limits.

Rationale A shared process couples the three. A restart to deploy an endpoint change interrupts a dispatch loop. Request load and dispatch load compete for one thread pool, and neither scales alone. A product with one deployable unit and modest background load accepts that coupling deliberately, which is why the choice is declared rather than assumed.

Example An application with an outbox dispatching a few messages each minute can run it in WebApi. An application dispatching continuously, or one whose dispatch must survive an endpoint deployment, creates the Worker project.

Requirement An application MUST prove project references, package boundaries, visibility, module folders, and aggregate inheritance with architecture tests.

Rationale A structural rule that only a reviewer checks stops holding as soon as review misses one file.

Requirement A host MUST register its own transport services and call the Infrastructure entry point without building a second provider.

Rationale WebApi and Worker are the only composition roots. Domain contains no registration code, and Application exposes contracts without resolving services.