Duolith docs

0171. The server is a small core, and every target, store, engine, broker and library is a module, added by the CLI and checked on every upgrade

  • Status: Accepted (Mik, 18 Nov 2026)
  • Date: 2026-11-18
  • Decided by: Mik, 18 Nov 2026, answering the review recorded in decision 0170. His words are quoted under each point below. The design is the integrator's.
  • Planning item: docs/plan/server-roadmap.md, work package 36

Context

The review in decision 0170 named five risks. Mik answered each, and three of his answers change the design:

  • On the matrix of targets and stores: "We should be able to do this as build extensions or additional packages so later on each of these gets it's own set of templates and rules and everything independently so that each only imports the packages they need through our Duolith cli."
  • On owning every security bug: "This isn't quite true, we can utilize the same packages we are talking about to build adapters against those dependencies, the only key thing here is we define the shape that must be implemented and add in tooling for when we upgrade to warn or error before a dependency is upgraded or our core system is upgraded."
  • On the workflow engine: "This can follow the same rules … Or use our simple in house built one to do it. Workflows should be pretty important though especially if we want to utilize Pub/Sub, Kafka, Messaging Brokers and all things like that."
  • On parts with no user: "We just want to have a way to do it and build and test it locally in a way that just makes sense."
  • On scope: "This was true before the age of AI I think we can do it."

The repository already works this way on the client. Lynx sits behind an engine adapter (decisions 0007, 0045), the data core sits behind an adapter (0019), production adapters are "a package of ports" with a reference implementation each (0070), duolith scan gives every npm package a verdict per target (0073), duolith add installs by name and takes a refused package out again (0146), and duolith upgrade moves a project forward with migrations (0067). This record applies the same pattern to the server.

The words need care. Mik said "the shape that must be implemented". In domain files a shape is already a data type (decision 0164). A first draft called it a "port", after decision 0070, and Mik asked for a plainer word: "I feel like that might just cause confusion and we need something that is easy to understand a simple concept." He then chose the words used here. What an app adds is a module, which is already the glossary's word for anything installed with add. Each module has a module type (target, store, broker), and each type has one set of tests that says what a module of that type must do. A Rust module (decision 0078) is a different thing with the same root: a crate the author writes in the app's modules/ folder.

Decision

1. A core, and modules

The core is what every server has and what cannot be a choice:

  • the domain format, its resolver and checks (decision 0164);
  • the pipeline's order and its build errors (decision 0165);
  • the generated code that is compiled from the app's own domains: the router, validators, writers and each operation's pipeline. No library can provide these, because they are written per app;
  • the module types (section 2), and one set of tests for each type, its conformance suite;
  • a local module of every type, built in, so that everything runs with nothing installed (section 6).

Everything with a choice is a module: a package of one type. A module carries all of its own parts, so nothing about it lives in the core:

A module bringsExample, for @duolith/store-postgres
Its adapter codeWhat a store must do, written over the Postgres client
Its templates (decision 0165, section 4)The generated code for claiming a row with SKIP LOCKED
Its rules: build checks and diagnostics for its own settings"A personal field needs an encryption key configured"
Its piece of the duolith.yaml schemaserver: stores: postgres: { url: … }, completed in the editor
Its type and that type's version, and which outside packages and versions it was verified withtype: store@1, verified with: pg 8.11 to 8.13
Its reference page, and a pack for agents (decision 0160)

Added through the CLI. duolith add store-postgres installs it, scans it (decision 0073), runs the conformance suite of its type, and writes it into duolith.yaml and the lock file. If any of that fails it is taken out again, as decision 0146 already does for packages. A setting that needs a module the project has not added is a build error that gives the command to run.

An app carries only what it added. A server on Bun with Postgres contains no Cloudflare, Redis, Kafka or Axum code and none of their dependencies. The build report lists every module and every outside package it brought, with its licence and verdict.

2. The module types

