Umit Unal

ScaleSense: Design for Scale Before You Build

“100K users” is not a capacity plan—or even a workload.

One hundred thousand registered users might produce 20 requests per second or 20,000. They might read tiny cached objects, run expensive analytical queries, upload large files, or arrive together during a flash sale. The same user count can describe systems with completely different CPU, memory, storage, network, latency, and failure requirements.

Yet architecture conversations often jump directly from a product number to a technology. We expect 100K users, so do we need Kubernetes? Traffic will grow, so should we add Kafka? The database might become slow, so should Redis sit in front of it?

Those technologies may be the right answer. But the user count does not prove it. Neither does QPS by itself.

That gap is why I built ScaleSense, an evidence-driven system design and capacity-planning skill for Codex.

Why I Built ScaleSense

While using coding agents for architecture work, I kept seeing the same jump: a demand estimate would turn into a stack choice before the work behind that estimate had been described. “100K users” became a reason for Kafka. A peak-QPS forecast became a replica count without any CPU profile or memory measurement. The answer looked complete, but the decision-changing inputs were still missing.

That bothered me because coding agents make implementation fast. A plausible diagram can become code before anyone asks what the peak actually looks like, which dependency is the binding constraint, or what happens during failure. I built ScaleSense because I wanted Codex to pause at that point and ask for the missing math, assumptions, and measurements.

ScaleSense starts with product demand and follows the work:

product demand
  -> workload, concurrency, and data growth
  -> latency and availability budgets
  -> component resource demand and failure behavior
  -> candidate design
  -> representative benchmark or production evidence
  -> validated decision and evolution trigger

The result is not simply “use the simplest stack.” The goal is the least complex option that satisfies the real constraints. Sometimes that is a single service and PostgreSQL. Sometimes replay, isolation, throughput, ownership, or recovery requirements justify Kafka, Redis, another datastore, or a new service boundary.

Complexity should not be rejected reflexively. It should earn its place.

Demand Is the Beginning, Not the Allocation

Suppose an API must sustain 900 requests per second. That still does not tell us how many replicas to run.

If production-shaped profiling measures 12 milliseconds of CPU per request, the foreground CPU demand is:

900 requests/second x 0.012 CPU-seconds/request
= 10.8 core-seconds/second

At a 65% utilization target, that becomes about 16.6 cores before N+1 capacity, rollout headroom, background work, and failure handling. Memory still depends on measured working set and concurrency. Replica count still depends on the tested capacity of a healthy instance, failure domains, startup time, and the latency objective.

The traffic forecast is an input. Profiling and a representative benchmark turn it into an allocation.

This distinction is central to ScaleSense: it can calculate workload and expose the missing evidence, but it will not invent exact CPU, RAM, partition, or replica numbers from users or QPS alone.

What Shopify’s Black Friday Scale Teaches Us

To see whether the method still held up beyond a small API calculation, I applied it to Shopify’s public Black Friday Cyber Monday numbers. The repository now includes a Shopify-inspired Black Friday capacity review. It is not a reconstruction of Shopify’s private architecture, and it does not suggest copying Shopify’s stack. It applies the ScaleSense method to public figures and engineering articles. It does not imply that Shopify uses or endorses ScaleSense.

Shopify’s published 2025 BFCM results reported peak traffic of 489 million edge requests per minute, more than 117 million app-server requests per minute, and 31.8 million API requests per minute. Converted carefully, that is:

  • 8.15 million edge requests per second
  • more than 1.95 million app-server requests per second
  • 530,000 API requests per second

The important lesson is not the size of those numbers. It is that they describe different layers and cannot be added together. An edge request may terminate before reaching an application server. One application request may fan out into multiple database queries, cache operations, events, and retries.

Shopify describes forecasting demand and then validating the forecast with full-scale exercises. The detail that stayed with me was that adding replicas increased connection pressure before application traffic even arrived. More application capacity had made a dependency constraint worse.

That is what a capacity plan needs to expose. It maps customer journeys to component work, quotas, connections, failure modes, and tested limits instead of stopping at one global QPS number. Shopify’s capacity-planning account also shows why a spreadsheet is a starting hypothesis, not the final proof. The traffic figures above come from its official 2025 BFCM results.

The exercise also made another problem obvious: one request can fan out into queries, cache operations, events, and retries. Once that happens, database roles and failure semantics become part of the capacity model. That became the focus of v0.2.0.

Why v0.2.0 Focuses on Database Decisions

I did not want a database workflow that asks only, “PostgreSQL or MongoDB?” A product name is usually the end of the reasoning, not the beginning.

ScaleSense v0.2.0 starts with harder questions:

  • Why does the current design truly fall short?
  • Can a smaller correction solve the measured problem first?
  • Which component owns each business invariant?
  • What happens when acknowledged data is lost or two systems disagree?
  • Which production-shaped benchmark justifies the decision?
  • How will the migration roll back?

Putting Redis in front of PostgreSQL, for example, is not just “adding a cache.” The review names PostgreSQL as the source of truth, Redis as derived state, the source used to rebuild it, and the expected behavior during a cold start. If Redis holds the only copy, ScaleSense stops treating it as a cache; persistence, backup, and restore are now part of the database design.

Kafka gets the same treatment. If it is transport, the review asks what happens when a consumer falls behind. If it becomes authoritative event history, retention, ordering, replay, schema evolution, and catastrophic rebuild are no longer optional details.

ScaleSense does not integrate with PostgreSQL, Redis, or Kafka. It makes their responsibilities explicit, compares them with the no-change option and smaller fixes, and asks for a production-shaped benchmark before approving the move.

What I Learned Building It

The hardest part was deciding what the workflow could calculate and what it could not know. Demand can be translated into CPU time, bytes, IOPS, connections, retries, and retained data. Exact allocation still needs evidence from the target environment. Making that boundary explicit improved the answers more than adding another formula.

I also changed how I think about simplicity. Adding a system without evidence is expensive, but refusing one after the current design has failed a measured requirement is not simpler. Team experience and an existing platform can make a specialized component the lower-risk choice.

The most useful lesson was that every recommendation needs a condition that can prove it wrong. “Use PostgreSQL” is an opinion. “Revisit this when the representative benchmark misses the p99 target under the required failure scenario” is a decision a team can operate. It can stay simple today without pretending today will last forever.

Try ScaleSense

Install the pinned public release with the Codex CLI:

codex plugin marketplace add umit/scalesense --ref v0.2.0
codex plugin add scalesense@scalesense
codex plugin list --json

Start a new Codex session after installation. Then ask naturally, or select one of the four workflows explicitly:

$scalesense review Review this design before implementation.

$scalesense design Design this service from the product and failure
requirements before choosing the stack.

$scalesense estimate Turn this demand forecast into workload and identify
the measurements required for resource sizing.

$scalesense challenge We expect 100K users, so we need Kafka and Redis.
Test that claim and define the evidence that would justify each technology.

$scalesense is a Codex skill mention, not a shell command.

ScaleSense is an MIT-licensed, instruction-only plugin. It has no backend or telemetry, and its estimates are models—not measurements or guarantees. You still need profiling, load tests, security review, and an engineer who owns the decision.

I built it to make assumptions and failure behavior visible before a confident diagram becomes code. If you try it on a real design, I would like to hear where it helps and where it gets in the way.