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 brings | Example, for @duolith/store-postgres |
|---|---|
| Its adapter code | What 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 schema | server: stores: postgres: { url: … }, completed in the editor |
| Its type and that type's version, and which outside packages and versions it was verified with | type: 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 type | Described in | Ships as the default | Other first-party modules |
|---|---|---|---|
| Target (where the handler runs) | Decision 0163 | None: an app picks one | target-bun, target-node, target-cloudflare, target-axum, target-vercel |
| Store | Decision 0165, section 3 | Memory, in the core, for development | store-postgres, store-redis, store-firestore, store-cloudflare |
| Token verifier (the Caller step) | Decision 0165, section 2 | An adapter over an audited library: jose in JavaScript, jsonwebtoken in Rust | Provider helpers (Firebase, Auth0, Clerk, Cognito) that only supply settings |
| Secrets | Decision 0165 | The environment and files | Google Secret Manager, Cloudflare secrets |
| Broker (events between parts) | Section 5 | The outbox over the app's own store | broker-pubsub, broker-kafka, broker-nats, broker-sqs, broker-rabbitmq, broker-redis-streams, broker-cloudflare-queues |
| Workflow engine | Decision 0167, and section 5 | Our own, on whichever store the app uses | workflows-temporal, workflows-cloudflare, workflows-vercel, workflows-lambda |
| Wire (how requests and live updates travel) | Decision 0166 | HTTP with JSON, and server-sent events | wire-binary, wire-connect, wire-websocket, wire-webtransport |
| Telemetry | Decision 0165, Record | JSON lines and OpenTelemetry | Provider exporters |
| Infrastructure writer | Decision 0168 | None | infra-gcp, infra-cloudflare, infra-vercel, infra-compose |
| Load runner | Decision 0168 | None | load-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:
- Code compiled from the app's domains is ours. It cannot be a library, and it is where the speed comes from.
- 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.
- Where the thing is an outside system, the adapter wraps its official client. Postgres, Redis, Kafka, Pub/Sub.
- 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 upgraded | What happens first | If 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 target | An error naming the rule that failed. Nothing is changed |
| A module | The same, plus a check that it is built for the version of its type that the core has | The same |
| The core, when what a module type must do changes | Each 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 schedule | duolith audit compares the lock file with a database of known vulnerabilities | An 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:
| Engine | When an app would choose it |
|---|---|
| Ours, on the app's store | The default. One database write per step, nothing else to run |
workflows-temporal | Very long or very large workflows, or a company that already runs Temporal |
workflows-cloudflare, workflows-vercel, workflows-lambda | The 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 --deadshows 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 devandduolith testrun 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 ledgerruns 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: ledgerinduolith.yaml. Nothing is published and nothing is installed. A folder inmodules/with amodule.yamlis one of the project's own modules. A folder there with only aCargo.tomlis 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.lockmarked as the project's own. A project's module that fails its tests is a build error whenduolith.yamluses 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.rsand the interface is a trait. - **
duolith modules newwith 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
duolithhere, 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:
| Record | Was | Now |
|---|---|---|
| 0163, section 4 | The generated server has no dependencies at run time | The core and generated code have none. Modules may wrap outside packages |
| 0163, 0165 | Targets and stores are parts of the server package | Each 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, Caller | Our own token verification on the platform's cryptography | A module type, with a default that wraps an audited library |
| 0166 | Wires are settings | Each 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 |
| 0168 | The infrastructure writer and k6 are built in | Each 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.
- A new project works with no choices made.
duolith create plaza --serverasks 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. - An author writes three things. The domain file says what the system is. A method per operation or step holds the business logic.
duolith.yamlsays 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. - A change of mind is one line and one command. Moving from the outbox to Kafka is
broker: kafkaandduolith add kafka. No method changes. The build says exactly that when the line is written first: the error gives the command. - 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".
- 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. - 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.
- 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 wants | Django | Phoenix | This plan today |
|---|---|---|---|
| An API with validation, sign-in, rules, limits, errors | Views, forms and a REST package to assemble | Controllers, plugs and changesets to assemble | Generated from the domain file. Ahead |
| A typed client for the app | None | None | Generated. Ahead |
| Live updates | Channels, added on | Built in, and excellent | Generated from live: true. Level, with less to write |
| Background work that survives a crash | Celery, a second system | Oban, a library | Workflows in the domain file. Ahead |
| Tables, migrations and queries from the models | **The ORM and makemigrations: its best feature** | Ecto schemas and migrations | Missing. A shape describes data, and the author still writes the database code by hand |
| A ready sign-in system | Built 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 data | Built in, and a reason people choose Django | A dashboard, no data admin | Missing |
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 accountscopies a complete, working accounts domain into the app, which the app then owns and can change. The same forpaymentsandnotifications, 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
| Option | Why 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 between | A 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 it | Every app carries every target and store, and one failing store blocks a release of the rest |
| Adopt an outside engine as the only workflow engine | A 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 published | The suites are cheap to run and are the only real evidence |
Consequences
- New work package 36, the module mechanism: the manifest,
duolith addfor server modules,modules.lock, the conformance runner,duolith upgrade --checkandduolith 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.yamlgains 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.