Backend Architecture

Inner code names no outer code, so business rules compile and test without adapters or hosting. An outward reference would drag technical concerns into Domain or coordination into Infrastructure. Application coordinates Domain, Infrastructure implements the boundaries both declare, and the reference matrix in Dependencies applies exactly.

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

Reviewed forWhich references point outward, away from Domain? Look at the reference graph in the code.

Marked guidance: a reviewer answers this question.

When each layer defines its own outward contracts, a change to an inner shape stops at the boundary instead of rippling through every outer layer. Shared-kernel values cross because the kernel is shared by definition, and aggregate typed identifiers cross because messages need to name their targets.

Reviewed forWhich outward contracts reuse an inner layer's type outside shared-kernel values and aggregate typed identifiers? Look at the contracts in each layer's folders.

Marked guidance: a reviewer answers this question.

One folder per declared aggregate and one folder per declared use case inside its UseCases/ folder let a reader move from a Domain aggregate to its handler, its repository, and its endpoint without a map. The closed folder names at each level keep that reading exact: a folder outside the allowed set is refused, so no second organization grows beside the tree. A module publishes what other modules may name in its Contracts/ folder sorted by kind, use cases no single aggregate owns sit in the module UseCases/ folder, and each reaction sits in one On{Fact}/ folder beside them. An aggregate stays flat only when its plural name equals the single module name.

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.

# single-aggregate module whose aggregate name matches the module: the aggregate stays flat
Organizations/
  Contracts/
    Identifiers/  Exceptions/  IntegrationEvents/  Commands/  Ports/
  Domain/  Application/  Infrastructure/  WebApi/
  UseCases/
    CreateOrganization/      use case, flat: Command, Result, Handler, Validator, Endpoint, RequestModel, ResponseModel

# multi-aggregate module: module, then aggregate folder, then UseCases, then use case
Spending/
  Contracts/
    Identifiers/  Exceptions/  IntegrationEvents/  Commands/  Ports/
  Expenses/
    Domain/  Application/  Infrastructure/  WebApi/
    UseCases/
      SubmitExpense/
      ApproveExpense/
  Policies/
    Domain/  Application/  Infrastructure/  WebApi/
    UseCases/
      DefinePolicy/

# module-level work beside the aggregates
Spending/
  UseCases/
    ReadExpenseDirectory/     a use case no single aggregate owns
    OnExpenseReimbursed/      a reaction
  Jobs/

The placement check 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

Reviewed forWhich module, aggregate, or use case folders resolve to no declared record, use a folder name their level forbids, or carry a technical-grouping name? Look at the folder paths in each module.

Marked guidance: a reviewer answers this question.

Counting consumers gives each type exactly one folder, so placement needs no judgment call. The lowest folder is the use case folder when one use case names the type, the aggregate layer folder when several use cases of one aggregate name it, the module layer folder when several aggregates of one module name it, and the product layer folder when several modules name it with no module between them. A type another module names is published by its owning module in Contracts/; across modules a type is never shared. A use case file's layer comes from its role suffix, and 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 product layer folders hold 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 product Domain/ folder 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.

Reviewed forWhich types sit above the lowest folder holding every consumer that names them? Look at each type beside its consumers, watching for Shared, Common, Util, Helpers, Core, or Misc folders.

Marked guidance: a reviewer answers this question.

Hidden implementations keep each layer's surface to the contracts other layers actually use. A public handler invites direct construction that bypasses the pipeline, and an inheritable one invites overrides that split behavior across subclasses. Messages, results, and ports stay public only when another layer uses them, and automatic discovery is not a reason to widen visibility.

Reviewed forWhich handlers, validators, definitions, persistence implementations, or endpoint implementations escape their own layer or stay open to extension? Look at the implementations in each layer.

Marked guidance: a reviewer answers this question.

The aggregate or value object that owns data is the only code that sees every change to it. A rule duplicated in a handler drifts from the aggregate that owns it, and then the same action is allowed through one path and refused through another.

Reviewed forWhich state transitions or invariants run outside their aggregate or value object, or repeat in a handler? Look at the handlers beside the aggregates they call.

Marked guidance: a reviewer answers this question.

Reads that load aggregates pay for invariant enforcement no read needs, and writes that read from projections enforce rules against stale shapes. Commands mutate one aggregate through its domain repository, following litespec/backend/application#keep-command-handlers-to-load-call-and-stage, with a use case declaring consistency: atomic over several aggregates as the declared exception. Queries project read results without loading an aggregate and write nothing, following litespec/backend/application#keep-query-handlers-free-of-writes. An enabled persistence extension may replace the read boundary for named aggregate paths, but a command still enforces no invariant from a read projection.

Reviewed forWhich commands mutate outside one aggregate or skip the domain repository, or which queries load an aggregate or write? Look at the command and query handlers in Application.