Module typeDescribed inShips as the defaultOther first-party modules
Target (where the handler runs)Decision 0163None: an app picks onetarget-bun, target-node, target-cloudflare, target-axum, target-vercel
StoreDecision 0165, section 3Memory, in the core, for developmentstore-postgres, store-redis, store-firestore, store-cloudflare
Token verifier (the Caller step)Decision 0165, section 2An adapter over an audited library: jose in JavaScript, jsonwebtoken in RustProvider helpers (Firebase, Auth0, Clerk, Cognito) that only supply settings
SecretsDecision 0165The environment and filesGoogle Secret Manager, Cloudflare secrets
Broker (events between parts)Section 5The outbox over the app's own storebroker-pubsub, broker-kafka, broker-nats, broker-sqs, broker-rabbitmq, broker-redis-streams, broker-cloudflare-queues
Workflow engineDecision 0167, and section 5Our own, on whichever store the app usesworkflows-temporal, workflows-cloudflare, workflows-vercel, workflows-lambda
Wire (how requests and live updates travel)Decision 0166HTTP with JSON, and server-sent eventswire-binary, wire-connect, wire-websocket, wire-webtransport
TelemetryDecision 0165, RecordJSON lines and OpenTelemetryProvider exporters
Infrastructure writerDecision 0168Noneinfra-gcp, infra-cloudflare, infra-vercel, infra-compose
Load runnerDecision 0168Noneload-k6

A payment provider is not on this list. It is a service an app declares (needs: [paymentProvider]), and Plaza shows how (decision 0170).

How a default is chosen, so that "lightweight" and "safe" do not fight:

  1. Code compiled from the app's domains is ours. It cannot be a library, and it is where the speed comes from.
  2. Where a mistake is a security hole and a small, audited, widely used library exists, the default wraps that library. Token verification and password hashing are the cases. We do not write our own.
  3. Where the thing is an outside system, the adapter wraps its official client. Postgres, Redis, Kafka, Pub/Sub.
  4. Where it is small and needed everywhere, ours is the default and bigger ones are adapters. The memory store, the outbox broker, the workflow engine.

This amends decision 0163, which said the generated server has "no npm dependencies at run time". The rule is now: the core and the generated code have none. An outside package enters only through a module the app chose to add, and is listed in the build report.

3. Each module type has one set of tests, and passing them is the whole agreement

What a module type must do is written once, as tests, in spec/server/modules/<type>/. The suite includes that type's security rules. A module is verified for a version of its type when it passes, and the suite is the same whoever wrote the module.

This is what turns the matrix into independent rows:

  • A claim of support belongs to one module. Adding a tenth store touches none of the other nine.
  • In CI a module's suite runs only when that module or the tests of its type change. The cost of a change stays flat as modules are added.
  • Modules can be built in parallel by separate threads, because each has one set of tests to pass and its own folder.

It does not make the first-party set smaller. Mik's answer stands: all five targets and all five stores are built. They are built as modules.

4. Nothing is upgraded until it has been checked

modules.lock, a committed file, records for each module its version, its type and that type's version, every outside package it wraps with its exact version and integrity hash, and the conformance result it was added with.

What is being upgradedWhat happens firstIf it fails
An outside package a module wraps (pg, jose, the Kafka client)The candidate is installed in a scratch copy. The conformance and security suites of the module's type run against it with that package. duolith scan gives its verdict for the app's targetAn error naming the rule that failed. Nothing is changed
A moduleThe same, plus a check that it is built for the version of its type that the core hasThe same
The core, when what a module type must do changesEach module type has a version. duolith upgrade --check lists every added module built for the old version, and what each needs. Settings are moved by migrations (decision 0067)The upgrade does not start until each module has a release for the new version
Anything, on a scheduleduolith audit compares the lock file with a database of known vulnerabilitiesAn error in CI naming the package, the advisory and the fixed version
  • A version outside the range a module was verified with is an error, in keeping with strict by default. It is lifted when the suites pass for that version on the project's own machine, and the lock file records that local result.
  • A warning is used in one case only: a newer verified version exists. Everything else passes or fails.
  • A scheduled job proposes upgrades as pull requests with the suite's results attached, so staying current costs a review and not an afternoon.

