Watch an AI coding assistant design a backend and you notice something. It produces a clean architecture in seconds, the code runs, and nowhere in that confident output does it tell you the design caps out at 12,000 users, that the single Postgres is the wall, or that the egress bill is four figures a month. It never did the back-of-envelope math, because nobody made it, and it would not have been grounded if it had.
The wrapper trap
The obvious fix is to ask the model: is this architecture good? That gets you fluent, generic, ungrounded advice. Frontier models are mediocre at capacity estimation and small local ones are worse, so the naive build is a wrapper that returns plausible-sounding nonsense with total confidence.
I wanted the opposite. In Brok, the model never reasons about the system. Deterministic code does, against real cited numbers. The calling assistant is allowed exactly one job: turn your prose or your docker-compose into a structured list of components. From there no model touches the judgment.
If the intelligence is in the data and the arithmetic, the tool cannot hallucinate a verdict. That is the entire design.
What it actually does
You point Brok at an architecture and tell it the scale you expect. It gives you the bottleneck, the user count the design holds, a latency warning when a component is past its queueing knee, a rough monthly bill, the trade-offs each component is making, and the whole thing phrased in a dry voice. A real card looks like this:
BROK: CUTTING IT CLOSE
orders-db is running 85% hot. Under the cap, sure, but past the knee,
so queueing already puts latency near 6.7x idle. Real headroom is about
700,000 users, not 1,000,000. shard it by a high cardinality key, or put
a write queue in front.
Receipts:
api: ~1,400/sec vs ~2,000 ceiling
orders-db: ~850/sec vs ~1,000 ceiling
THE TRADE-OFFS YOU ARE MAKING:
relational_db: fine under about 500 writes/sec, one machine of data.
cost: a single point of failure, writes cap near 1k/sec. outgrow it:
read-heavy add replicas, write-bound shard by a high cardinality key.
WHAT IT COSTS (rough monthly):
compute $180, egress $1,240, total $1,420.
about 13,800 GB/month leaving the system, order-of-magnitude.Every number traces to a cited source. Postgres at roughly 1,000 writes a second, Redis at roughly 100,000 ops a second, an app instance in the low thousands of requests a second. The conservative low end of each range is what the verdict uses. Hand Brok a component it has no cited number for and it says so instead of guessing.
It is benchmarked, and the benchmark is honest
Brok scores 100 percent on bottleneck accuracy and capacity-within-2x on a curated golden set, with zero off-by-100x misses. That sounds like a brag, so here is the honest framing: the benchmark checks that the engine is internally consistent with its own cited ceilings, that it abstains on unknowns, and that it does not cry wolf on a hobby app. Real systems like Instagram, which sharded for data volume rather than throughput, are included as documented out-of-model cases and excluded from scoring, because a single-instance throughput model has no business judging them. The claim is precise: consistent, well-behaved, and honest about what it cannot see. It is not a claim that it predicts every real-world scaling wall.
The lenses, and what I refused to build
The first version only did capacity, and it felt thin. The realization that fixed it: Claude Code will not write a blocking socket inside an async handler, it knows the syntax cold. What it does not reliably know are the quantitative trade-offs. So the lenses are about feeding it the judgment it lacks, not the syntax it already has.
- Trade-offs. A curated, cited table: when each component is fine, what it costs you, and the move when you outgrow it. Shard versus add replicas, why a CDN is useless for writes, when a cache is actually earning its keep.
- Latency. Naive capacity says "fine until 100 percent." Queueing theory says no: latency climbs as
1 / (1 - utilization), so a component at 80 percent load is already paying about 5x its idle latency. Brok now flags the knee at around 70 percent. But it reports a multiplier, never a millisecond, because an absolute latency needs per-handler compute time and cache hit rates I cannot know. The honest refusal is the feature. - Cost. A mid-tier compute table plus egress computed from the traffic Brok already has. Egress is the one that surprises people. In one example, compute was 260 dollars a month and egress was 7,700. Order of magnitude, assumptions stated, not a billing forecast.
What I deliberately did not build matters as much as what I did. No absolute latency in milliseconds. No Universal Scalability Law curve with coefficients I would have to invent. No memory model. Each of those needs a number I could only fabricate, and fabricating numbers is the exact thing this tool exists to avoid.
Why it is named Brok
Brok is the blunt, foul-mouthed dwarf blacksmith from God of War, and Brokkr from Norse myth long before that. He forges the best weapons in the nine realms and has no patience for sloppy work. In Ragnarok he dies, and it lands harder than almost any death in the game, because he was the most human character in it. Naming a tool that respects work which holds, and has no patience for the lazy kind, after him is a small tribute to a dwarf who deserved better.
To be clear about the line: the name is Norse myth and public domain, the dry bluntness is the homage, and every line of the voice is my own writing. Nothing is copied from the game. He is named Sindri's brother in the lore, and Sindri was this project's first name, until Brok turned out to be the funnier, blunter one. Fitting.
When it is worth it, and when it isn't
This is a back-of-envelope sanity check, the one you would otherwise skip. Be honest about the fit:
- Worth it while designing or scaling, or when an assistant has just drafted an architecture and you want a grounded second opinion before you commit to it.
- Not worth it as a load test, a billing forecast, or production capacity planning. It is single-instance throughput math with an order-of-magnitude bar. It will not catch a missing index or a hot partition.
Knowing the difference, and saying it in the README instead of hiding it, is the point.
The code
It is free, runs locally, needs no API key, and contains no model on the critical path, so it gives the same answer every time. The engine, the benchmark, the voice, and every reproducible test are here:
github.com/RudraDudhat2509/brok
Rudra, doing the napkin math the model skips.