0168. The build knows the system, so it sizes it, prices it and generates its infrastructure
- Status: Accepted (Mik, 18 Nov 2026)
- Date: 2026-11-18
- Decided by: Mik asked on 18 Nov 2026 to "build the server in a way to optimize infra costs", to think about "the way code is scaled and how infra is built to amplify it and prevent issues", and to "allow businesses to scale as needed and keep costs low in the early stages". The design is the integrator's, approved by Mik on 18 Nov 2026 with the answers recorded at the end.
- Planning item: none (after version 1, with decisions 0163 to 0167 and 0169)
Context
A framework usually stops at the process. What it runs on, how many copies, how they scale and what that costs are written by hand somewhere else, by someone guessing. IDX-Studios/work-stable-api shows the amount of work: fifteen Terraform files and ten modules, four Cloud Run services from one image told apart by SERVER_ROLES, and sizes in config/default.json (maxInstances: 3, containerConcurrency: 20, minInstances: 1) that nothing measures and nothing ties to what the code does.
Duolith is in an unusual position. After decisions 0163 to 0167 the build knows every route and when its HTML is made, every operation and what it reads, changes and calls, every store rule, every workflow and every live model. It measures what each operation costs to run (decision 0165, section 5). That is enough to do three things nobody does by hand well: spend nothing while idle, do the least work per request, and say what a change will cost before it ships.
What the platforms charge (secondary sources, read 18 Nov 2026)
| Platform | How it bills | Starting cost | Idle |
|---|---|---|---|
| Cloudflare Workers | CPU time only, no charge for waiting or for data out | Free to 100,000 requests a day; $5 a month with 10 million requests, then $0.30 a million | Nothing runs |
| Vercel (Fluid compute) | Active CPU ($0.128 an hour in iad1) plus memory for the instance's life, plus requests and data out | Free for non-commercial use; $20 a seat a month | Scales down |
| Google Cloud Run | Per request and per CPU-second | 2 million requests, 360,000 vCPU-seconds and 180,000 GiB-seconds a month free | Scales to zero unless a minimum is set |
| AWS Lambda | Per invocation and per GB-second | 1 million requests and 400,000 GB-seconds a month free | Scales to zero; cold starts of 100 to 3,000 ms reported |
| Fly.io, Railway, a plain server | Per second while a machine runs, or a flat rate | A few dollars a month | Machines can stop and start in about a second (Fly); a plain server always costs |
One worked example from a source with a stake in the answer: 100 million requests a month at 10 ms of CPU each came to about $51 on Workers and about $275 on Vercel before memory. The sources agree on the shape and give no break-even figure: request-billed platforms win while traffic is small or comes in bursts, and a machine that stays up wins once load is steady.
Decision
1. Three rules
- Nothing is paid for while nothing is happening. Every part can scale to zero, and the defaults do.
- The cheapest request is one that never reaches the code. The build pushes every answer as far out as it is safe to hold.
- The shape of the deployment is a setting, never a rewrite. The same domains run as one small process on day one and as several scaled servers later (decision 0169).
2. Do less work per request
Each answer is served from the first place on this ladder that can hold it. All but one exist in decisions 0162 to 0165. The new one is the CDN's or the browser's copy of a query's answer.
| Where the answer comes from | Cost per request | Decided by |
|---|---|---|
| A file on the CDN (a written page) | None at the origin | Decision 0162 |
| The kept copy of a page, at the edge where the target has one (Workers, Vercel) and in the server's store elsewhere | None, or one store read | Decision 0163 |
| The CDN's or the browser's copy of a query's answer | None at the origin | New. A query that is public, or the same for everyone allowed, gets Cache-Control, an ETag and a cache tag written from its keep: and stale: rules. A command that changes: the model purges by the derived key. Nothing is typed |
A 304 Not Modified | A lookup, no body | Decision 0165 |
| The read cache in the store | One store read | Decision 0165 |
| One shared call for many identical requests | One call, however many are waiting | Decision 0165 |
| The method and the database | Full | The author's code |
Around the ladder:
- Budgets on operations. An operation may say
budget: { store calls: 3, cpu: 5ms, answer: 50kb }. Tests and the benchmark fail when it is passed. In development a request that reads the same model in a loop is reported with the line that did it. - A budget on database connections. The most instances times the pool of each can never be more than the database allows. The build works it out and refuses a setting that breaks it. This is the commonest way a scaling server takes its own database down.
- Compression and batching are already defaults (decisions 0165 and 0166), with one rule added here: a query the CDN can answer travels by itself and is left out of a batch, so batching never hides it from the cache.
3. Load is measured and simulated, never guessed
Mik asked (18 Nov 2026) for "some sort of k6s testing to understand the need for load and scaling that a user can import or set based on how things are going", able to "make recommendations to split it out", "or some other load scaling testing so we can simulate and easily measure the load". There are three parts: a traffic profile, a real run, and a simulation.
The traffic profile says what load means for this app. It is one file, load/profile.yaml, and every name in it is a reference the build resolves. It can come from three places:
| Source | How |
|---|---|
| Set by hand | The share of each operation, the usual and peak rates, and how many times larger to plan for |
| Imported from how things are going | duolith load import reads the counts and timings the Record step already emits (decision 0165), per operation and per hour, from the telemetry store or an exported file. It brings in the real mix, the real peaks and how uneven tenants are. It never brings in a request's contents |
| Imported from a recording | A browser recording (a HAR file) is mapped back to the operations it called |
From the profile the build writes named scenarios: usual, peak, growth (a multiple, ten by default), spike and soak.
A real run uses k6. duolith load run peak generates a k6 test and runs it:
- The test is generated into
generated/load/, one function per operation. Requests are made from the examples and the types in the domain files, so every input is valid and inside its limits. Commands use fresh identities so that runs do not collide. Callers are test identities made for the run. - Requests arrive at a set rate (k6's arrival-rate scenarios), whatever the server does. A server that slows down cannot hide by slowing its callers.
- Pass and fail come from the domain. Each operation's
budget:and deadline become k6 thresholds. A run that misses one fails, and so does CI. - Workflows are measured by their ends: how long a run takes to finish under load, and the age of the oldest one waiting (decision 0167).
- Results are joined. k6's summary (latency and errors seen by the caller, per operation) is joined with the server's own telemetry for the same run: CPU time, store calls, time spent waiting for a database connection, requests refused under load, breakers opened, copies running. The joined result is kept as a file, so runs can be compared and a slower release is caught.
Where a run may be aimed is strict. The target must be an environment named in duolith.yaml: duolith dev --as-deployed for the shape of the answer, a staging deploy made from the generated infrastructure for true numbers. An address typed on the command line is refused, so the tool cannot be pointed at someone else's site. Production is refused unless the app permits it by name with a ceiling on the rate.
Why k6, and what else was looked at:
| Tool | Verdict |
|---|---|
| k6 (Grafana; 2.0 released May 2026) | The first runner. Tests are JavaScript or TypeScript, which we can generate and type. Arrival-rate scenarios, thresholds, HTTP/2, gRPC and WebSocket built in, a JSON summary and OpenTelemetry output. It is widely used, and it runs from a laptop, in CI or spread over a cluster |
| Artillery | Close, with tests in YAML. Fewer built-in protocols, and its larger runs lean on its own cloud |
| Locust, Gatling | Tests in Python, or Scala and Java: a second language in the project |
wrk, oha, vegeta, autocannon | Good for hammering one address. No scenarios, mixes or checks |
| Our own load generator | Work with nothing gained over k6 |
k6 is a development tool that duolith load calls. It is never part of a generated server. The runner sits behind a small seam (a scenario in, a result file out), so another can be added later as an extension. Two limits to state: k6 has no built-in server-sent events (there is a community extension), so live updates are load-tested over WebSocket first, and it has no WebTransport.
A simulation answers "what if" without a run. duolith load simulate growth takes the cost of each operation measured in the last real run, multiplies it by a scenario, and works through the same limits the server has: requests one copy handles at once, the ceiling on copies, the database connection budget, the cache hit rates. It reports where the system gives way first, at what load, and what it would cost by then (section 5). It is arithmetic on measurements, so it is quick enough to try ten shapes in a minute, and it says which of its inputs were measured and which were assumed. A real run is what confirms it.
Sizes come from these numbers, in place of hand-typed ones:
- Requests a copy handles at once comes from the run, per target, in place of a typed 20.
- What each part scales on follows what it does. Requests scale on how many are running. Workflow runners (decision 0167) scale on the age of the oldest waiting run. Live connections (decision 0166) scale on how many are open.
- The most copies is a ceiling on the bill as well as on the load. It always has a value, and the estimate shows what it allows.
- The fewest copies is zero unless the app says otherwise. Keeping one warm is a setting, shown with its monthly price.
4. The infrastructure is generated
duolith infra generate writes what the target needs, from the same definitions as the server:
| Target | What is written |
|---|---|
| Google Cloud (first, since work-stable-api is there) | OpenTofu and Terraform: Cloud Run services and jobs, Cloud SQL with its private connection, Pub/Sub topics and push subscriptions with dead-letter queues, Cloud Tasks, Secret Manager entries, service accounts, alerts and a budget |
| Cloudflare | wrangler.jsonc: Workers, Durable Objects, queues, KV, service bindings, routes |
| Vercel | .vercel/output (decision 0163) with functions, cron and queues |
| A container host or a plain server | The Dockerfile of decision 0163, a compose file and a fly.toml |
What makes it better than hand-written files is that it is derived:
- Operations say what they need. An operation or a workflow step names the outside services and secrets it uses,
needs: [payments], in the domain file. The method is then handed exactly those, so using one that was not named is a type error. Stores need no naming: the build already knows them fromchanges:, the shapes returned and the store rules. - Least privilege comes from that. Each server's identity may reach only the stores, topics, secrets and other servers that the operations it hosts use. Nothing gets a broad role because narrowing it was tedious.
- Internal routes are never public. The wake route of decision 0167 and event subscribers are reachable only by the platform's own identity. work-stable-api keeps this as a written rule ("must only be mounted on the
v1-eventsrole"). Here the build enforces it. - Alerts and dashboards come from the telemetry names of decision 0165, so each operation, store and workflow has its error rate, latency and stuck count watched from the first deploy.
- Secrets are references, resolved by the build like every other name (decision 0164, section 1a). A secret that no code reads, or code that reads one not declared, is an error.
- The templates are replaceable (
duolith templates eject, decision 0165), and the output is checked whoever wrote it: no public database, no wildcard role, no internal route with a public address, no service without a ceiling on copies.
The files are committed and reviewed like code. Applying them stays a deliberate step by a person or a pipeline. Nothing here deploys by itself.
5. What it will cost, before and after
- **Before:
duolith cost.** Given expected traffic (requests a month and a rough mix, or last month's real numbers), it multiplies the measured cost of each operation by a dated price table and prints the monthly bill for the current target and the others, with the largest items first. It says plainly when a different shape would be cheaper: request-billed while traffic is small or bursty, a machine that stays up once it is steady. - In review: the cost of a change. CI already measures the pipeline. It adds one line to a pull request when an operation's cost moves past a set amount: "
users.searchnow makes 4 store calls where it made 1". - After: cost by operation and by tenant. The Record step adds CPU time, store calls and bytes sent to the event it already emits. A report then answers what a business needs to know while it grows: which feature and which customer the bill comes from.
- Guards. A ceiling on copies, limits per caller and per tenant (decision 0165), body and time limits, and a budget alert. A flood of requests, hostile or not, meets a limit before it meets the bill.
The price table is a file in the repository with a date and its sources. An estimate from a table older than a set age says so.
6. Recommendations, each with its evidence
duolith advise reads the latest run or simulation and the cost report, and prints what to change. Each item has four parts: what was seen, the change as a ready diff to duolith.yaml or a domain file, the expected effect on cost and latency, and the scenario to rerun to check it. Nothing is applied for you.
| What the numbers show | What it suggests |
|---|---|
| One domain or operation takes most of the CPU at peak, peaks at different hours from the rest, or slows the others when it is busy | Move it to its own server (decision 0169), with the servers: lines written out and the cost either way |
| A query is answered the same way many times | A keep: rule, or caching it at the edge, with the calls it would save |
| Requests wait for a database connection | A smaller pool per copy, a cache in front, or a read replica |
| Copies sit at the ceiling and requests are refused | A higher ceiling, with its monthly price |
| Cold starts set the slowest responses while traffic is light | One warm copy during the busy hours, with its price |
| Load is steady on a platform billed per request | An always-on shape or another target, with both bills |
| A request spends its time on slow work | Make it a workflow (decision 0167) |
| One tenant takes most of the load | A limit per tenant |
| Nothing above | "No change. A split would add $X a month and gain nothing" |
The rules are a file in the repository, each with its threshold and its reasoning, so a recommendation can be traced and argued with. They are deterministic: the same numbers give the same advice. duolith load compare then shows the run before and after a change.
7. Growing without rewriting
| Stage | Shape | Typical bill | What changes to get there |
|---|---|---|---|
| Starting | Pages on a CDN. One server that scales to zero and does everything. One small Postgres | Free tiers to a few dollars a month | Nothing: this is the default |
| Growing | The same, with a warm copy at busy hours and a read cache | Tens of dollars | Two settings |
| Steady | The server stays up. Workflow runners and live connections can move to servers of their own, scaled on their own signals | The cost of the machines, now cheaper than per-request billing | A change of target, or a servers: line (decision 0169) |
| Large | A domain or operation that needs it gets its own server (decision 0169), a read replica, more regions | Follows the load, per server | One setting per move |
Each step is a change to duolith.yaml and a generated diff of the infrastructure. Because the generated server is a standard handler with every store behind a seam, moving between targets is a change of setting as well, which is the real protection against a platform's prices.
8. Preventing the usual failures
| Failure | What prevents it |
|---|---|
| A spike takes the database down | The connection budget, load shedding (decision 0166), and slow work moved to workflows that take it at a set rate (decision 0167) |
| One customer slows everyone | Limits and fair queues per tenant |
| A deploy drops requests or strands work | Graceful drain, leases handed back, and the in-flight rules of decision 0167 |
| A deploy breaks older clients | duolith domains diff in CI (decision 0164), and the typed "update needed" answer (decision 0166) |
| A schema change breaks the copy still running | The build checks a model change against the previous release: add first, remove in a later release |
| A bad release reaches everyone | The generated rollout sends a new revision no traffic until its checks pass, then a share, then all, with one step back. This is work-stable-api's pilot revision, generated |
| The bill surprises | Ceilings, budget alerts, and the cost line in review |
Stages
- Cache headers,
ETags and purging by derived key; shared calls; the connection budget; operation budgets. - The traffic profile, generated k6 tests,
duolith load run | import | simulate | compare, measured sizes, andduolith costwith the price table. needs:in domain files;duolith infra generatefor Google Cloud, Cloudflare and Vercel, with the output checks.- Cost by operation and tenant; the cost line in review;
duolith advise; the generated rollout.
Alternatives considered
| Option | Why not |
|---|---|
| Leave infrastructure to each app | Every app repeats work-stable-api's fifteen files, with sizes nobody measured, and the privileges and private routes depend on someone remembering |
| A platform that owns the deploy (Encore's cloud, Vercel alone) | The cost and the exit are then that platform's. Generated files in the app's own repository and cloud account keep both with the business |
| Kubernetes by default | A cluster has a monthly floor and an operator before the first user. Nothing here prevents it as a later target |
| Always-warm servers for speed | Pays for idle from the first day. A warm copy is one setting when measurement says it is worth it |
| Prices fetched live from each provider | A build that needs the network and changes without a commit. A dated table is reviewable |
Consequences
- New commands:
duolith infra generate,duolith load,duolith cost,duolith advise. k6 becomes a development tool the project uses and never ships. Its licence must be checked before release: it was not stated in the pages read. New context intools/boundaries.yamlfor the infrastructure templates and the price table. - The domain schema gains
budget:andneeds:.duolith.yamlgainsscale:on a server and the list of services and secrets. There is one way to split a deployment, theservers:setting of decision 0169. This record adds no second one. needs:in the domain file extends decision 0164 (section 2, item 3), which had the implementation declare its services in code. That record is accepted and is not rewritten. The change takes effect if this record is accepted.- Decision 0163's Dockerfile and Vercel output become two of the things
infra generatewrites. - The numbers in the table above are from secondary sources, two of them written by vendors. The price table that ships must be made from each provider's own pricing pages.
Sources read on 18 Nov 2026
- Morph, "Cloudflare Workers vs Vercel" (9 Jun 2026, a vendor built on Workers): the Workers and Vercel prices and the worked bills.
- Railway, "Best serverless platforms 2026" (updated 5 Nov 2026, a vendor): the Cloud Run, Lambda, Fly and Railway figures.
- CoderCops, "Edge functions vs serverless vs containers" (6 Feb 2026): Lambda cold starts.
IDX-Studios/work-stable-api:terraform/,config/default.json,AGENTS.md.- Grafana: 'k6 2.0 is here' (12 May 2026), the k6 2.4.0 release notes and the test authoring guide.
- Not read today, described from general knowledge: Encore, Artillery, Locust, Gatling, and the details of k6's arrival-rate scenarios and thresholds.