Marked guidance: a reviewer answers this question.

A read port in the owner's Contracts/Ports/ folder keeps the owning module in charge of its data: the port returns contract results keyed by typed id, so the caller names targets without loading them. A module that loaded another module's aggregate or repository would couple its reads to the owner's consistency boundary and storage. Where no shared read fits, the module answers with its own query over data it already holds.

In the Claimwick product, the reporting module reads expense totals through the spending module's read port in Contracts/Ports/, which returns contract results keyed by expense id; it loads no spending aggregate and no spending repository.

Reviewed forWhich cross-module reads bypass the owner's Contracts/Ports/ read port or load another module's aggregate or repository? Look at the cross-module reads beside the Contracts/ folders.

Marked guidance: a reviewer answers this question.

Each module guards its own consistency boundaries, so a command from another module that wrote its aggregates would bypass the owning module's rules. An act on another module's aggregate is that module's use case: the caller dispatches it or triggers it through a published integration event, and the owning module enforces its own invariants.

In the Claimwick product, a command that needs a policy change dispatches the policy module's use case or raises the integration event that triggers it; it writes no policy aggregate itself.

Reviewed forWhich commands change an aggregate outside their own module instead of dispatching that module's use case? Look at each command handler beside its module.

Marked guidance: a reviewer answers this question.

A domain event stays inside the module that raised it, while the published integration event carries the fact outside. A reaction that subscribed to another module's domain event would couple to the owner's internals and break when they change. The integration event is the stable cross-module fact, so cross-module reactions answer it.

In the Claimwick product, a reaction in the reporting module answers the published expense reimbursed integration event, never the spending domain event behind it.

Reviewed forWhich reactions subscribe to another module's domain event instead of its published integration event? Look at each reaction trigger beside the integration events.

Marked guidance: a reviewer answers this question.

The declared host is either the WebApi process or a Worker project. A rule that only restricts when a Worker exists leaves unsaid where the work runs without one, so a project can host background services inside WebApi while breaking no named rule and recording no decision. Naming the host makes the choice visible whichever way it goes.

The declaration lives in a Decision record following litespec/core/model#record-each-technical-choice-as-a-decision. 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 hosted operation classes live in Worker or Infrastructure, because they hold provider and scheduling concerns: in Worker when the project exists, otherwise in Infrastructure. The host registers them.

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

Reviewed forWhich execution host runs durable dispatch, queue consumption, or scheduled work without a naming decision? Look for the decision record under .litespec/intent/decisions/.

Marked guidance: a reviewer answers this question.

A shared process couples scaling, deployment, and resource limits: a restart to deploy an endpoint change interrupts a dispatch loop, and request load and dispatch load compete for one thread pool where neither scales alone. When background work needs independent scaling, deployment, or isolation, it gets its own process. A product with one deployable unit and modest background load accepts that coupling deliberately, which is why the choice is declared rather than assumed.

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

Reviewed forWhich background work needing its own process runs outside a Worker project? Look at the execution-host decision beside the solution project list.

Marked guidance: a reviewer answers this question.

Layer references, package boundaries, visibility, module folders, and aggregate inheritance are invisible at runtime: the application runs the same with or without them, so each one needs mechanical proof on every run. The analyzers and model check already give that proof for the boundaries in the table below. LS1001, for one, reports an outer-layer call inside a method body, which a test over compiled signatures misses. An architecture test that repeats a covered boundary holds a second copy of a rule the build or the check already enforces, and the copy drifts while the analyzer or the check keeps reporting the breach. Architecture tests hold the rest: a boundary the table covers only in part, and a structural decision the project itself made that no LiteSpec tool names.

In the Claimwick product, no architecture test repeats LS1001, LS1002, LS2004, or LS2012: the build reports a Domain file that names a Marten type, an enum declared in Domain, a command handler that holds a document session, and a handler that throws a forbidden refusal or takes the authorization guard. The architecture suite keeps a test that no module reaches another module outside its dependsOn, which LS2020 allows when the named type sits in the other module's Contracts/ folder.

Reviewed forWhich structural boundaries have no LiteSpec analyzer or model check finding in the table and no architecture test, or which architecture tests repeat a boundary the table covers? Look at the architecture tests beside the analyzer and model check runs.

Marked guidance: a reviewer answers this question.

Each host registers its own services and calls the shared Infrastructure entry point, so the full composition of a process is visible in one place. A second provider built mid-registration would resolve a different object graph than the host runs. WebApi and Worker are the only composition roots: Domain contains no registration code, and Application exposes contracts without resolving services.

Reviewed forWhich host entry points build a second provider or skip the Infrastructure entry point? Look at each host entry point.

Marked guidance: a reviewer answers this question.