5. Workflows and messaging

The workflow engine is a module type. Decision 0167's own engine is the default, because it needs no extra system and a new business should not have to run one. Because a flow is declared in the domain file and not written as replayed code, the same file can drive another engine:

EngineWhen an app would choose it
Ours, on the app's storeThe default. One database write per step, nothing else to run
workflows-temporalVery long or very large workflows, or a company that already runs Temporal
workflows-cloudflare, workflows-vercel, workflows-lambdaThe app lives on that platform and wants its engine's limits and billing

The conformance suite for engines is the crash test of decision 0167, section 8: kill the runner at every step and during every undo, and every run must still reach a declared end with each outside effect done once. An engine that cannot pass it is not listed.

The broker is a module type, for events between domains, servers and outside systems:

  • Declared, never typed. events:, publishes: and subscribers are in the domain file (decision 0164). A topic's name, its message type and its ordering key are derived. The ordering key is the model's identity.
  • What every broker adapter must give: at-least-once delivery, order within one key, retries with a growing wait, and a dead-letter list that duolith events list --dead shows and can replay. The generated subscriber drops an event it has already handled, so the author's code sees each one once.
  • Sent only if the change was saved. A publish goes through the outbox (decision 0165), then to the broker. That is true for every adapter.
  • A workflow can start from an event (on: paymentSucceeded), and a step can publish one.
  • Events from systems we do not own (another team's Kafka topic) are declared in a domain file with their shape and marked external. They are validated on arrival exactly as a request is. A message from a broker is untrusted input.
  • The default is the outbox over the app's own store, delivered by the runners. It needs no extra system. Pub/Sub, Kafka and the rest are modules.

6. Everything runs locally

Every module type has a local module in the core: the memory store, the in-process broker, our workflow engine with a clock a test can move, a token verifier with test keys.

  • **duolith dev and duolith test run the whole app with nothing installed**: requests, live updates, workflows, events and a split across servers (decision 0169).
  • **duolith dev --real** writes and starts a compose file with the real systems the project's modules name (Postgres, Redis, a Kafka-compatible broker, the Pub/Sub emulator, Temporal's development server) and runs against them.
  • The conformance suites run in both modes. What passes locally is what is claimed.

This is how a part with no user yet is still built properly: it has a suite, it runs on a laptop, and Plaza uses it.

7. A module a project writes for itself

Mik, 18 Nov 2026: "we should allow people to create the base template with something like 'duo module db create "<name>"' sort of like NestJS but without all the flair", "in the case a developer needs a custom one for their project".

duolith modules new store ledger

That writes two files and nothing else:

modules/ledger/
  module.yaml      # type: store@1, and the outside packages it wraps (none yet)
  index.ts         # every function a store must have, typed, each one a stub that says it is not written
  • The tests are the to-do list. duolith modules test ledger runs the tests every store must pass and lists which pass and which remain. There are no tests to write, because they belong to the module type.
  • It is used by name: store: ledger in duolith.yaml. Nothing is published and nothing is installed. A folder in modules/ with a module.yaml is one of the project's own modules. A folder there with only a Cargo.toml is a Rust module, as decision 0078 says.
  • It gets the same checks as any module: the scan, the tests of its type, and an entry in modules.lock marked as the project's own. A project's module that fails its tests is a build error when duolith.yaml uses it.
  • No flair. A module is one plain object of functions that matches its type's interface, checked by the compiler. There are no decorators, no classes to extend, no container and no registration step. In a Rust project the file is lib.rs and the interface is a trait.
  • **duolith modules new with no type lists the types** and what each is for. A project writes modules of the types the core has. A new type is a change to the framework, with its own tests, and is not something an app declares.
  • The command is written duolith here, as everywhere in these records. Its public name follows the rename of decision 0161.

