0169. Any domain, operation or function can be moved to its own server by naming it, and the move is tracked until the old place is retired
- Status: Accepted (Mik, 18 Nov 2026)
- Date: 2026-11-18
- Decided by: Mik asked on 18 Nov 2026 to "split out certain apis and domains into different servers that automatically keep everything updated and tracked until we can deprecate an old one", without the complexity of microservices, and gave the case: "if we realize that only the Users API needs to be scaled seperately we can dictate that as a seperate server and build out IaC or things around that decision and on the next deploy and build those will start to point to the new endpoint". A first draft added a "context" to every domain and rules to keep contexts apart. Mik turned that down the same day: "we need to simplify this … we have a default when it's not set and we should be able to move certain domains, endpoints, or functions into their own server". This record is the simpler design, approved by Mik on 18 Nov 2026 with the answers recorded at the end.
- Planning item: none (after version 1, with decisions 0163 to 0168)
Context
A single server is the cheapest and simplest thing to run, and it is what a business should start with. Later, one part needs to scale apart from the rest. In most stacks that is a rewrite, and the usual way to avoid the rewrite is to split everything into services up front, which costs more than the problem it prevents.
IDX-Studios/work-stable-api is one deployable, and its AGENTS.md rules out microservices: "one developer, one release train". That should stay true by default, with a split costing one line when it is needed.
Decision
1. One server unless you say otherwise
With nothing set, there is one server and it runs everything. There is nothing to declare and no new idea to learn.
2. To move something, name it
# duolith.yaml
server:
servers:
users:
hosts: [users] # a whole domain
search:
hosts: [jobs.searchJobs, skills.searchSkills] # single operations
drafting:
hosts: [coverLetters.generation.draft] # one step of a workflow
scale: { most: 20 }
- What can be named: a domain, one operation (an endpoint), a workflow or one of its steps, a route's server code (decision 0163), or a kind of work:
workflows(every workflow runner) andlive(every live connection, decision 0166). - **A server may set its own
scale:and its owntarget:** among the targets its code can run on. TypeScript servers can mix Bun, Node, Cloudflare and Vercel. A Rust project is Axum throughout (decision 0163). - Everything not named stays on the default server.
- Each name is a reference the build resolves (decision 0164, section 1a). A wrong name is an error at that line.
- Nothing in the domain files or the code changes. That is the whole feature.
3. What the build does with that line
Code already reaches other operations through generated symbols, never by address. So the build only changes what a symbol compiles to:
| On the same server | On different servers | |
|---|---|---|
| Calling an operation | A function call | The generated client over the internal wire of decision 0166, with the caller's deadline and a circuit breaker |
| A workflow step | Run by the runners of that server | Run by the runners of the server named, with its once-key (decision 0167) |
| An event | Delivered in process | Delivered through the pub/sub store |
| The trace | One | One: its id travels with the call |
The moved part connects to the same stores as before. No data moves and no table changes.
The build then writes the rest:
- A bundle per server, holding only what that server hosts, with the Dockerfile of decision 0163 for each.
- The infrastructure (decision 0168): the new service, its scaling, its alerts, its share of the database connections, and an identity that may reach only what its operations use.
- The addresses. Nobody types one. | Caller | How it is repointed | | --- | --- | | Browsers, native apps and outside parties (a webhook from Stripe) | They keep calling one public address. A generated routing table at the edge sends each path to the server that has it. Apps already installed need no update | | The app's other servers | The generated client reads an internal address written by the generated infrastructure. Only servers that really call the moved part are allowed to |
Security between servers.
- A moved server has no public address where the platform allows it: a service binding on Cloudflare, a private service on Google Cloud. The edge routing table is the only public way in.
- Servers prove who they are to each other with the platform's identity token, or mutual TLS elsewhere (decision 0166), or a service key (decision 0165) as the last resort. A server may call only the servers the build shows it calling.
- The user's identity travels as a short-lived token signed by the first server, never as the user's own credential.
allow:is checked again where the operation runs, so a server that is reached some other way still refuses. - The whole pipeline of decision 0165 runs on the moved server for every call, internal or not. Moving something removes no check.
One check, made only when something is moved. If a call to the moved part sits inside the caller's database transaction, it can no longer be part of that transaction. The build stops with the line and the fix: make it a workflow step with an undo (decision 0167). Nothing is asked of code that is not being moved.
4. The move is tracked until the old place is retired
duolith servers status shows every move and where it stands. The states are kept in a committed file, servers.lock.
| State | What is true | How it advances |
|---|---|---|
| Planned | The line is written. duolith servers plan shows the new service, the calls that gain a network hop with their measured latency, and the cost either way | The infrastructure diff is reviewed and applied |
| Both | The new server is up and passes the same contract tests. Both servers run the moved part: same code, same stores, so either can answer | Routing shifts a share of traffic, then all of it. Stepping back is one change, because the old server still has the code |
| Moved | All new traffic goes to the new server. The old one still counts every call that reaches it, by caller and by app build | Calls to the old place stay at zero for seven days (a setting), and no workflow run started there is still going |
| Retired | The old server no longer runs it. The build drops it from that server's bundle and rights | duolith servers retire users, which refuses while the count is not zero |
users moved to `users` on 18 Nov 0.4% of calls still reach `main`
from: app builds 1.4.2 and older (iOS), 3 workflow runs going
safe to retire: no
CI fails when a move has sat in one state past its time, so none is left half done. Putting something back is the same line removed, through the same states.
5. The same tracking retires anything old
- An operation replaced by a better one:
deprecated: { use: getUserProfile, until: 2027-03-01 }. Callers get a build warning, answers carry the standardDeprecation(RFC 9745) andSunset(RFC 8594) headers, and removal is allowed only after the date and once no caller is left. - An old system replaced piece by piece: a domain marked
served by: legacyis routed to the existing app (the Elysia adapter of decision 0164) until its replacement takes over, through the same states. This is the path for work-stable-api.
6. Strict by default, loosened only by name
Mik's rule (18 Nov 2026): "Everything should also be strict where possible and we can build off it as extensions later on to approve certain new flows or details." So a check here is an error, never a warning, and there are few of them:
| Refused | Why |
|---|---|
| A call to a moved part inside the caller's transaction | It would quietly stop being atomic (section 3) |
| Two servers that call each other in a circle | One slow server then stalls the other, and neither can be deployed first |
| A request that crosses more than two servers | Each hop adds latency and a way to fail |
| A move left in one state past its time | A half-finished move is the thing this record exists to prevent |
| Retiring while anything still calls the old place | Section 4 |
An app that needs one of these says so by name, in one place, with a reason that review can read:
server:
exceptions:
- permit: deeper calls
for: [resume.generate] # a name the build resolves
why: fans out to three scoring servers by design
An exception is narrow (one operation, one move), is listed by duolith servers status, and is the only way round a check. Anything larger, such as a new kind of flow, arrives later as an extension that is designed, recorded and tested, not as a switch.
What only informs:
duolith servers planshows each added hop and the fixed monthly cost a new server brings before its first request.duolith cost(decision 0168) says when a part would be better apart: it takes most of the CPU, or peaks at different hours. Without such evidence it says the split only adds cost, and how much.duolith devalways runs everything in one process.duolith dev --as-deployedruns the servers apart to test the wires.
Stages
servers:with whole domains: bundles, the generated internal client and identities, the edge routing table, on Google Cloud and Cloudflare first.- Single operations, workflow steps and route server code; the transaction check.
servers.lock, the states,duolith servers plan | status | retire, counts by caller and app build.deprecated:andserved by: legacyon the same tracking.
Alternatives considered
| Option | Why not |
|---|---|
| Group domains into contexts, with rules that keep contexts apart from the first day (the first draft) | Mik turned it down: a new idea and new rules for every app, to prepare for a split most parts never need. The one real hazard, a transaction across the cut, is checked when a move is made |
| A service per domain from the start | Thirty services for one developer, and thirty fixed costs |
| One program for ever, scaled as a whole | The part that needs twenty copies drags the rest with it |
| Split by hand when the time comes | Addresses, clients, infrastructure and rights all edited by hand, and nothing tracks what still calls the old place |
| A service mesh to route and secure the calls | A second system to run. The build already knows every caller and callee |
Consequences
duolith.yamlgainsserver: servers:. The domain schema gainsdeprecated:andserved by:. Nothing else in a domain file changes.- New commands:
duolith servers plan | status | retire.duolith.yamlalso gainsserver: exceptions:. New diagnostics for an unknown name inhosts:, a moved call inside a transaction, a circle, a chain past two servers, and a move left unfinished. - Splitting below a domain (one operation, one step) means two servers hold code of the same domain. Each bundle contains only what it runs, so this costs build time, not run time.
Sources
IDX-Studios/work-stable-api:AGENTS.md.- RFC 9745 (the
Deprecationheader) and RFC 8594 (theSunsetheader), confirmed to exist on 18 Nov 2026 and not reread.
Mik's answers (18 Nov 2026)
- No contexts. One server by default, and any domain, endpoint or function can be moved by naming it.
- Strict where possible, with named exceptions and later extensions.
- "Build out everything" (18 Nov 2026).