performance-at-scale

name	performance-at-scale
description	Use when writing code that runs per item, per frame, or per event, or building a cache or lookup over a collection that can grow large.

The rule

Hot-path code meets your data at production scale, not at the handful of rows in your test fixture. A linear scan that's instant on ten items freezes the UI on a hundred thousand. The cost is invisible in the test and brutal in the field. Design the hot path for the largest realistic input before you write it, not after a user reports a freeze.

Fires when

Writing code that runs per item, per frame, or per event. Building a cache or a lookup. Iterating a collection that could grow large. Rebuilding a whole list when one entry changed.

How to apply

Before writing data-path code, ask "does this hold at the largest realistic input?"

Use O(1) lookups with an early exit — a map keyed by the thing you're asking about, so 99% of queries return immediately. Prefer incremental point updates (remove one, add one) over rebuilding the whole structure. Keep allocations and copies out of tight loops. Verbose logging in a hot loop is fine, but only after the early exit, never before it.

If the answer is "no, it won't scale", redesign before you write it, not after.

Worked example

A handler runs once per tile and scans a flat list of issues linearly to find the ones that match. With a dozen issues in the test, it's instant. In a real project the list holds four thousand issues, and every tile now costs a one-to-two second freeze. Keyed into a map by tile, each query early-exits in O(1) and the freeze is gone. The scan looked fine because the test never had enough data to make it hurt.

Red flags

Thought	Reality
"It's fast enough"	Fast on the fixture, frozen at scale.
"I'll rebuild the whole list, it's simpler"	Simpler to write, O(N) to run every time.
"Just loop and find it"	A linear scan on a hot path is a freeze waiting for data.