7a. Modules from other people

Anyone can publish a module of any type. duolith add treats it as it treats ours: scan, conformance suite, security suite, and out again if any fails. One that passes is recorded as verified locally. Nothing reaches a generated server on trust.

Templates stay without logic (decision 0165), so a module's templates cannot run code at build time. A module's adapter code is ordinary code and is scanned as any package is.

8. What this changes in earlier records

Accepted records are not rewritten. Where this record differs, it takes over if accepted:

RecordWasNow
0163, section 4The generated server has no dependencies at run timeThe core and generated code have none. Modules may wrap outside packages
0163, 0165Targets and stores are parts of the server packageEach is a module with its own templates, rules and tests. All are still built
0165, alternatives"Depend on existing packages … Why not"Allowed inside a module, chosen by the rules of section 2. Still never a chain of middleware
0165, CallerOur own token verification on the platform's cryptographyA module type, with a default that wraps an audited library
0166Wires are settingsEach wire beyond the default is a module, turned on by the same settings
0167"There is no outside engine"Ours is the default. Other engines and brokers are modules
0168The infrastructure writer and k6 are built inEach cloud's writer and the load runner are modules

9. None of this is the developer's problem

Mik, 18 Nov 2026: "We need to be sure that these don't add complexity to the developers and we extract complexity away and give users everything in the framework that is easier than Django and Elixir but just as robust. It's about letting devs build complexity once only when required and then only ever focusing on business logic … sort of like a DSL."

Modules and lock files are how the framework is built. They are not what an app's author works with. These rules keep it that way, and each is tested.

  1. A new project works with no choices made. duolith create plaza --server asks at most two questions (where it will run, and which database) and produces a server that starts, with sign-in, a database, events and workflows working. The modules it needs are already added. Nobody has to know the word.
  2. An author writes three things. The domain file says what the system is. A method per operation or step holds the business logic. duolith.yaml says where it runs. There is no fourth kind of file: no router, no middleware list, no wiring, no client, no infrastructure files, no queue consumers.
  3. A change of mind is one line and one command. Moving from the outbox to Kafka is broker: kafka and duolith add kafka. No method changes. The build says exactly that when the line is written first: the error gives the command.
  4. Complexity is met only when it is needed, and in this order: a default, then a setting, then a typed hook, then a replaced template, then writing a module (decision 0165, section 4). Most apps stop at the second. Each step is documented as "you need this only if".
  5. Complexity is built once. A rule, a template, a workflow or a whole domain that a team has written can be shared and added to another app by name (packs, decision 0160; duolith add, decision 0146). The second app does not write it again.
  6. Every error says what to do next, with the line, the nearest right name and the command. That is already the rule for diagnostics, and it is how strictness stays easy.
  7. The vocabulary is small and plain. An author's words are domain, shape, query, command, event, workflow, step, rule and server. An author adds a module (duolith add postgres) and needs no more than that word, which the glossary already has. "Module type", "adapter" and "conformance" appear only in the pages for people who write modules.

Measured, not asserted. The guide "Your first domain on a server" is a test: a script follows it from an empty folder, and CI fails if it takes more commands, more files or more lines than the budget recorded with the guide. The same is done for "add a second server", "switch broker" and "add a payment". If a change to the framework makes any of them longer, that is a failing check.

Where Django and Phoenix are still ahead of this plan. An honest comparison, for the things a developer does most:

What a developer wantsDjangoPhoenixThis plan today
An API with validation, sign-in, rules, limits, errorsViews, forms and a REST package to assembleControllers, plugs and changesets to assembleGenerated from the domain file. Ahead
A typed client for the appNoneNoneGenerated. Ahead
Live updatesChannels, added onBuilt in, and excellentGenerated from live: true. Level, with less to write
Background work that survives a crashCelery, a second systemOban, a libraryWorkflows in the domain file. Ahead
Tables, migrations and queries from the models**The ORM and makemigrations: its best feature**Ecto schemas and migrationsMissing. A shape describes data, and the author still writes the database code by hand
A ready sign-in systemBuilt in**phx.gen.auth writes one into the app**Missing. The Caller step verifies a token. Nothing gives an app its accounts domain
An admin screen for the dataBuilt in, and a reason people choose DjangoA dashboard, no data adminMissing

