Layering
How code is split into layers, projects and folders, so that every file has one obvious place and dependencies only point down: Core < Infrastructure < Configuration < Hosting < Web < Automation. The Layered Architecture guide explains the layers themselves and the tooling around them.
That chain is the default layers for a solution; Automation (build tooling) sits on top so that no shipped library can depend on it. A solution may list its own layer names. Optional overrides live in the root .anarchy-toolkit.json; see Automation Preferences.
Recommendation, not a requirement. The packages work without following this convention. It is a rule only for code in the toolkit repository (see Contributing); applications can adopt it, adapt it or skip it. Opting out or adapting explains how.
Why
- Dependencies you can see. The business core never depends on a database driver, a host or a web framework, so it can be tested and reused without them. See ADR 0001.
- One place per file. Layer, then responsibility, then namespace: no team debate per pull request.
- Checked, not reviewed.
make check_layeringturns the rule into a failing build instead of a review comment.
Choose one project-layering mode
For adopters, the recommended layout determines a project’s layer from its folder: for example,
src/Library/Core/Core.csproj and src/Library/Infrastructure/Infrastructure.csproj. A single-application solution
can put its layer projects directly under src/. See Code Organization for the layouts and
the trade-offs of shared library dependencies.
The alternative is project-name prefixes, such as Core.Orders and Infrastructure.Orders.Postgres. The toolkit
itself uses this mode, which is useful for separately distributed packages but available to any solution.
Choose one mode for the whole solution. Folder mode determines layers from configured paths; prefix mode determines them from project names. Neither mode falls back to the other. Mixing detection modes is unsupported; bypassing the checks to mix them is strongly discouraged. Layer-named folders inside a project organize its code and are separate from this choice.
The solution can save its choice in the optional root .anarchy-toolkit.json (schema); bootstrap and scaffold can also receive layout arguments directly. The scaffolding, make check_layering and make dependency_map resolve explicit arguments, saved overrides, then in-code defaults. A missing file or mode is valid: the baseline is folder mode (src/Library, standard application folders and layers). The tooling never guesses a mode from project names or paths. Invalid JSON, an unknown mode, contradictory folder settings in prefix mode, and invalid effective mappings are reported:
{
"$schema": "https://anarchy-io.github.io/anarchy-toolkit/schemas/anarchy-toolkit.schema.json",
"layering": { "mode": "folder", "libraryRoot": "src/Library" }
}
layering is only one optional section in the shared file. Its optional mode is folder or prefix; the default
is folder. layers (innermost first) defaults to the chain above; root defaults to src. Folder mode defaults
libraryRoot to src/Library and maps standard application folders (src/Api, src/Jobs, src/Ui) to their usual
layers. A single-application layout can explicitly set libraryRoot to src and map its app folder. Prefix mode
suppresses folder-mode fallbacks and uses project names. All properties may be omitted; consult the
schema for the complete preference file.
Inside a project
A project’s own code sits directly at its root and is organized by responsibility folders. Use plural folder and namespace names such as Repositories/, UseCases/, Services/Aggregates/, and Extensions/; see Code Organization and Naming for the conventions.
src/Core.Orders/
├── Events/
├── Helpers/
├── UseCases/
├── Services/Aggregates/
└── Extensions/
A root folder named after a layer (Core/, Infrastructure/, Configuration/, Web/) is only allowed for a layer below the project’s own. It holds the classes the project introduces for that inner layer:
| Project layer | Allowed layer folders | Example |
|---|---|---|
Core.* |
none: a Core project never has a Core/ folder |
Core.Health/Checks/... |
Infrastructure.* |
Core/ |
Infrastructure.Orders/Core/Repositories/Orders/IOrderRepository.cs, but never Infrastructure/, Configuration/ or Web/ |
Configuration.* |
Core/, Infrastructure/ |
Configuration.Orders/Infrastructure/Repositories/Orders/Postgres/... |
Hosting.* |
Core/, Infrastructure/, Configuration/ |
none yet |
Web.* |
Core/, Infrastructure/, Configuration/, Hosting/ |
Web.Orders/Hosting/Workers/... |
Automation.* |
any lower layer | Automation.Build/Core/Entity/Build/... |
So Infrastructure.Persistence.Db.Oracle may get a Core/ folder if it has to expose its own domain entities, but code of its own layer, including its DI modules, goes at the root, never under Infrastructure/ or Configuration/. Layer folders do not change the project’s layer either: a Core/ folder inside an Infrastructure.* project is still Infrastructure code, so it may only use projects up to Infrastructure.
Where does a new file go?
- Pick the project by layer, then the folder by responsibility. Code of the project’s own layer goes at its root. Only code for an inner layer gets a layer folder: a repository contract is
Core/Service/Repository/...even when it ships in an Infrastructure package (seeInfrastructure.Persistence.Db/Core/Service/Repository/Storage/Event/). - Extension classes live under
Extensions/, organized by subject, and use the subject’s namespace. The toolkit’s own extensions still sit underExtension/in many projects, with their published namespaces; new code follows Code Organization. - Embedded SQL sits in a
Queries/folder next to the repository that loads it, because resources are resolved from the repository’s namespace (<Namespace>.Queries.<Name>.sql). - A new project must follow the solution’s selected layering mode: its name needs a known layer prefix in prefix mode; in folder mode its path must map to a layer or a configured application folder.
Composition/vsConfiguration/. An application’s composition root (its startup, entry point and DI wiring, e.g.Web/Composition/WebAppStartupBase.csor a sample’sComposition/Startup.cs) goes underComposition/.Configuration/is only for settings and options (e.g.Entity/Configuration/.../PostgresConnectionOptions.cs).
Namespace collisions to know about
The responsibility folders produce a few namespace segments that collide with type names:
Attribute. Under.../Entity/Attribute/orPresentation/Attribute/, derive fromSystem.Attributeexplicitly.Host. AHost/folder (e.g.Hosting/Host/) can shadowMicrosoft.Extensions.Hosting.Hostfor code in neighboring namespaces. If you getCS0118onHost.CreateDefaultBuilder(...), use the full type name.
For toolkit-owned types, prevent CS0118 (“is a namespace but is
used like a type”) and CS0104 (ambiguous reference) with a descriptive name or meaningful suffix, as the
naming convention requires. Automation’s ConfigurationValueSet, EnvironmentValueSet and
RuntimeValueSet make their role clear without colliding with architectural namespaces or .NET types. Reserve
qualification or an alias for unavoidable external names rather than using aliases to compensate for toolkit names.
Opting out or adapting
| You want to… | Do this |
|---|---|
| Keep your current project layout | Leave ILayeringBuild out of build/Build.cs. Nothing else in the toolkit reads your layout. |
Keep layers, but organize by folder (src/Library/Core/...) |
Use the folder baseline, or set layering.libraryRoot in .anarchy-toolkit.json; set layering.root to check only one subtree. |
| Use other layer names or more layers | Set layering.layers in .anarchy-toolkit.json. |
| Map whole applications to a layer (APIs are Web, jobs are Hosting) | Set layering.applicationFolders in .anarchy-toolkit.json (e.g. { "src/Api": "Web", "src/Jobs": "Hosting" }), as in the greenfield walkthrough. |
| Adopt it gradually | Run the check locally first, fix one project at a time, then add check_layering to the pull-request gate. |
What you lose by opting out: the layering check and the red edges in the dependency map. The scaffolded APIs, jobs and UIs (anarchy-toolkit scaffold) assume the layered layout and need moving files if you use another one.