andaime does not impose an architecture. A handler is a function, a controller method or a lambda, and everything else is
your code. Small services are often best as one module (examples/hello). For applications that will grow, this page
describes a ready-made structure based on Clean Architecture and SOLID. andaime new generates it (cli.md), but
nothing in andaime depends on it: you can follow it by hand, change it, or ignore it.
examples/clean is a complete application in this structure: users over HTTP, Postgres and memory, companies with their
members (a tenant, the acting user, two tables in one unit of work), a background job scheduled through the transactional
outbox, and their tests. It is the exact output of andaime new --tenant and andaime generate.
The folders are the circles of the Clean Architecture diagram, and a feature is the same file name in every layer:
source/
domain/users.d entities and business rules
usecases/users.d what the application does, and the ports it needs
adapters/http/users.d a controller, the JSON a client sends and receives
adapters/postgres/users.d a repository over andaime:pg
adapters/memory/users.d the same repository in memory (tests, running without a database)
adapters/jobs/users.d background jobs
app.d the composition root: which adapter implements each port, which routes the app serves
main.d, jobs.d, config.d the process: configuration, roles, serve
The dependency rule: source code points inward only.
| Layer | May import |
|---|---|
domain/ |
druntime, Phobos, andaime.values (Optional, PatchField, JsonValue, Uuid, Timestamp, CalendarDate: values with no I/O) |
usecases/ |
domain/, andaime.values |
adapters/ |
usecases/, domain/, andaime |
app.d, main.d, jobs.d, config.d |
anything |
So the business code compiles and is tested without a framework, a database or a network, and an adapter can be replaced
without touching it. andaime check verifies the rule from the compiler's own import graph (below).
Domain: plain structs and functions. No framework, no status codes.
module domain.users 2025;
struct User { long id; string name; string email; }
struct NewUser { string name; string email; }
/// What the business decides; throws RuleViolation. The request's format is checked at the edge.
void checkRules(const NewUser user) { }Use cases and ports: one final class per use case, with one execute. Its constructor takes the ports it needs;
the port is an interface declared next to the use cases that need it (the use cases own it, the adapters implement it).
module usecases.users 2025;
interface UserRepository
{
Optional!User find(long id);
User add(NewUser user); // throws Conflict when a unique value is taken
// ...
}
final class GetUser
{
private UserRepository users;
this(UserRepository users) { this.users = users; }
User execute(long id)
{
auto found = users.find(id);
if (!found.has)
throw new NotFound("user not found");
return found.get;
}
}Adapters: the HTTP adapter is a controller. Its DTOs are the HTTP contract (validation attributes, wire names, OpenAPI), mapped to and from the domain:
module adapters.http.users 2025;
struct UserIn { string name; string email; }
struct UserOut { long id; string name; string email; }
final class UserController
{
private GetUser getUser;
// ...
@Get("/users/{id}") @responds(404, "user not found")
UserOut get(long id) => toOut(getUser.execute(id));
}The Postgres and memory repositories both implement UserRepository; the Postgres one turns a unique violation into the
domain's Conflict.
Composition root: app.d builds the adapters, the use cases and the routes. buildApp runs once per worker, so each
worker gets its own repositories and pool, and nothing needs a lock:
App buildAppWith(Adapters a)
{
auto app = new App;
app.mapError!NotFound(404);
app.mapError!Conflict(409);
app.mapError!RuleViolation(422);
auto api = app.group("/api/v1");
api.mount(construct!UserController(a)); // its use cases, and their ports, are found in `a` by type
app.serveOpenApi(OpenApiInfo("clean", "0.1.0"));
return app;
}
App buildApp() => buildAppWith(currentAdapters()); // Postgres, or memory with STORE=memoryconstruct!T(a) reads the constructor of T and fills each parameter from the field of Adapters with that type, or by
building it the same way when it is a concrete class (the controller's use cases). A value that is not a port, such as a
JWT secret, is an extra argument: construct!Login(a, secret). It is resolved at compile time: a parameter with no
value, two fields of one type, a cycle or a class with several constructors is a one-line compile error that names the
class and the parameter. Writing the new lines by hand still works; construct! only removes the lines that repeat the
constructor.
Kept: the dependency rule; entities and use cases without the framework; the core owning its interfaces (dependency inversion); one use case per class, with only the ports it needs (single responsibility, interface segregation); thin controllers; one contract test that every implementation of a port passes (Liskov substitution).
Changed, because of andaime and D:
- No presenters or output boundaries. In andaime a handler's return type is the HTTP contract and produces the OpenAPI
document. A presenter writing to an output port would make handlers return
voidand lose the response schema. Use cases return values; controllers map them to response DTOs. - No interfaces for the use cases. Tests replace the ports, not the use cases, and
finalmethods are not virtual. - No dependency injection container.
buildAppalready runs once per worker: it is the composition root ("pure DI").construct!T(adapters)only fills a constructor by type at compile time, from a struct you wrote; there is no registry, nothing is looked up at run time, and a missing port does not build. D has no runtime reflection for a runtime container. - Interfaces, not templates, for ports. Templated use cases would be compiled again for each use, slow the build and make the error messages worse. A virtual call costs nanoseconds next to a database round trip.
- Exceptions for business errors.
domain/errors.dhasNotFound,ConflictandRuleViolation, each with acode;app.mapErroranswers each with its status, without logging them as failures, andapp.errorBody(&apiError)(adapters/http/errors.d) gives every error the API answers one body,{"message": "...", "code": "..."}(validation.md). - Wire names are the adapters' business.
dub.sdlsetsversions "AndaimeNamingSnakeCase": JSON, query strings, OpenAPI and columns spellcreatedAtascreated_at, and the domain's structs carry no andaime attribute (requests.md). Where a DTO differs from a domain type by a few fields,copyAs!UserOut(user)copies the rest. - Time, identifiers and tokens are ports.
usecases/system.ddeclaresClock(it returns aTimestamp),IdGeneratorandTokenGenerator;adapters/system/implements them over the system (uuid7(), the secure random generator) andtests/fakes.dgives fixed ones, so a use case that stamps a date or creates an id is tested exactly.
- The format of a request (types, required fields, lengths, ranges) belongs to the HTTP DTO:
@minLength,@inRangeand the rest answer 422 before any use case runs (validation.md). - What the business decides (an e-mail that must be unique, an order that cannot be cancelled once shipped) belongs to the
domain and the use cases: they throw
RuleViolationorConflict.
A use case that writes through two repositories, or writes and schedules a job, owns the boundary of its transaction
through a port, usecases/uow.d:
interface UnitOfWork
{
void run(scope void delegate() @safe work); // all of it, or none of it
void readOnly(scope void delegate() @safe work); // one consistent view
}
T inUnitOfWork(T)(UnitOfWork uow, scope T delegate() @safe work); // for work that returns a value
final class CreateCompany
{
// ... the constructor takes uow, companies, memberships
Company execute(Actor actor, NewCompany input)
{
return inUnitOfWork(uow, () {
auto company = companies.add(input);
memberships.add(Membership(company.id, actor.userId, Role.owner));
return company;
});
}
}The use case sees no connection and no framework. The adapters decide what a transaction is:
PgUnitOfWork(adapters/postgres/uow.d) runsworkindb.transaction. andaime:pg's transactions are ambient: whileworkruns, every repository built over the worker's pool, and the job store over the same conninfo, runs its statements on that transaction's connection (database.md). So the composition root still builds the repositories once per worker, and a nestedrunis a savepoint.MemoryUnitOfWork(adapters/memory/uow.d) snapshots every store it tracks (uow.track(new MemoryUserRepository), and the in-memory job store) and puts them back whenworkthrows, so the tests in memory see the same rollback.
What does not join: a query inside offload (another thread; andaime asserts on it), and another fiber (spawn, another
request). PgConfig.requireTransaction makes a statement outside any unit of work an error, for teams that want every
write inside one.
Why ambient, and not a typed transaction per feature. The other design hands the work an interface of repositories
bound to one transaction (interface CompanyTx { CompanyRepository companies(); MembershipRepository memberships(); },
UnitOfWork!CompanyTx.run((CompanyTx tx) { tx.companies.add(...); })), so the compiler checks that the repositories
used are the transaction's. Both were built on the companies feature and measured:
| ambient (kept) | typed Tx |
|
|---|---|---|
| code of the feature (use cases, both adapters, tests) | 307 lines | 367 lines (+20%) |
| per feature, on top | nothing | a Tx interface, a Postgres and a memory implementation, a Tx fake per test |
| read use cases | call the repository | wrap the call in uow.readOnly((tx) { result = ...; }) |
| a transaction across two features | any repositories join | a new Tx interface combining both |
| type-check of the app (source and tests) | 371 ms | 371 ms |
3,000 CreateCompany on Postgres |
942 ms | 944 ms |
Same speed and compile time; the typed design costs code in every feature and makes cross-feature transactions a new
interface each time. What it buys, the compiler refusing a repository from outside the transaction, the ambient design
gets from the pool itself (a repository over the worker's pool always joins), with an assertion for offload and
requireTransaction for statements outside any unit of work.
andaime new --tenant adds what a multi-tenant application needs from the start, and a feature that uses it
(companies and their members):
Tenant(domain/tenancy.d) is a typed value: the company that owns some data. A repository method over data a company owns takes it (memberships.list(actor.tenant)), so every query names whose data it reads: forgetting the filter does not compile, where an implicit, scoped repository would leak data between companies when one is missed.Actoris the user acting on a request: id, active tenant, role. The controller builds it from the request's authentication (Local!AuthContext, set by a middleware) and passes it toexecute; the use case decides with the domain's policies (require(canSeeMembers(actor), "...")), which throwForbidden(403). Permissions are business rules, not status codes.adapters/http/auth.dis a development stand-in that trusts three headers. Replace it with real authentication (a session, a verified token) before production; it only has to set the sameAuthContext.CreateCompanywrites the company and the owner's membership in one unit of work, withClockandIdGeneratorfor its timestamp and its UUID.
A query use case does not have to return entities. When a screen needs a list with data from several tables (tasks with
their tags and assignees), declare its shape in usecases/ (struct TaskListItem { ...; TagRef[] tags; }) and let the
Postgres adapter fill it in one statement, with json_agg/array_agg into Json!(TagRef[]) or array fields and
rowsAs (database.md). The memory adapter builds the same shape from its stores. One round trip instead of
one per row, and the entity stays what the business rules need.
A job is an entry point, like a controller. It comes in two parts: the payload (the @Job struct: what is stored) and its
handler (a class that receives the use case through its constructor and hands it the payload). jobs.d is the jobs'
composition root: buildJobs builds the handlers over currentAdapters(), once, on the thread that runs the jobs, as
buildApp builds the routes. A job of AllJobs without a handler stops the start.
// adapters/jobs/users.d
@Job("default")
struct SendWelcomeJob { long userId; }
final class SendWelcomeHandler
{
private SendWelcome useCase;
this(SendWelcome useCase) { this.useCase = useCase; }
void perform(const SendWelcomeJob job, ref JobContext ctx) @safe { useCase.execute(job.userId); }
}
// jobs.d
JobHandlers buildJobs()
{
auto handlers = new JobHandlers;
handlers.handle!SendWelcomeJob(new SendWelcomeHandler(new SendWelcome(currentAdapters().users)));
return handlers;
}No global, no @trusted: the tests build a handler over in-memory adapters and pass it to drainJobs
(jobs-and-cron.md).
The other direction, a use case that schedules a job, is a port like any other effect on the outside world. generate job
writes it next to the use case, and its adapter next to the job:
// usecases/users.d
interface SendWelcomeScheduler { void schedule(long userId); }
// adapters/jobs/users.d
final class QueuedSendWelcome : SendWelcomeScheduler
{
private JobStore store;
this(JobStore store) { this.store = store; }
void schedule(long userId) { SendWelcomeJob job; job.userId = userId; enqueue(store, job); }
}Called inside a unit of work (below), the job is part of the transaction: the transactional outbox, with no connection in sight. A rollback leaves no job; a commit stores it and wakes a worker.
jobs.d also holds the process roles: --role=api serves HTTP, --role=worker runs the jobs, --role=all does both
(jobs-and-cron.md).
- HTTP end to end, in memory:
TestClient(buildAppWith(memoryAdapters()))runs the real routes, validation, use cases and error mapping, without a database. - The repository contract: one function of assertions runs on
MemoryUserRepositoryalways, and onPgUserRepositorywhenTEST_DATABASE_URLnames a test database. Both adapters then behave the same, so tests in memory say something about production. - Jobs:
TestJobStoreenqueues and drains them on the test's thread (jobs-and-cron.md).
dub test runs source/ and tests/; source/main.d holds only main, so the tests can import the composition root.
tests/openapi.d keeps a snapshot of the API contract in tests/openapi.json (UPDATE_OPENAPI=1 dub test accepts a change,
static-files-and-openapi.md).
andaime.json lists the layers and what each may import:
"layers": {
"domain": { "modules": ["domain.*"], "may_import": ["andaime.values.*"] },
"usecases": { "modules": ["usecases.*"], "may_import": ["domain", "andaime.values.*"] },
"adapters": { "modules": ["adapters.*"], "may_import": ["usecases", "domain", "andaime.*"] },
"main": { "modules": ["main", "app", "config", "jobs"], "may_import": ["*"] }
}andaime check compiles source/ with -deps (no code is generated) and prints one line for each import that breaks
a rule, for example andaime check: domain.users imports andaime.web.application (domain may import: andaime.values.*). A layer may always import its own modules, druntime and Phobos are always allowed, and a module
that is in no layer is reported too. Edit the rules to fit your own architecture: hexagonal, layered or anything else.
- A feature that outgrows one file per layer becomes a D package:
usecases/users.dturns intousecases/users/package.dplususecases/users/*.d. The rules do not change. - One feature using another goes through a port of the caller:
usecases/orders.ddeclares what it needs from users, and an adapter (or the composition root) implements it with the users' use cases or repository. - Writes across repositories in one transaction: run them in the use case's unit of work (above).
- One class per file: when a feature's use cases outgrow one file, make
usecases/companies/a package with one module per use case (create_company.d,list_members.d) and the ports inusecases/companies/package.dorports.d. The generators still write one file per layer; move the classes by hand when the file gets long (the rules and the imports ofapp.ddo not change ifpackage.dimports the modules publicly). - A large
app.d: give each feature a composition function next to it (compose/companies.d:void mountCompanies(Group api, ref Adapters a)), and keepbuildAppWitha list of calls. Add the folder to themainlayer ofandaime.json. - A package prefix: an application whose modules are
visto.domain.users,visto.usecases.users... uses globs with it inandaime.json("modules": ["visto.domain.*"]); the longest matching glob decides a module's layer. - A composition root with many use cases: the generators emit
construct!X(a)for controllers and job handlers, so a hundred use cases are not a hundred hand-writtennewlines, and a changed constructor needs no edit at the call sites. Two ports of one type (twoClocks, say) are told apart by giving one of them as an extra argument. - When not to use this: a service with a handful of routes and no business rules gains little from four layers.
andaime new --template minimalkeeps the routes, handlers and tests in one module.
andaime reads and writes JSON with its own code (web/source/andaime/web/json.d and jsonvalue.d), not with std.json.
std.json is only used in tests, as an independent parser that checks what andaime writes. The reasons:
- Typed decoding and encoding.
std.jsonparses a tree and leaves copying it into your struct to you (and building a tree to write). andaime decodes a body straight into a DTO, with its validation attributes and one error per field, and writes a DTO straight into the response buffer. - No garbage on the hot path. A handler's return value is written into a pooled buffer, and
tests/allocfails the build if serving a request allocates. A tree-based writer cannot do that. @safeand bounded input.std.json's accessors are@system. andaime's reader is@safe, limits nesting (JsonLimits.maxDepth) and is fuzzed (tools/fuzz.sh json).- Compile time. Pulling in
std.jsonand the Phobos modules around it costs more than the 400 ms budget can spare.
Measured with tools/json_bench.sh and tools/json_load.sh (LDC -O, a 1.7 KB order with 20 items, one worker on one
core, 64 connections, 60 s). The std.json side does what a handler would have to do by hand: parse, then copy.
| andaime | std.json |
|
|---|---|---|
| Decode into a struct | 23 µs, 8.9 KB garbage | 74 µs, 37 KB garbage |
| Encode a struct | 7.4 µs, 5.9 KB garbage | 50 µs, 25 KB garbage |
| Parse to a generic tree | 42 µs, 45 KB garbage | 60 µs, 30 KB garbage |
| Compile time of one decode call | 181 ms | 373 ms |
| POST that decodes and encodes the order | 23,300 req/s, p99 3.1 ms | 7,300 req/s, p99 12.5 ms |
What this does not show: generic JsonValue trees allocate more than std.json's, so the memory gain is for typed DTOs.
Peak RSS was the same in the one-minute run (9 MB), and the long-run effect of less garbage (fewer GC pauses) is reasoned,
not measured. If most of your handlers wait on a database, JSON is a small part of each request. Numbers depend on the
machine: run the scripts twice and compare before/after, not across machines.