The three missing rows are what "only ever focusing on business logic" still lacks. Decision 0173 designs them. Mik's condition (18 Nov 2026) is that none is required, and that an ORM in particular is never forced on an app:

  • Database code. A model can be marked as stored. A data module for the query tool the developer prefers then generates typed tables and checks the models against the real schema. Migrations stay the developer's own, in any tool. Plain create, read, update and list operations can be generated. There is no ORM at run time.
  • Starter domains. duolith add accounts copies a complete, working accounts domain into the app, which the app then owns and can change. The same for payments and notifications, taken from Plaza.
  • An admin, generated from the operations an admin may call, guarded by the app's own rules and written to the audit trail.

Alternatives considered

OptionWhy not
Keep "no dependencies" everywhere (decision 0163)We would write and own token verification, broker clients and database drivers. Mik's point holds: a checked adapter over an audited library is safer than our own copy
Depend on libraries directly, with nothing in betweenA library's change reaches every app unannounced, and replacing one is a rewrite. This is the middleware-chain world decision 0165 left
One large server package with everything in itEvery app carries every target and store, and one failing store blocks a release of the rest
Adopt an outside engine as the only workflow engineA new business would have to run or pay for it before its first user. As a module it is there when wanted
Name the interface a module implements a "port" (the first draft, after decision 0070)Mik: it "might just cause confusion"
No noun at all: "an extension of a kind" (the second draft)Mik asked again for a clear name. "Extension" was also a word the glossary says to avoid
"Adapter, with an adapter type"Familiar from Astro, SvelteKit and Rails, and offered to Mik beside "module". It would add a second word for something installed with add. "Adapter" stays the word for the code inside a module that wraps an outside library
Trust a module because it is publishedThe suites are cheap to run and are the only real evidence

Consequences

  • New work package 36, the module mechanism: the manifest, duolith add for server modules, modules.lock, the conformance runner, duolith upgrade --check and duolith audit. It comes early, since targets are the first modules.
  • Work packages 20 to 34 build their targets, stores, wires, engines and writers as module packages. The roadmap and the briefs for work packages 20 and 21 are updated with this record.
  • tools/boundaries.yaml gains a rule: only a module may import an outside package, and only its own.
  • More packages to version and publish. The lock file and the scheduled upgrade job are what keep that manageable.
  • A module can only offer what its type describes. Where an outside system can do more (Kafka's exactly-once transactions, Temporal's signals), an app reaches it through that module's own settings, and what the type demands stays small.
  • New glossary words: broker and engine for authors; module type and verified for people who write modules. "Module" is already the glossary's word for anything installed with add.
  • The guides become tests with a budget of commands, files and lines (section 9).
  • Decision 0173 follows this one, for database code, starter domains and the admin.

Mik's answers (18 Nov 2026)

  • Targets, stores, brokers and engines are modules, each with its own templates and rules, added through the CLI.
  • Outside packages are allowed inside a module, with a check before any upgrade.
  • No word "port": "we need something that is easy to understand a simple concept". After the record was accepted with "extension" and "kind", Mik asked for a clearer name still, "something like adapter or module with an implementation type idea", and chose "module, with a module type" on 18 Nov 2026. The record was reworded to match. Nothing else in it changed.
  • None of it may add complexity for the developer.
  • Database code, starter domains and an admin are wanted, with no ORM required. They are designed in decision 0173, which is still proposed.
  • A project can scaffold its own module with one command (section 7), added at Mik's request after acceptance.
  • Accepted on 18 Nov 2026.