DEV Community: Sergey

Virtualization Isn't Enough: Making Long Lists Actually Fast

Sergey — Sun, 25 Oct 2026 13:18:13 +0000

Imagine a chat with a hundred thousand messages. Twenty of them fit on the screen.

If you create a DOM element for every message, the browser has to keep track of all hundred thousand elements, even though the user sees only a small part of the history. Virtualization solves this problem: it keeps the visible messages and a small buffer around them in the DOM, and represents the rest of the space with an empty block called a spacer.

The screen still feels like a long history, but the browser doesn't have to render every message at once.

Virtualization doesn't solve every problem

To show the right messages, the component has to figure out which rows fall inside the viewport. If every row has the same height, that's easy:

const index = Math.floor(scrollTop / rowHeight)

But chat messages vary. One takes up two lines, another takes twenty. An image may load after the text, and resizing the window changes how lines wrap. A message's height isn't known precisely until it has been rendered.

So a virtual list has to solve three related but distinct problems:

Quickly find the row that corresponds to a given scroll position.
Update a row's height once its actual size becomes known.
Keep the message being read in place when the heights of rows above it change.

You can find rows quickly and still get scroll jumps. You can preserve the reading position and still spend too much time computing coordinates. A reliable list needs both solutions.

How virtualization works

A virtual list usually contains a full-height spacer and a separate container with the visible rows. The container is offset by the distance from the top of the list to the first rendered row.

History:  [ hidden rows ][──── viewport ────][ hidden rows ]

DOM:                     [visible + buffer]

Spacer:   ···············│                  │··············
                         ↑ window start

The visible range is often extended by a few rows above and below. This buffer is called overscan: it helps avoid blank areas during fast scrolling.

In simplified form, the markup might look like this:

<div style={{ height: totalHeight }}>
  <div style={{ transform: `translateY(${top}px)` }}>
    {visibleRows}
  </div>
</div>

Here, totalHeight is the combined height of the entire history, and top is the coordinate where the first rendered row begins. A real component also has to handle container positioning, row measurement, and size updates.

If every row's height is known and fixed, finding the window is easy. With variable heights, it gets harder: you need to quickly determine which row contains scrollTop, and then the coordinate where the window starts.

Let's start with a simple solution and add complexity only when we hit a concrete limitation.

Step 1. Linear scan: simple while the list is small

The most obvious approach is to add up message heights from the top of the list until the running total reaches scrollTop.

function findRowLinear(heights: number[], scrollTop: number) {
  let top = 0

  for (let i = 0; i < heights.length; i++) {
    const bottom = top + heights[i]

    if (bottom > scrollTop) {
      return { index: i, top }
    }

    top = bottom
  }

  // The list is empty, or the coordinate lies beyond the end of the list.
  return { index: -1, top }
}

The algorithm checks rows one by one. If the user is near the top of the list, the search finishes quickly. If they've scrolled almost to the end of the chat, it has to check nearly all hundred thousand messages.

In the worst case, lookup time is proportional to the number of rows: O(n).

Start of list                                        End
[1][2][3][4][5][6][7][8][9][10] ... [99991] ... [100000]
 └───────────────────────────────────────────────→ search

The problem isn't the number of DOM elements: virtualization has already capped that. The problem is that computing the visible window still walks the entire list to find a row.

You can cut some overhead by storing heights in a Float64Array, maintaining a running total height, and not recomputing the same values multiple times in a single pass. These are useful optimizations, but they don't change the asymptotic complexity: lookup still takes O(n).

Takeaway: a linear scan is a good simple starting implementation and a baseline for comparison. A large list needs a way to find a row without visiting every row before it.

Step 2. Prefix sums: fast lookup, expensive updates

A row's height is also the distance to the next row. If you add up the heights of all rows before row k, you get the coordinate of its top edge.

For example, for heights [40, 60, 30, 70], the boundary coordinates are:

Rows:        [   40   ][     60     ][  30  ][      70      ]
Boundaries:  0        40            100    130             200

Let's build a prefix sum array:

const heights = [40, 60, 30, 70]
const prefix = [0, 40, 100, 130, 200]

prefix[k] is the total height of the first k rows. So you can get the start coordinate of a row in O(1), and since the boundary coordinates are sorted, you can find a row with binary search in O(log n).

Say scrollTop = 115. The largest boundary that doesn't exceed 115 is 100. So the visible area starts in the third row (counting from one), 15 pixels below its top edge.

But now imagine that, once measured, the first row turns out to be 10 pixels taller than estimated:

Before: [0, 40, 100, 130, 200]
After:  [0, 50, 110, 140, 210]
             └── every later boundary shifted

To update the prefix array, you have to change every value after it. In the worst case, a single measurement costs O(n).

Chat message heights are refined after rendering and can change again when an image loads or the window is resized. So updates aren't an exception — they're a normal part of the component's work.

Takeaway: prefix sums work well when data rarely changes. A list with frequent measurements needs a structure that updates only the affected sums.

Step 3. Fenwick tree: fast queries and point updates

A Fenwick tree doesn't store every prefix sum; it stores a set of partial sums. Each node covers a specific range of elements. To get the sum of the first k rows, you add up just a few of these ranges.

For eight rows, the node ranges look like this. Tree indices start at one:

Node:      1     2      3      4       5      6       7       8
Range:    [1]  [1–2]   [3]   [1–4]    [5]   [5–6]    [7]   [1–8]

For example, to get the sum of the first seven rows, you only need nodes 7, 6, and 4:

7 → 6 → 4 → 0

[7] + [5–6] + [1–4] = sum of rows [1–7]

Instead of seven additions, you do three. For larger arrays, the number of steps grows logarithmically.

Why do the jumps work this way? The length of node i's range is i & -i — the value of the lowest set bit of i. For example, 6 in binary is 110, and its lowest set bit is 2. So node 6 stores the sum of elements 5 and 6.

Updating the height of a single row

If row 6's height changes, you only need to update the nodes whose ranges include that row. For eight elements, the update path looks like this:

Update row 6:
6 → 8 → done

We store the raw heights separately so we can compute the difference between the new and old values.

function prefixSum(count: number) {
  let sum = 0

  for (let i = count; i > 0; i -= i & -i) {
    sum += tree[i]
  }

  return sum
}

function setHeight(index: number, nextHeight: number) {
  const delta = nextHeight - heights[index]
  heights[index] = nextHeight

  for (let i = index + 1; i <= heights.length; i += i & -i) {
    tree[i] += delta
  }
}

Here, index is the zero-based row index, while the tree's internal indices start at one. The code assumes tree has already been built and holds correct partial sums.

Both the prefix query and the point update take O(log n). Unlike a prefix sum array, a Fenwick tree doesn't require updating every subsequent prefix sum when a row's height changes.

Finding a row by coordinate

Finding the sum of the first k elements and finding an index for a given sum are different problems. For the second one, you can do a binary lifting search over the Fenwick tree: check powers of two from largest to smallest, and take the next range if its sum fits into the remaining offset.

function findByOffset(offset: number) {
  if (heights.length === 0) return -1

  const total = prefixSum(heights.length)
  if (offset >= total) return heights.length - 1
  if (offset <= 0) return 0

  let position = 0
  let remaining = offset
  let step = 1

  while (step * 2 <= heights.length) step *= 2

  for (; step > 0; step >>= 1) {
    const next = position + step

    if (next <= heights.length && tree[next] <= remaining) {
      position = next
      remaining -= tree[next]
    }
  }

  // position is the number of rows lying entirely before offset.
  // With positive heights, this is the zero-based row index.
  return Math.min(position, heights.length - 1)
}

This search assumes heights are non-negative, the tree is built correctly, and offset is given in list coordinates. In a production component, the boundaries need to match your chosen semantics: for example, which row counts as active when the coordinate lands exactly on a row's bottom edge. An empty list and coordinates near the end also need explicit handling.

Where a Fenwick tree stops being convenient

A Fenwick tree is great when heights are updated one at a time. But suppose the app switches display modes and needs to add the same amount to the height of an entire range of rows at once.

If you perform a hundred thousand individual updates, the total work is O(n log n). The plain Fenwick tree in this implementation can't apply a single operation to an arbitrary range in O(log n).

Takeaway: if the main workload is coordinate lookups and individual height changes, a Fenwick tree offers a good balance of speed and simplicity. If you need frequent updates to whole ranges, consider a segment tree.

Step 4. Segment tree: range updates in O(log n)

A segment tree divides an array into ranges. The root represents the whole list, its children represent the left and right halves, and the leaves represent individual rows. Each node stores the total height of its range.

                        [1–8]
                 sum of all eight rows
                    /             \
                 [1–4]             [5–8]
                /     \           /     \
             [1–2]   [3–4]      [5–6]   [7–8]

To find the row at a given coordinate, compare the coordinate with the total height of the left subtree. If it's smaller, the target row is on the left. Otherwise, subtract the left half's sum and go right. Each step halves the range, so lookup takes O(log n).

Lazy updates

Now imagine you need to add 5 pixels to the height of every row in the range [1–8].

A naive approach would update all eight leaves. But the root already represents the entire range. It's enough to increase its sum by 8 × 5 and record the addition in a pending field to propagate later.

Before:                After adding +5:

       [1–8]                  [1–8, pending +5]
      /     \                 /               \
  [1–4]   [5–8]           children not updated yet

This technique is called lazy propagation. The node's sum already reflects the change, but its children haven't been updated yet. When the algorithm needs to descend to the children, it first pushes the accumulated addition down to them.

In simplified form, applying a change looks like this:

function apply(node: number, left: number, right: number, delta: number) {
  sum[node] += (right - left + 1) * delta
  pending[node] += delta
}

A range update follows three rules:

If the node doesn't overlap the target range, skip it.
If the node lies entirely inside the range, update its sum and pending addition without descending to the leaves.
If the node is only partially covered, push the pending addition down to its children, update the relevant subranges, and recompute the node's sum.

function addRange(
  node: number,
  left: number,
  right: number,
  from: number,
  to: number,
  delta: number
) {
  if (to < left || right < from) return

  if (from <= left && right <= to) {
    apply(node, left, right, delta)
    return
  }

  push(node, left, right)

  const middle = Math.floor((left + right) / 2)

  addRange(node * 2, left, middle, from, to, delta)
  addRange(node * 2 + 1, middle + 1, right, from, to, delta)

  sum[node] = sum[node * 2] + sum[node * 2 + 1]
}

This snippet illustrates the core idea. A full implementation should also include building the tree, bounds checking, handling an empty list, and a push function that passes the pending change down to the children and resets the current node's pending.

A key invariant: sum[node] already accounts for pending[node], but the children's sums may not include that addition yet. If you forget to push it down before descending, queries will start returning wrong sums.

For any range, the tree visits only a bounded number of nodes per level, so adding to a range takes O(log n). A point height update also takes O(log n).

There's an important caveat, though: this advantage applies only when a single operation can be applied uniformly across the range — for example, adding the same amount to every row. If resizing the window makes each message wrap differently and end up with its own new height, the tree doesn't spare you from measuring those rows. It speeds up storing and updating the values, but it doesn't eliminate the work needed to obtain them.

Takeaway: a segment tree is justified when the app genuinely needs frequent range updates. If only individual rows change, a Fenwick tree is usually simpler.

Comparing the structures on the same set of operations

Let's put the properties of these solutions into a single table. Here, "find a row by coordinate" means locating a row at a given coordinate while accounting for heights, and "add a value to a range" means applying the same addition to every row in a range.

Structure	Find a row by coordinate	Update a single height	Add a value to a range
Height array with linear scan	O(n)	O(1)	O(n)
Prefix sum array	O(log n)	O(n)	O(n)
Fenwick tree	O(log n)	O(log n)	O(n log n) via individual updates
Segment tree with lazy propagation	O(log n)	O(log n)	O(log n)

These complexities describe algorithmic work, not guaranteed time in milliseconds. On a real device, results depend on the implementation, available memory, the browser, the number of measurements, and the work performed by the UI itself.

What the measurements show

In the original experiment with 100,000 rows, finding the window near the end of the history took about 50 ms with the naive scan and about 3–4 µs with the indexed structures. Updating the height of a row near the start of the history took about 387 µs with prefix sums and about 2 µs with either the Fenwick tree or the segment tree. Adding a value to the entire range took about 7.6 ms with the Fenwick tree and about 2 µs with the segment tree.

These are results from a specific microbenchmark, not universal properties of the data structures. Before publishing numbers like these, you should include the benchmark code and specify the runtime environment, the number of iterations, the warm-up method, and how the final values were calculated. Without that information, the numbers are hard to verify independently.

A separate scrolling run in headless Chrome with a 6× CPU slowdown produced the following results:

Step	p95 frame time	Frames over 20 ms
Naive scan	248 ms	28 of 29
Height array	24 ms	28 of 312
Prefix sums	18 ms	0 of 455
Fenwick tree	18 ms	5 of 425
Segment tree	18 ms	6 of 448

These numbers are also specific to the test environment. They show that switching from a linear search to an indexed data structure significantly improved performance in this run, while switching between indexed structures had little effect on the p95 frame time.

Why? Once one bottleneck is removed, another part of the UI can become the limiting factor: row measurement, React component updates, layout, or painting. Speeding up the data structure doesn't necessarily speed up the whole frame by the same factor.

Practical takeaway from the benchmark: choose a more complex structure for the operations it actually speeds up. Don't adopt a segment tree just hoping it will automatically make scrolling smoother.

Correct sums don't guarantee correct scrolling

Even with a fast height index, a virtual list still has another problem: the height of an off-screen row may be unknown.

Until a row is rendered, the component uses an estimate. When the row appears, ResizeObserver lets you get its actual size and update the height index.

But if a row above the viewport becomes 12 pixels taller, the coordinates of every row after it also increase by 12 pixels. Without compensation, the user sees a jump: the message they were reading moves.

Height of a row above viewport:  +12 px
Scroll position:                 +12 px
Visible message:                 stays in place

If the height of a row above the anchor grows by delta and the reading position must be preserved, the scroll position is usually adjusted by the same amount. Keep the sign in mind: if the row got shorter, the adjustment is negative.

Preserve an anchor, not just a pixel count

For reliable compensation, it helps to remember the first visible row and the offset within it. After heights change, the component recomputes that row's coordinate and restores the previous offset within it.

This is more robust than blindly adding every change to scrollTop: several rows may change during a single cycle, the user may scroll manually, and measurements may arrive in a different order from the one in which they were requested.

The same principle applies when loading older messages at the top. If rows are prepended before the current history, you need to keep the anchor message in place. First update the total height calculation and the spacer size, and only then restore the scroll position. Otherwise, the new scrollTop value may exceed the old content height, and the browser will clamp it.

The browser may also try to preserve the scroll position automatically through scroll anchoring. If your component manages the anchor itself, check how it interacts with the CSS overflow-anchor property so the browser and the app don't both compensate for the same change.

There's also a special case: the user is at the bottom of the chat. In that case, you usually want to keep the view anchored to the bottom rather than preserve the position of a specific message — provided that this matches your product's intended behavior. If the user is reading older messages, new messages shouldn't force them back to the bottom.

A practical sequence of steps

Don't start with the most complex structure. Evolve the solution as real limitations surface.

Implement virtualization. Render only the visible rows and a small buffer around them.
Start with a simple height model. Verify that coordinates and edge cases are correct.
Measure performance. Make sure that row lookup or height updates are actually the bottleneck.
Choose a structure that fits your update pattern. Prefix sums suit data that rarely changes, a Fenwick tree suits frequent point updates, and a segment tree suits frequent range updates.
Solve scroll jumps separately. Keep a reading anchor and compensate for height changes correctly.
Measure again. Compare not only the data-structure microbenchmark but also the behavior of the full UI.

A good virtual list is more than just a small number of DOM nodes. It computes coordinates quickly, handles variable heights correctly, and keeps the reader's place when content changes.

The most complex structure isn't always the most useful one. The best solution is the one that removes the measured bottleneck, keeps the UI behaving correctly, and doesn't add unnecessary complexity.

Code for this article: godfreyd/virtual-list-fenwick.

From 100 Million Events to 1,200 Pixels: Engineering a Data-Heavy Dashboard

Sergey — Mon, 19 Oct 2026 13:28:34 +0000

Your dashboard has a chart that is about 1,200 pixels wide.

Behind it sits a table that grows by a few million rows a day. Somebody opens the page, picks "last 30 days", and expects to see request volume, cost, error rate and p95 latency — immediately, and again a second later when they drag across a spike to zoom in.

Somewhere between those two facts — millions of rows on one side, a few hundred visible values on the other — your architecture decides where the data gets smaller. Usually nobody makes that decision on purpose. It happens in the first version of the API, and it stays there until the dashboard gets slow.

This article is about making that decision deliberately. The question is simple to state:

How do we get from a hundred million raw events to the few hundred values the UI actually needs?

And the claim I want to back with measurements rather than opinions:

Performance of a data-heavy frontend starts long before React.

By the time a component renders, almost every important decision has already been made: what was stored, what was scanned, what was aggregated, what crossed the network, and what the browser had to do with it. Drawing 730 points is easy. Getting to the right 730 points is the actual engineering problem — and, as we'll see, a correctness problem as much as a speed problem.

The case study: an AI SaaS usage dashboard

To keep things concrete, imagine a product built on top of large language models. Every model call produces one event:

Field	Example
`ts`	`2025-06-12T14:03:27.481920Z`
`user_id`	`u_0004211`
`model`, `provider`	`atlas-mini`, `northwind`
`tokens_input`, `tokens_output`	`412`, `187`
`latency_ms`	`1269`
`cost_usd`	`174` (micro-dollars)
`country`	`DE`
`status`	`ok`, `error` or `timeout`

The product team wants the usual dashboard: requests over time, cost, tokens, error rate, latency percentiles, breakdowns by model, provider, country and user, filters on all of them, and zooming from a year down to an hour.

None of this is specific to AI. Replace "model call" with "HTTP request", "payment" or "sensor reading", and you have an observability, fintech or IoT dashboard: a high-volume, append-only stream of events and a UI that needs a compact summary of it. LLM usage is just a convenient example with interesting metrics — money, tokens, heavy-tailed latency — and plenty of dimensions to slice by.

The path every number travels

Every value on the chart takes the same route:

Each arrow is a place where the data can get smaller — or not. The interesting question is where the reduction happens, because every step to the left of that point pays for the full volume, and every step to the right only sees the result.

The browser doesn't need events. It needs answers.

A 30-day chart of p95 latency needs roughly one value per pixel column, maybe with a min/max band. It does not need the thousands of individual requests behind each of those values. The rest of this article follows the data along this path and measures what changes when the reduction moves.

A small lab instead of opinions

Arguments about dashboards and databases tend to be settled by whoever has the most confident anecdote. To avoid that, I built a small, reproducible lab (linked at the end).

One dataset. A generator produces a year of fictional LLM events with realistic structure: daily and weekly seasonality, growth, traffic spikes, heavy-tailed latency that differs per model, provider incidents with bursts of errors, and a few heavy users. The same seed always produces the same events, at 100 thousand, 1 million, 10 million and 100 million events.

Two independent axes. Every result is a cell in a matrix: the engine — PostgreSQL, DuckDB or ClickHouse — and the strategy, which says where and how the data is reduced: naive, server-aggregation, an optimized physical layout, pre-aggregated rollups, and auto, a planner that chooses among them. The goal is not to crown the fastest database. It is to see how the placement of computation changes the whole system, regardless of the engine underneath.

One question, one identity. Every request is normalized into a canonical form — an exact time range, a timezone, sorted filters, the bucket size, a result budget — and hashed. When two engines answer "the same question", their responses carry the same hash, so it can be checked that they really answered the same question.

Measurements were taken on one machine with warm caches: each cell is the median of repeated requests after warm-up (two warm-ups and seven repetitions on the larger datasets), cells run in shuffled order, every comparable response is compressed with gzip at the same fixed level, and browser timings come from a production build in Chromium. Every request has 120 seconds, and every cell has an explicit outcome — completed, timeout, failed — instead of a missing value. Every number is traceable to a recorded run, and the harness rejects any run it cannot prove belongs to the engine, strategy and dataset it claims. The full methodology lives in the repository's README.

The browser receives too much

In the lab: naive — the browser receives raw events and aggregates them in JavaScript.

The dashboard has to show requests, cost and p95 latency over time. The fastest way to get there is to fetch the events and compute the chart in the browser.

That is not a strawman. It is what most of us build first, for good reasons: the backend already has an endpoint that returns events, JavaScript is perfectly good at grouping by time bucket, the first version ships in an afternoon, and every new chart is a frontend-only change. And the problem never arrives as a failure. It arrives gradually, as a dashboard that was instant in March and takes several seconds by September.

In the lab the naive path streams events as NDJSON, and the browser parses them, assigns them to buckets and sorts latencies for the percentiles. (One detail worth stealing: the stream ends with a trailer line, because once a streamed response has started, an error can only be reported inside the stream — and a stream without a trailer must be treated as truncated, not as a dip in the chart.)

What it costs

Here is the one-year view on the smallest dataset, 100,000 events:

One-year view, 100k events	naive	server-side aggregation
Events sent to the browser	100,000	0
Values on the chart	730 buckets	730 buckets
Payload, uncompressed	24.4 MB	82 kB
Transferred with gzip	3.36 MB	15 kB
Total time, request to result	~1.36 s	~51 ms

The cost grows with the range the user looks at: a 30-day view moved 7,781 events (266 kB transferred), a single day 288. And in production it grows with every month of history you keep.

The 1.36 seconds themselves say more about this implementation than about the architecture: a separate profile spent about 0.53 s serializing events in Python and 0.28 s compressing them — work in the API layer, which is the same for every engine. What does not depend on implementation is the volume: to draw 730 points, 100,000 events were read, 24.4 MB produced and 100,000 objects processed in the browser.

Compression is not reduction

Gzip shrank the yearly payload about seven times. That is a real improvement, and it is tempting to stop there. But the database still returned 100,000 rows, the server still serialized 100,000 objects, the browser still parsed all of them — and the chart still showed 730 values.

Compression reduces the size of the representation; aggregation reduces the volume of information.

A compressed list of 100,000 events still contains 100,000 events.

What happened as the data grew

In a real browser, the one-year view on 1 million events downloaded 1,000,000 events — 32.7 MB over the wire — and took 15 to 18 seconds to draw. The same chart from server-side aggregation arrived as 15 kB and was on screen in 63 to 495 ms, depending on the engine.

At 10 million events the naive one-year view did not finish within two minutes on any engine. At 100 million, neither did the one-month view; only the one-day view still completed, by moving 287,370 events (8.9 MB on the wire) to draw 288 points. Every engine failed at the same place, because what grew was the number of events per request — the naive architecture's real unit of cost. The browser was receiving about 137 events for every point it drew, and that ratio only gets worse as history accumulates.

Move the computation to the data

In the lab: server-aggregation — the same events, filtered, grouped and aggregated inside the engine.

The second strategy changes a single thing: the question travels to the data, instead of the data travelling to the question.

GET /v1/timeseries?from=…&to=…&metrics=requests,cost,p95_latency&max_points=1200
        ▼
canonical query: range · timezone · bucket size · budget  →  hash
        ▼
engine: filter → group into buckets → count / sum / percentile
        ▼
API → 730 buckets of JSON → browser → chart

Two details matter. The client sends max_points equal to the chart's width in device pixels, and the server picks a bucket size so that the result never has more buckets than that. And the request is no longer "give me rows" but "give me these metrics, at this resolution, for this range, with these filters" — the API stops being a CRUD endpoint and starts behaving like a small query language.

One shared layer defines what a bucket, a percentile or a filter means; a thin adapter per engine decides how to compute it — percentile_cont() in PostgreSQL, quantile_cont() in DuckDB, quantileExactInclusive() in ClickHouse. For every control query, all three engines returned the same canonical hash and equivalent values. The reduction strategy is independent of the engine.

The first measurements showed DuckDB slower than PostgreSQL on small queries. Before writing that down, I traced it: the engine ran the query in 3–4 ms, and about 40 ms went into passing a few hundred bucket boundaries from Python as a query parameter — a property of my adapter, not of the database. Passing them as a small in-memory table took the overhead from about 48 ms to about 7 ms. The measuring apparatus has to be cheaper than the thing it measures.

Server-side aggregation shrank the yearly answer from 100,000 events to 730 buckets — roughly 300 times less data, more than 200 times less on the wire — while the chart stayed exactly the same.

Sidebar: cancelling work nobody needs anymore

Users don't wait for a chart before changing their mind. They drag to zoom, zoom again, flip a filter, and every new action makes the previous query useless. An AbortController per request stops the browser from waiting — but unless the cancellation travels all the way down, from the closed HTTP connection through the application into the engine, the database keeps computing answers nobody will see.

The lab simulates a user who changes zoom and filters four times in quick succession while each query is kept busy in the engine for 1.5 seconds. On all three engines the three superseded requests were cancelled, exactly one query was running while the latest one executed, and no orphaned queries were left afterwards. A frontend concern — "zooming feels sluggish" — was solved by a change that reaches into query execution. The most expensive query is the one whose result is thrown away.

Correctness before performance

A fast dashboard that shows the wrong p95 is worse than a slow one, because nobody notices. So before any benchmark, every engine and strategy has to produce the same answer — and that answer has to be right.

If PostgreSQL and DuckDB return the same number, that proves they agree, not that the number is right. Bucketing, timezones and the definition of a percentile live in shared code; a bug there makes every engine wrong in the same way. So the lab has three independent layers:

A hand-written fixture of 57 events, each placed to test something: an event exactly at the start of the range and one exactly at its end, a 23-hour Berlin day, a Kolkata day that starts at 18:30 UTC, empty hours, a latency spike, a range that runs past the data. The expected answers were computed by hand.
An independent reference implementation — plain Python loops that share no code with the query layer and assign events to buckets with a different algorithm.
The same control queries against every engine and strategy, compared strictly: integers exactly, floating-point values within a relative error of 10⁻⁹.

The suite paid for itself on its first real run. On the 100k dataset, the engines disagreed with the reference on weekly buckets in UTC — and the bug was in the reference. It started UTC weeks on Thursday, because 1 January 1970 was a Thursday, while the specification starts weeks on Monday. Even an independent oracle can be wrong; that is why the hand-computed fixture exists as the one check that trusts no code at all. After the fix, every control query passed on every engine and strategy.

A preview: what you keep decides what you can answer

Correctness also decides what can be pre-aggregated later. One day in the fixture has 36 requests: one hour with 20 slow requests (1,000–1,950 ms), eight hours with two fast ones each. Suppose only hourly summaries were kept:

How the daily value is computed	Average latency	p95 latency
Exact, from all 36 events	868.3 ms	1,862.5 ms
Average of the hourly values	261.7 ms	317.2 ms
Maximum of the hourly values	—	1,902.5 ms
From composable state: hourly `sum` + `count`	868.3 ms	—
From composable state: merged hourly histograms	—	1,852.4 ms

The average of averages is off by a factor of three, because it forgets that the slow hour had ten times the traffic; keeping sum and count makes it exact again. Neither the average nor the maximum of hourly p95 values gives the daily p95. Merged hourly histograms gave 1,852.4 ms against the exact 1,862.5 ms — an observation on 36 hand-placed events, not a guarantee, but an approximation of the right thing instead of an exact answer to the wrong question.

Pre-aggregation is only correct if we preserve enough information to compose the metric later.

Sidebar: benchmarking code needs correctness checks too

The measuring code needed the same suspicion as the code it measures. Each of these would have produced a confident, wrong number:

the cancellation test passed for ClickHouse while proving nothing — the artificial "busy" query was optimized away, so nothing was ever in flight;
the harness silently dropped a parameter and measured the baseline strategy in every cell labelled "optimized";
an engine-side time limit stricter than the benchmark's own turned a slow stream into an "error" on one engine and a "timeout" on the others;
the first PostgreSQL rollups measured slower than the raw events they summarize, because my builder wrote them in hash order, so reading one month of a time-indexed summary touched nearly the whole table;
an exact percentile on ClickHouse that had "run out of memory" turned out to hold only 427 MiB of the 2.70 GiB the server reported in use when it was stopped. The failure was not attributable to the query's own memory, and in a clean state the same query passed every time.

None of them showed up as a crash; each showed up as a number. The harness now fails closed: every measurement must prove, from what the server reports, which engine, strategy, dataset and canonical question it belongs to, or the run is discarded — and discarded runs stay on record with the reason. A database benchmark can measure work you did not realize was running.

The database is still reading too much

In the lab: optimized — the same events, in a physical layout each engine can prune.

Server-side aggregation fixed the network. It did not fix the work: the engine still computed every chart from event-level data, and on 100 million events ClickHouse reported reading all 100 million rows to draw a single day.

The OLTP reflex is to index the timestamp. But an index helps you find a few rows; a dashboard wants millions of rows, grouped. What matters at this scale is whether the engine can discard whole partitions, files or blocks before reading them. So each engine got a layout built for pruning: PostgreSQL monthly partitions with a BRIN index on time; DuckDB Parquet partitioned by day and sorted by model and time; ClickHouse monthly partitions sorted by model, country and time. The correctness suite re-checked every query on every layout.

100M events, baseline → pruning layout	One day	One month	One year
PostgreSQL	145 → 127 ms	4.4 → 3.6 s	51 → 52 s
DuckDB	109 → 78 ms	0.92 → 1.22 s	26 → 27 s
ClickHouse	491 → 51 ms	533 → 178 ms	1.2 → 1.8 s

ClickHouse is the clearest example of pruning doing exactly what it promises: for one day it read 2.74 million rows instead of 100 million. The other two engines are more interesting. PostgreSQL barely changed — consistent with its baseline already having a B-tree on the timestamp, which serves exactly this kind of time-range question. DuckDB's baseline was the generator's time-ordered Parquet, whose per-row-group statistics allow skipping much of a file for a narrow range. Its day-partitioned layout was slower than that baseline everywhere except the one-day view at 100 million events — at 10 million, a day took 36 ms instead of 18. That is consistent with the cost of opening and planning thousands of small files outweighing the rows they let it skip; the lab did not profile where the time went.

And nothing helped the year. A year is the whole dataset: there is nothing to skip.

Layouts also have a price. On 100 million events, PostgreSQL's partitioned table took 16.7 GB instead of 14.0 GB and 390 s to build; ClickHouse's took 1.6 GB instead of 3.6 GB, its compressed column types more than paying for the extra structure; DuckDB's sorted, partitioned Parquet took 1.7 GB instead of 2.1 GB.

A physical layout is a bet on which questions will be cheap. Pruning reduces what the engine reads only when the question is narrower than the data. The widest question a dashboard asks — "show me the whole year" — reads everything, every time, and recomputes history that will never change.

The obvious move is to compute those answers once and keep them. But before storing anything, we have to know what a stored answer must contain — and that depends on the metric.

How expensive is a percentile?

In the lab: one layout, one range at a time, and only the metric changes.

A dashboard tile looks like a number. Behind it is an aggregation, and aggregations are not equally expensive. A count needs one integer per bucket, an average two. An exact percentile needs far more value-level state and work: its answer depends on how all the values in a bucket are distributed, not on a few running totals. Before deciding what to pre-aggregate, I measured what each costs on its own. "Approximate p95" here means a histogram over 142 fixed logarithmic latency bins — the same on every engine, chosen because it can be merged, not because it is fast.

One month (7.8M events), 100M dataset	count	sum + avg	exact p95	approximate p95
PostgreSQL	1.43 s	1.61 s	4.12 s	4.78 s
DuckDB	678 ms	687 ms	670 ms	2.39 s
ClickHouse	106 ms	162 ms	176 ms	1.98 s

The exact percentile costs memory before it costs time. ClickHouse, the only engine here that reports per-query memory, needed 54 kB to count a year of events and 592 MB for the exact p95 over the same 100 million events, at about the same speed. A count's state does not grow with the data; an exact percentile's does. On PostgreSQL the exact percentile was also about three times slower than the count.

The approximate percentile was not cheaper. Computed from raw events, it was the slowest metric on every engine — eleven times slower than the exact one on ClickHouse for a month. In this lab's implementation each event is assigned to a bin by a generic expression, and ClickHouse reads the data twice; the measured cost is consistent with that extra work, but the lab did not profile it, and a different implementation could behave differently. The measurement does not show that histograms are inherently slow. What the histogram bought was bounded state — 288 MB on ClickHouse for a year, independent of how many events fall into a bucket — and, above all, the ability to merge.

On PostgreSQL the yearly comparison was not interpretable: a full-year scan of a 16.7 GB table under the lab's 3 GB memory limit reads from disk, varied between 25 and 59 seconds within one series, and hit the two-minute limit in three of four cells at least once.

Approximation is an information and representation trade-off, not a performance guarantee.

The percentile is the metric that decides what a summary must contain. An exact percentile needs value-level detail that grows with the data — much closer to the raw events than to a summary — so a summary either keeps that detail or keeps a bounded, mergeable approximation and accepts an error. If we want to stop recomputing history, we first need a representation that can be merged without changing the meaning of the metric. Additive metrics already have one; for the percentile, the histogram is it.

Why recompute history?

In the lab: rollup and auto — the same questions, answered from pre-aggregated, composable state instead of events.

Physical layout helped when the query could skip data. A year cannot be skipped. Every time someone opened the yearly view, the engine read 100 million events again and recomputed answers for months that had not changed since the last time — and never would.

What if we stop asking 100 million events the same question?

What we decided to keep

The correctness preview already said what not to store: no averages, no percentiles — only state that can be combined. The lab keeps three grains, identical on all three engines:

Rollup	Time grain	Dimensions kept
`r_1m`	minute	model, status
`r_1h`	hour	model, country, status
`r_1d`	day	model, country, status

Every cell stores a count, cost and token sums, a latency sum, a failure count, the latency minimum and maximum, and a 142-bin latency histogram. The daily rollup is built by merging hourly cells, which makes it a composability test in its own right: its per-model, per-day totals matched the generator's records exactly on every engine. One thing is deliberately missing — user_id — and the next part is about why.

Asking the summary — and being refused

A planner splits every requested bucket into the largest whole rollup cells that fit it and keep every filtered dimension, and computes whatever is left — ragged edges that don't line up with a minute — from event-level data. A filter on country cannot use the minute grain, which doesn't keep country; a Kolkata day, which starts at 18:30 UTC, is assembled from hourly cells plus thirty minutes of minute cells. An exact percentile cannot come from a rollup at all, so that combination is reported as not applicable rather than quietly approximated. And when no rollup can answer — a filter on one user — rollup refuses, while auto answers from event-level data and says so in its plan. Nothing falls back silently.

Is it still the same answer?

Before measuring speed, rollup answers were compared with the independent reference. Additive metrics — requests, cost, tokens, average latency as sum over count, error rate — matched exactly on all three engines, on every control query, from 100 thousand to 100 million events.

The p95 is now an estimate, and its quality depends on how many events fall into a bucket. On 100 million events the histogram stayed within 0.46% of the exact p95 for daily and six-hour buckets; for five-minute buckets of one model or one country the median error was 1.5–2.2% and the worst bucket was off by 36%. On the 1-million-event dataset, one bucket in ten was off by more than 60%. A histogram describes a crowd well and a handful of requests badly. These are observations on this dataset, not a guarantee — and a dashboard that shows an approximate p95 should say so.

What the measurements showed

The yearly view changed most, because that is where recomputation was most wasteful:

Yearly view, 100M events	From events (exact p95)	From events (approximate p95)	From rollups (approximate p95)
PostgreSQL	45.3 s	timed out	10.9 s
DuckDB	41.5 s	91.6 s	1.74 s
ClickHouse	1.69 s	19.8 s	0.36 s

The one-month view went from 3.9 s to 0.91 s on PostgreSQL, 0.65 s to 0.18 s on DuckDB and 164 ms to 117 ms on ClickHouse; the one-day view barely changed anywhere, because pruning had already removed nearly all its work. Pre-aggregation pays where the question is wider than the data you can skip.

The funnel explains both the gain and its limit. The 730-point yearly chart uses 12-hour buckets, which daily cells cannot fill, so the engine read the hourly rollup: 37.5 million rows instead of 100 million events. And 94% of those rows were histogram rows. Additive state is cheap; the percentile is most of the rollup.

That is not waste — it is the price of a decision made earlier. Correctness required composable state; a composable percentile requires a histogram per cell; and the histogram is what keeps both the summary large and the p95 answerable for any range. A rollup is not "a few hundred rows".

Rollups also have a price in storage and build time. Built from scratch on 100 million events they took between 219 s (ClickHouse) and 622 s (PostgreSQL). They occupied 367 MB as Parquet and 609 MB in ClickHouse, but 9.8 GB in PostgreSQL — 70% of the size of its event table; the lab measured that difference but did not isolate its causes. Most of it is the minute grain, which keeps 0.71 rows for every event: a "summary" barely smaller than the data it summarizes.

Pre-aggregation moves work from every read to one build — and only for the questions its grain can still answer.

A rollup behaves like a cache with a schema: it precomputes some questions and deliberately gives up others. It made the most expensive question in the dashboard 4 to 24 times cheaper on every engine, kept additive answers exact, and turned the p95 into an estimate whose quality depends on bucket size. Keeping it fresh as new events arrive is outside this investigation.

Reducing data means reducing optionality

In the lab: rollup grain, high-cardinality dimensions, and what happens when a summary cannot answer.

The rollups have no user_id. That was the price of making them small, and it means a support engineer who asks for one customer's latency over the year gets a refusal from rollup and an event-level query from auto. Every dimension left out of a summary is a question you have decided to answer the slow way — or not at all.

So how much would it cost to keep it? The lab counted, exactly, the cells and histogram rows that existing and hypothetical grains would contain on 100 million events. Nothing hypothetical was built; the sizes are counted over the raw events, not estimated.

Grain (100M events)	Cells	Rows stored per event	Cannot answer a filter on
`r_1d(model, country, status)`	171,363	0.037	user
`r_1d(model, country, status, user_id)`	29,158,129	0.87	—
`r_1d(user_id)`	10,913,108	0.35	model, country, status
`r_1h(model, country, status)`	2,266,643	0.38	user
`r_1h(model, country, status, user_id)`	53,677,021	1.42	—
`r_1m(model, status)`	5,433,407	0.71	country, user
`r_1m(model, country, status)`	46,999,692	1.42	user

Adding user_id to the daily rollup multiplies its cells by 170 and brings it to 0.87 stored rows per event. Adding it to the hourly rollup, or adding country to the minute rollup, produces more rows than there are events: the "summary" is larger than the data it summarizes. A user-only rollup is smaller, but answers nothing about models or countries.

The planner makes the trade-off visible instead of hiding it: a query filtered by user is refused by rollup and answered by auto from event-level data, with the reason in its plan — "r_1d cannot be used: it has no user_id dimension".

Every rollup is a decision about which questions remain answerable.

A rollup is not small because it is a rollup. It is small only while its grain and dimensions collapse enough of the original event space — and pre-aggregation reduces data partly by reducing the set of future questions the representation can answer. High-cardinality dimensions belong to a different access path, and the system has to know which path answers which question, and say so. A summary that silently answers a question it cannot answer is worse than one that refuses.

Your chart has only so many pixels

In the lab: a point budget instead of a bucket size, and a min/max envelope that is part of the query, not a trick in the client.

So far the question was what to store and what to read. The last reduction happens at the other end of the pipeline: how much of the answer to send. Every request so far carried max_points=1200, and the server turned it into a bucket size. That choice was never tested. A reasonable engineer could argue the opposite: return as much resolution as you can afford and let the chart sort it out — more points can only be more faithful. So: what does extra resolution cost when the screen cannot show it, and what does a coarse answer lose?

Why "return everything you have" isn't free

The experiment fixed everything — 100 million events, the yearly range, request rate as the metric, the auto strategy, ClickHouse and DuckDB — and changed only the point budget. The server picks the finest bucket from a fixed set that fits it, so budgets form a staircase:

Point budget	Bucket	Points	Transferred (gzip)	Time to chart, ClickHouse / DuckDB
100 or 300	1 week	53	2 kB	98–164 / 192–203 ms
600	1 day	365	5 kB	110 / 173 ms
1,200	12 hours	730	8 kB	292 / 242 ms
5,000	3 hours	2,920	50 kB	382 / 289 ms
10,000	1 hour	8,760	127 kB	633 / 457 ms

Twelve times as many points as the 1,200-point chart multiplied the bytes by sixteen and roughly doubled the time to chart on both engines. Drawing was not the bottleneck — the chart rendered 8,760 points about as fast as 730. The cost was everything before the canvas: finer cells to read, more JSON to build, transfer and parse. The budget even decided which summary could be used at all — up to one-day buckets the daily rollup answered; below that, the hourly one, with thirteen times as many cells.

Before measuring, the lab checked every bucket of every response against per-minute rates computed directly from the raw files: buckets tile the year without gaps or overlaps, never exceed the budget, use the finest step that fits — including a Berlin year with its 23- and 25-hour days — and every value matches.

What a coarse answer loses

Fewer points mean fewer bytes; that part is obvious. The real question is what disappears. To avoid picking a flattering example after the fact, a rule fixed before measurement selected the features: the three highest per-minute traffic peaks relative to their 12-hour rolling median that stay above 1.5× for at most three hours. It picked three spikes, 5.6 to 7.1 times the surrounding rate, lasting one to two and a half hours.

On the 1,200-point chart each spike falls into one 12-hour bucket, and the bucket's mean showed only 20–23% of the spike's peak; compared with its neighbours, the spike's bucket stood out in only one of three cases. Even at 10,000 points — eight times the screen — the mean reached only 65–81% of the peak. Averaging is a reduction that decides, silently, that short events don't matter.

Keeping the spike without keeping every sample

The alternative is to decide explicitly what must survive. With an envelope, the server also returns for each bucket the minimum and maximum of the per-minute rate inside it — computed from whole minutes of the minute rollup, and counted against the result budget as two more numbers per point.

At 1,200 points the envelope's maximum equalled each spike's peak per-minute rate exactly, and the spike's bucket stood out from its neighbours by a factor of 3.2 to 6.1. Compared with simply asking for more points, it was the better trade on this workload: 11 kB instead of 127 kB, and the full per-minute peak instead of 65–81% of it, at a similar time to chart. Its cost does not depend on the budget but on the base resolution: every envelope request read the year's 5.4 million minute cells, adding 150 to 310 ms on the server.

It has limits. It is exact only at its base resolution: it reports the busiest minute, so a burst shorter than a minute is averaged into it and no individual event is kept. It preserves magnitude, not timing: the spike is only known to lie somewhere in its 12-hour bucket. And it does not guarantee visibility: in weekly buckets, one spike — on a Saturday morning, when traffic is low — was smaller than the ordinary weekday peaks sharing its bucket, so its envelope looked like any other week's.

Reducing information is useful only when we know which information the consumer can no longer use — and which information it still needs to see.

A 1,200-pixel chart cannot use 8,760 points. What it could use was a little more information per pixel. Resolution is a budget with two dimensions: the point budget limits temporal resolution — how many buckets — and a value budget limits representation richness — how much each bucket carries. The same 730 buckets can carry one number each or three, and only the second version shows the spike.

One fast query is not a production dashboard

In the lab: closed-loop concurrency — the same yearly chart from events, from rollups, and from rollups with the envelope, while more users ask at once.

Every number so far came from one request at a time. A dashboard is not used that way, and a strategy that is fast alone can still collapse when its requests compete for the same cores. Does reducing information per request also improve the system's ability to serve concurrent users — and what happens to the envelope's extra work when many people want it at once?

The lab ran a closed loop: virtual users, each sending the next request as soon as the previous answer arrives. Every user asked for the yearly chart at the 1,200-point budget in three representations — A, event-level aggregation on the pruning layout; B, from rollups; C, from rollups with the per-minute envelope — on ClickHouse and DuckDB, with the same container limits as everywhere else and no cache. Users went up 1, 4, 8, 16, 32, and a rule fixed beforehand stopped each ladder when throughput no longer grew while tail latency rose, or when more than 5% of requests failed. CPU per request came from the containers' own accounting, engine and API together.

The first attempt was discarded. Four event-level DuckDB queries timed out, and two of them kept running for about fifty seconds after their clients had left, competing with the next measurement for the same six cores. Cancellation itself worked — a single heavy query stopped within half a second — but four interrupted heavy queries on one DuckDB instance wound down one at a time. The repeated run waited for every engine to be idle before each step.

Where throughput stopped

Every ladder stopped early, at 4 or 8 users. Each one except DuckDB's event-level ladder stopped when its engine had used up its CPU allowance — ClickHouse all 3 engine cores, DuckDB all 4; the event-level DuckDB ladder failed by timeouts first, at four users, with requests taking over 100 seconds.

Per representation	A · events	B · rollups	C · rollups + envelope
ClickHouse: max throughput	0.95 req/s	45 req/s	10 req/s
ClickHouse: CPU per answer	3.2–3.6 s	0.07–0.08 s	0.26–0.36 s
DuckDB: max throughput	0.06 req/s	11 req/s	4.8 req/s
DuckDB: CPU per answer	39 s	0.35–0.37 s	0.80–0.83 s

The ceilings matched, within a few percent, the CPU allowance divided by the CPU each answer cost — for ClickHouse from rollups, 3.8 cores ÷ 0.084 s ≈ 45 requests per second. Answering from rollups did not just make one request faster; it raised capacity by about the same factor as it reduced work: 48 times on ClickHouse, about 190 times on DuckDB.

Past the plateau, adding users bought only waiting: on ClickHouse with rollups the median answer took 32 ms for one user, 86 ms for four and 175 ms for eight, at the same 45 requests per second. The waiting was inside the engine, not in the API's queue. And the engines got there differently: one ClickHouse rollup answer used about 1.6 of its 3 cores, leaving room for a few more users, while one DuckDB answer already kept nearly all 4 cores busy, so its throughput was flat from the first step.

The price of the envelope, multiplied

For one user the envelope cost little: on ClickHouse the median answer went from 32 to 97 ms. Under load, that difference became capacity. Reading a year of minute cells made each answer cost about four times as much CPU, and the system served 10 requests per second instead of 45; on DuckDB, 4.8 instead of 11. The envelope's fidelity is still worth having — but it is paid on every request, and under simultaneous demand it is paid in users.

Capacity is a budget of work. Reduce the work per answer before trying to serve more answers at once.

On this machine, how many users a representation could serve followed from how much work each answer took. The strategy that won for one request also won under load, by a wider margin than its latency alone suggested. These are relative results on a small, fixed allowance of cores; they say nothing about how many users any engine supports in general.

Results: how the bottleneck moved

Each part of this investigation removed one kind of unnecessary information, and each time the bottleneck moved. Followed in order, the same one-year chart went through six transitions:

Where the data got smaller	What the yearly chart processed	What it cost
Nowhere — the browser aggregates	every event in the range, sent to the browser	stopped finishing at 10M events; at 1M, 32.7 MB and 15–18 s to chart
In the engine	all 100M events read, 730 buckets returned (about 15 kB)	ClickHouse 1.2 s, DuckDB about 26 s, PostgreSQL about 51 s
In the physical layout	for one day, 2.74M rows read instead of 100M	51 ms instead of 491 ms on ClickHouse — and no help for the year
In stored history	37.5M rollup rows instead of 100M events, 94% of them histogram rows	ClickHouse 0.36 s, DuckDB 1.7 s, PostgreSQL 10.9 s — instead of 1.7 s, 41 s and 45 s
At the screen	730 points (8 kB) instead of 8,760 (127 kB); 2,190 values with an envelope (11 kB)	about half the time to chart, with every spike's per-minute peak kept
Across users	45 rollup answers per second instead of 0.95 event-level (ClickHouse); 11 instead of 0.06 (DuckDB)	capacity set by CPU per answer

Read top to bottom, the table is a list of bottlenecks that each looked like the problem until it was removed: first the network and the browser, then the engine scanning everything, then the engine recomputing history, then the size of what history had to keep to stay correct, then how much of the answer the screen could use, and finally the CPU every answer costs when many people ask at once.

The reductions were cumulative — rollups mattered because the browser no longer received events, and budgets mattered because rollups had made answers cheap enough for their size to show. And each was safe only because something checked it: the same canonical question, answered identically by three engines and an independent reference, before any of its speed was measured.

The lab stopped at 100 million events. The trend a larger run would test — event-level work growing with the data, summaries growing far more slowly — was already visible from 100 thousand upward; another step would have confirmed it rather than raised a new question. Not tested at all: keeping rollups fresh, a cache in front of the engine, behaviour beyond capacity under an open arrival rate, and concurrency on PostgreSQL.

Choosing an architecture

The reader should not take a database ranking from this lab, because none was measured in a way that would support one. What the experiments do support is a sequence of questions about the workload — each changed the outcome more than the choice of engine did.

Are you shipping event-level data to answer aggregate questions? Then the database is not your first problem. The naive dashboard failed at the same point on all three engines, because its unit of cost was events per request.

Are your queries selective enough for the layout to matter? For narrow ranges, yes — but check what the baseline already does. PostgreSQL's ordinary time index already captured most of the benefit; ClickHouse needed a sort order before it could skip anything; DuckDB's extra partitioning helped only one view at the largest scale. For the whole year, no layout helped.

Are broad historical questions repeated? Then stop recomputing them. Rollups made the yearly view 4 to 24 times faster on every engine and raised concurrent capacity by a similar factor, and did little for a single day.

Which metrics need composable state? Sums and counts compose; averages and percentiles don't. A percentile in a summary needs a mergeable representation, which costs storage and returns an approximation whose error depends on bucket size.

Which dimensions must stay available? Every dimension kept in a summary multiplies its size, and a high-cardinality one can make it larger than the data. Decide which questions get the cheap path, and make the system say which path it took.

How much resolution can the consumer use? Returning more points than pixels cost bytes and time without making the chart more faithful. If short-lived features matter, ask for them explicitly and pay for them in the budget.

What does one answer cost when many people ask at once? Under CPU-bound load, capacity was the CPU allowance divided by the work per answer.

The engines differed in where they met these limits, and those differences are evidence about this workload on this machine, not general verdicts:

PostgreSQL served selective time ranges well with nothing but an index. Its broad scans of 100 million events were I/O-sensitive under the lab's 3 GB container budget and varied widely between repetitions. Rollups still cut the yearly view from 45 s to 10.9 s. Its rollup tables were far larger than the other engines' — 9.8 GB against hundreds of megabytes — for reasons the lab did not isolate.
DuckDB scanned Parquet quickly and spread a single query across all its cores, which made one request fast and left no headroom for a second user in this setup. Its partitioned layout was a net cost at small scale here — consistent with the overhead of many small files on this data, and not evidence about partitioning in general. Under overload, interrupted heavy queries took tens of seconds to wind down.
ClickHouse had the fastest broad scans once its data was sorted, and a single rollup answer left part of its CPU free for other users. Its exact yearly percentile needed about 600 MB of memory; an earlier out-of-memory failure turned out not to be attributable to that query alone.

Practical recommendations

These follow from the measurements on this workload and this machine. They are starting points, not laws.

Reduce data before transport. Don't ship event-level rows when the visualization needs aggregates; send the question and the chart's width, return buckets. It was the largest single improvement in the lab, on every engine.
Reduce reads through physical access — after checking what you already have. Sorting and partitioning by time helped narrow ranges; a plain time index was already most of the win on PostgreSQL, and small partitioned files cost more than they saved on small DuckDB datasets.
Store the state needed to compose the metric, not a final value that cannot be composed. Sums and counts instead of averages; for percentiles, a mergeable representation — this lab used a fixed-bin histogram — and label the result as approximate, because its error depends on how many events a bucket holds. Verify the summary against raw data before trusting it.
Stop recomputing the widest questions you keep asking. Rollups paid off on the year and barely on the day. Choose grains that fit the bucket sizes your charts request: a 12-hour bucket cannot be filled from daily cells.
Reduce optionality deliberately. Keep high-cardinality dimensions out of summaries, give them their own access path, and make the system refuse or route — with a reason — when a summary cannot answer.
Budget the representation for its consumer. Ask for the screen's resolution, and name the features that must survive it: when short-lived extremes matter, return an envelope per point instead of more points, and count it in the budget.
Reduce the work per answer before trying to serve more answers at once. Throughput topped out at the CPU allowance divided by the CPU one answer cost; price every addition to an answer in users, not only in milliseconds.
Treat the benchmark as code under test. Several confident numbers here measured a bug in the harness, the builder or the environment. Make every measurement prove which question, engine and dataset it belongs to, and keep discarded runs on record.

Where should a chart's numbers come from?

Does the request need individual events (an export, a drill-down to rows)?
├─ yes → serve event-level data, paged or streamed — a different access path from charts
└─ no  → aggregate on the server; at most as many buckets as the chart has pixels
         │
         Must short-lived extremes stay visible?
         ├─ yes → add a min/max envelope from a fine base, counted in the value budget
         │        (it keeps each sub-bucket's peak, not single events or exact times;
         │         to locate a spike, ask for a narrower range)
         └─ no  → the bucket value alone
         │
         Exact percentile required?
         ├─ yes → event-level aggregation on a pruning-friendly layout
         └─ no  → Does a rollup keep every filtered dimension?
                  ├─ no  → event-level aggregation, and say why
                  └─ yes → rollup cells, with event-level data for edges they don't cover

One answer is fast, but many users saturate the engine?
└─ capacity ≈ CPU allowance ÷ CPU per answer: remove work from each answer first,
   and price additions such as the envelope in users. Past that point, more users only add waiting.

Conclusion

The chart at the start of this article is 1,200 pixels wide. Behind it were 100 million events. Everything in between was a series of decisions about where to discard information.

The naive dashboard discarded nothing until the browser. Server-side aggregation moved the reduction into the engine; a pruning layout let the engine skip data — but only for questions narrower than the data. Rollups stopped recomputing history, and only worked because they kept composable state rather than finished answers. Their size showed that a summary is small only while it gives up enough questions. The screen set a budget for the answer, and the spikes showed that the budget is not just a number of points but a choice of what each point must carry. Under many users, all of it became a single quantity: the work each answer costs.

One rule ran through every part:

Find the earliest layer where information can be safely discarded.

Earliest, because every layer before the reduction pays for the full volume. Safely, because every reduction is also a decision about which questions remain answerable — and correctness, composability and fidelity are what make it safe.

A data-heavy frontend is not a rendering problem with a database behind it. It is an information-reduction pipeline, and its performance is decided long before the first component renders.

The lab, the full methodology and every raw measurement: https://github.com/godfreyd/100m-to-1200px

You Don't Modularise a Frontend by Moving Files

Sergey — Sat, 29 Aug 2026 10:23:25 +0000

Notes from trying to give one React component a place it could actually call its own

We wanted to split a large frontend into packages.

This sounded, at first, like a file-moving problem.

We had a component. Let's call it WeatherCard.

It showed the current weather, allowed the user to save a location, sent analytics events, behaved slightly differently on the home page and in search results, participated in an experiment, and knew whether the application was running on mobile.

Nothing particularly exotic.

It lived here:

src/
  feed/
    cards/
      weather/
        WeatherCard.tsx

We wanted it here:

packages/
  weather-card/

So we moved it.

That took an afternoon.

Modularising it took considerably longer.

The files moved. The application came with them.

The first package looked promising.

packages/
  weather-card/
    WeatherCard.tsx
    WeatherIcon.tsx
    weather.css
    index.ts

It had a package.json.

It had tests.

It even had a pleasantly small public export.

export { WeatherCard } from './WeatherCard';

Then I looked at the imports.

import { useSelector } from 'react-redux';
import { useTranslation } from '../../i18n';
import { useExperiment } from '../../experiments';
import { useAnalytics } from '../../analytics';
import { useRouter } from '../../router';
import { selectSavedLocations } from '../../store';

The package was physically separate and architecturally attached to almost everything around it.

An import is at least honest about this. Package managers can see it. Build tools can see it. Static analysis can complain about it.

Other dependencies are more discreet.

Our component appeared to have a wonderfully small API:

<WeatherCard item={item} />

That was not really its API.

Its inputs looked more like this:

WeatherCard
    │
    ├── item
    ├── Redux store
    ├── router
    ├── translations
    ├── experiments
    ├── analytics
    ├── application type
    └── device configuration

Only one happened to be written in the function signature.

The others arrived through the atmosphere.

This wasn't an argument against Redux or React Context. Both had been useful. The problem appeared only when we tried to establish a boundary.

Global context doesn't remove dependencies.

It makes some of them easier not to see.

An adapter helped

We introduced an adapter.

function WeatherCardAdapter({ rawItem }: Props) {
  const savedLocations = useSelector(selectSavedLocations);
  const t = useTranslation();
  const router = useRouter();
  const experiment = useExperiment('compact-weather-card');
  const analytics = useAnalytics();

  return (
    <WeatherCard
      rawItem={rawItem}
      savedLocations={savedLocations}
      translate={t}
      compact={experiment.enabled}
      onOpenLocation={router.open}
      onEvent={analytics.send}
    />
  );
}

WeatherCard no longer needed to know where these things came from.

The application-facing dependencies accumulated in the adapter instead.

Application
     │
     ▼
WeatherCardAdapter
     │
     ▼
 WeatherCard

There was an immediate problem.

The component interface became ugly.

We fixed the ugly interface

The real component looked closer to this:

<WeatherCard
  rawItem={rawItem}
  savedLocations={savedLocations}
  translate={translate}
  compact={compact}
  onOpenLocation={onOpenLocation}
  onSaveLocation={onSaveLocation}
  onEvent={onEvent}
  isMobile={isMobile}
  pageType={pageType}
/>

Nine props.

We had taken a component with a neat API and turned it into this.

So we did what seemed sensible.

We introduced WeatherCardContext.

interface WeatherCardContext {
  savedLocations: SavedLocation[];
  translate: Translate;
  compact: boolean;
  openLocation: (id: string) => void;
  saveLocation: (id: string) => void;
  sendEvent: (event: WeatherEvent) => void;
  isMobile: boolean;
  pageType: PageType;
}

The component became tidy again.

<WeatherCard
  rawItem={rawItem}
  context={weatherCardContext}
/>

Much better.

For perhaps a week, I thought we had found the right abstraction.

Then another card needed the same translation function.

And the same navigation behaviour.

But not the same analytics.

A third card needed analytics and device information, but had a different interpretation of pageType.

We started constructing context objects.

Then helpers for constructing context objects.

Then a common context from which card-specific contexts could be constructed.

The dependency graph we had been trying to remove was slowly reappearing inside one object.

Worse, code review had become harder.

This:

<WeatherCard context={context} />

said almost nothing about what changing WeatherCard might affect.

We had successfully shortened the interface.

We had also hidden it again.

So we deleted WeatherCardContext and put the ugly props back.

That felt like going backwards.

It wasn't.

The long interface was information.

Some props belonged to the weather card:

rawItem
savedLocations

Some were capabilities supplied by the application:

onOpenLocation
onSaveLocation
onEvent

Some described presentation:

compact

And some looked suspicious:

isMobile
pageType

Why did a weather card need to know that it was on mobile?

The answer was in the rendering code.

if (isMobile) {
  return <CompactTemperature temperature={temperature} />;
}

return <TemperatureWithDetails temperature={temperature} />;

It didn't care about mobile.

It cared about presentation.

So:

isMobile={isMobile}

became:

displayMode="compact"

A tiny change, but a useful one.

isMobile described the world outside the card.

displayMode described the card.

The ugly interface had shown us where to look.

Sometimes an ugly interface is an X-ray.

Then we found the state

Saving a location changed global Redux state.

That seemed reasonable. The application needed to know which locations were saved.

The card also stored whether its save animation was running in Redux.

That seemed less reasonable.

Then we found whether the tooltip had been dismissed.

Also Redux.

Whether the expanded forecast was open.

Redux.

Whether the user was currently hovering over the card.

Thankfully, not Redux.

We had apparently drawn a boundary somewhere. We just couldn't explain why it was there.

Asking whether something belonged in Redux wasn't getting us very far, so we changed the question.

Who owns this state?

The expanded forecast existed only while the card existed.

The save animation existed because the card was displaying it.

The tooltip belonged to that interaction.

They moved inside.

function useWeatherCard() {
  const [expanded, setExpanded] = useState(false);
  const [saving, setSaving] = useState(false);
  const [tooltipVisible, setTooltipVisible] = useState(true);

  // ...
}

Saved locations were different.

Another card could save the same location. Navigation could show the number of saved locations. The information survived the lifetime of any individual WeatherCard.

That stayed outside.

This gave us a rule we could actually use:

If state needs to be observed outside a boundary, either the observer belongs inside the boundary or the state doesn't.

It was a more useful question than choosing between Redux and useState.

The application knew what weather looked like

Data was next.

The API returned something like:

{
  "type": "weather",
  "id": "london",
  "temperature": 17,
  "units": "celsius",
  "forecast": [],
  "alerts": [],
  "provider": {}
}

The application parsed this response.

The feed extracted fields.

The card received the resulting object.

This had always worked.

It also meant that changing the server representation of a weather card could require changes in code that otherwise had nothing to do with weather.

We tried making the data opaque to the application.

The feed needed surprisingly little:

interface FeedItem {
  id: string;
  type: string;
  rawItem: unknown;
}

The rest could cross the boundary untouched.

Server
   │
   ▼
Feed
   │
   │ rawItem
   ▼
WeatherCard
   │
   ▼
Weather parser
   │
   ▼
Weather model

The parser moved into the package.

const WeatherItem = object({
  id: string,
  temperature: number,
  units: oneOf('celsius', 'fahrenheit'),
  forecast: array(Forecast),
});

This was one of the quieter changes in the migration.

It removed no visible feature. It probably made no benchmark move.

What changed was who had to understand the data.

The feed stopped understanding weather.

That was useful.

A string that wasn't a string

Packages gave us another tool: compilation boundaries.

Suppose some application code accepted a location identifier.

type LocationId = string;

function openWeather(locationId: LocationId) {
  // ...
}

Later the contract changed. openWeather could no longer accept any location identifier. It required the canonical location selected after resolving aliases.

Unfortunately:

LocationId = string
CanonicalLocationId = string

From TypeScript's point of view, nothing had happened.

The compiler was correct.

It was proving the wrong thing.

We wanted consumers to acknowledge the semantic change, so we gave the new identifier a distinct type.

type CanonicalLocationId = string & {
  readonly __brand: 'CanonicalLocationId';
};

Suddenly the build failed in several places.

Good.

Each error represented a consumer whose assumption needed to be reconsidered.

The branded type wasn't particularly sophisticated. What interested me was what the failure meant.

We had turned part of an architectural migration into something the compiler could inspect.

A boundary described in documentation is an intention. A boundary that can fail the build has teeth.

One experiment, three teams

The compact layout had started as a single experiment.

compact-feed-cards
      │
      ├── WeatherCard
      ├── NewsCard
      └── SportsCard

This had seemed like sensible reuse.

The three cards were testing roughly the same visual idea, so one flag was simpler than three.

Then the weather implementation was ready.

The news implementation was nearly ready.

Sports had discovered an interaction problem and needed another week.

Nothing was broken. There was no technical incident. We simply couldn't finish the weather experiment without deciding what to do about sports.

The options were not attractive.

We could wait.

We could add special-case logic around the shared experiment.

We could coordinate a partial rollout between teams.

Or we could admit that the experiment wasn't actually one thing.

We split it:

compact-weather-card
compact-news-card
compact-sports-card

Three flags where there had been one.

Less DRY.

The weather team shipped.

A few days later news shipped.

Sports changed its implementation and shipped after that.

The interesting dependency had never appeared in the module graph. There was no import from weather to sports. There was no shared component.

They shared a release decision.

That was enough to couple them.

After that I became less interested in counting dependencies and more interested in looking for things that had to change together.

Sometimes that was an import.

Sometimes state.

Sometimes a server format.

Sometimes an experiment.

Sometimes a release process.

They looked different in code.

Operationally, they behaved rather similarly.

The architecture got worse

After the first few migrations, our architecture diagram looked worse than when we started.

Imagine a feed with sixty card types.

We had migrated four.

It now looked roughly like this:

Feed
 ├── LegacyNewsCard ───── Redux ── Context ── ...
 ├── LegacySportsCard ─── Redux ── Context ── ...
 ├── LegacyFinanceCard ── Redux ── Context ── ...
 │
 ├── WeatherCardAdapter
 │       │
 │       ▼
 │   WeatherCard
 │
 ├── TravelCardAdapter
 │       │
 │       ▼
 │   TravelCard
 │
 └── ...54 more

Before the migration there had been one architecture.

Now there were two.

We had more adapters, more package boundaries and more concepts to explain to somebody joining the project.

Meanwhile product development continued.

A legacy card would gain a feature while we were extracting another card. Occasionally somebody would add a new global dependency to a component we intended to migrate next.

For a while this felt like evidence that the migration was too slow.

The tempting response was to accelerate it.

Take ten cards.

Stop touching them for product work.

Move them together.

Clean up the intermediate abstractions afterwards.

On paper this was much more efficient.

It also meant that instead of learning whether the boundary worked from one card, we would learn after ten.

So we kept the migration deliberately uneven.

Four cards became six.

Six became nine.

The remaining cards stayed exactly as awkward as they had been before.

This had an unexpected benefit.

The new architecture had to earn its keep while surrounded by the old one.

If extracting WeatherCard required changing all sixty cards, the design was not useful yet.

If the new package required every feed to adopt a new state model simultaneously, the design was not useful yet.

If a parser could move only after the entire API response was redesigned, it was not useful yet.

The constraints of incremental migration rejected quite a few elegant ideas for us.

I am grateful for that now.

An architecture that works only after the migration is finished has a bootstrapping problem.

For a large, continuously changing system, the intermediate states are not a brief inconvenience between two architectures.

They are where you live.

Our migration would take months.

For most of that time, the transitional architecture was the architecture.

That changed the question we asked about new abstractions.

Not:

Does this get us to the cleanest final design?

More often:

Does this make the next card cheaper to change without making the remaining fifty-one harder to live with?

That produced smaller steps.

It also meant we could stop.

Had priorities changed after twelve cards, we would still have had twelve cards with clearer ownership and forty-eight functioning legacy cards.

There would have been no half-built platform waiting for the rest of the application to catch up.

The destination still mattered.

The ability to stop on the way mattered more than I had expected.

The card became boring

Eventually WeatherCard became surprisingly uninteresting.

It received data.

It parsed the data it owned.

It managed its local interactions.

It asked the application to perform things outside its boundary.

<WeatherCard
  rawItem={rawItem}
  displayMode="compact"
  savedLocations={savedLocations}
  onSaveLocation={saveLocation}
  onOpenLocation={openLocation}
  onEvent={sendWeatherEvent}
/>

It didn't know which state library the application used.

It didn't know which router it used.

It didn't know where experiments came from.

It didn't know whether it was rendered in the main application, Storybook or a test harness.

The adapter knew considerably more.

                   Application
                        │
       ┌────────────────┼────────────────┐
       │                │                │
     Router          State          Experiments
       │                │                │
       └────────────────┼────────────────┘
                        ▼
                WeatherCardAdapter
                        │
                        ▼
                   WeatherCard

We had not eliminated the complexity.

We had changed where knowledge was allowed to accumulate.

I think that distinction matters.

The files were the easy part

Looking back, moving WeatherCard into packages/weather-card was one of the least interesting things we did.

The package became useful only as other changes accumulated around it.

Dependencies that had been ambient became explicit.

State acquired owners.

Data was interpreted closer to the code that understood it.

Some semantic contracts became compilation failures.

Release decisions that looked shared turned out not to be.

And the old application remained operational while all of this happened.

I started with a fairly mechanical picture of modularity:

one large thing
      ↓
several smaller things

That picture isn't wrong.

It just doesn't say very much.

The question I find more useful now is:

If this part of the system changes, how much of the rest of the system needs to know?

For WeatherCard, the answer gradually became: less.

Not nothing.

Just less.

That turned out to be enough.

Teaching an AI to Review Frontend Code

Sergey — Sat, 29 Aug 2026 09:13:56 +0000

I have been experimenting with AI-assisted code review for a while.

The first attempts were not particularly useful.

They were not wrong, exactly. The reviews found things: a questionable name here, a function that might be extracted there, an opportunity for useMemo, perhaps an any that could be made more precise.

There was plenty of activity.

There was rather less reviewing.

What bothered me was the lack of proportion. A naming suggestion and a possible race condition could appear next to each other as though they deserved roughly the same amount of attention.

They do not.

That observation led to a small experiment.

Instead of asking an AI to find problems in code, I tried to describe how I wanted a review to proceed.

I ended up writing a code-review skill.

This is a story about what went into it, what changed along the way, and what the exercise taught me about code review itself.

The first version was a checklist

This seemed sensible.

Frontend code has plenty of things worth checking:

TypeScript types
React effects
accessibility
error handling
performance
tests
state management
API contracts
naming
duplication

So I wrote them down.

The result was comprehensive.

It was also not very good.

Given enough checklist items, an AI can nearly always find something to say. The difficulty is that software engineering is rarely about finding the largest number of technically defensible observations.

It is about deciding what matters.

Consider a small change:

useEffect(() => {
  fetchUser(userId).then(setUser)
}, [userId])

There are several things one might say about these four lines.

But the interesting question, for me, is what happens when userId changes before the first request completes.

Request A starts for user 10.

The component changes.

Request B starts for user 11.

B completes first.

Then A completes.

The code is still short. The types may still be correct. The linter may be entirely content.

The UI may now be showing the wrong user.

That was the first useful shift in the skill:

Review the behaviour around the code, not merely the code in the diff.

A review needs an idea of what matters

Once I had noticed this, the checklist began to look like the wrong abstraction.

The skill needed priorities.

I eventually wrote this near the beginning:

Review code as a production risk audit, not a style pass.

That sentence became surprisingly useful.

It gives the review a direction.

A resource leak matters before a naming preference.

A broken permission boundary matters before duplicated code.

Losing a user's changes matters before whether a helper should be extracted.

An out-of-order response matters before an unnecessary allocation.

This does not make maintainability, performance or style irrelevant.

It simply gives them somewhere to stand.

The review starts with things that can break user trust or cause the running system to diverge from its intended behaviour: lifecycle leaks, asynchronous races, state integrity, permissions, persistence and other high-impact paths.

That ordering made the reviews noticeably quieter.

I considered that progress.

Contract before implementation

The next problem was more subtle.

How can a reviewer decide whether code is correct without first deciding what the code is supposed to do?

This sounds obvious when written down.

In practice, I had been skipping it.

So the first review gate became Contract.

The contract is not necessarily written in one place. It may be distributed across the pull-request description, types, tests, public exports, documentation, neighbouring code and the vocabulary of the project.

Even the word refactor contains a contract.

If I say:

This is only a refactor.

I am making a fairly strong claim:

Observable behaviour has not changed.

Similarly:

This improves performance.

contains another claim:

There is a measurable improvement, and the relevant behaviour has been preserved.

Once I started treating those statements as claims rather than descriptions, the review changed.

Instead of asking:

Is this implementation good?

the more useful question became:

What has this change promised, and what would convince me that the promise holds?

I like this framing because it removes quite a lot of personal taste from the conversation.

The diff is smaller than the change

Another thing I kept running into was the boundary of the pull request.

A prop changes in one component, but the behavioural change belongs to every consumer.

A query key changes in one hook, but the consequence belongs to the cache.

An API field changes in one type, but the actual surface may run through validation, mapping, persistence and several pieces of UI.

A new option is particularly interesting.

Adding it is easy.

Working out what every existing consumer does when it encounters that option is often where the real review begins.

So I added another gate: Impacted surface.

The instruction is essentially to follow changed values and behaviour through the system: props, state, API payloads, events, permissions, loading states, errors, cache keys, exports and side effects.

This is expensive compared with commenting on the changed lines.

It is also much closer to what I find myself doing when reviewing an important change manually.

The diff tells me where the edit happened.

It does not necessarily tell me where the change happened.

Time deserves its own review

Frontend software has another awkward property: much of its behaviour exists across time.

A component renders, mounts, updates and unmounts.

A request starts, gets cancelled, retries, resolves or becomes stale.

A form is initialised, edited, validated, submitted, rejected, reset and perhaps abandoned halfway through.

Looking at one moment in these processes hides a surprising number of bugs.

So the skill began to describe lifecycles explicitly:

Component
render → hydrate → mount → update → suspend → unmount

Async work
start → cancel → retry → resolve/reject → stale result → cleanup

Form
initialise → edit → dirty → validate → submit → error/success → reset

Data
fetch → normalise → validate → cache → derive → render → mutate → invalidate

These are not meant as universal state machines.

They are prompts for attention.

When an effect changes, I want the review to follow it through unmount.

When a form changes, I want to know what happens after the server rejects the submission.

When caching changes, I want to know how stale data eventually becomes fresh again.

This turned out to be one of the more useful additions.

Evidence changed the tone of the review

There was still a problem.

AI is rather good at producing plausible concerns.

This could cause unnecessary renders.

There may be a race condition here.

Consider memoising this value.

Each sentence sounds reasonable.

None of them is necessarily true.

I did not want to solve this by making the model more confident.

Quite the opposite.

I wanted uncertainty to become part of the output.

That led to the Evidence gate.

A correctness change should have a regression test, or a reason why one is impractical.

A behaviour-preserving refactor should have evidence that the relevant old behaviour still exists.

A performance improvement should have a measurement.

And when the available context cannot establish something, the review should say so.

For example:

I cannot establish whether this request is cancelled when the component unmounts. The caller lifecycle or a focused cancellation test would close that gap.

I find that much more useful than:

Potential memory leak.

The former tells me what is known, what is not known and how to reduce the uncertainty.

The latter mostly tells me that a memory leak is imaginable.

Perhaps unsurprisingly, this also made the reviews less argumentative.

Evidence is easier to discuss than confidence.

Refactoring needed a different rule

At some point I tried using the same skill for refactoring.

That exposed another distinction.

When I ask for a review, I want the system to challenge behaviour.

When I ask for a refactor, I usually want the opposite: improve the implementation while being extremely conservative about behaviour.

So refactoring acquired a rather strict constraint:

Zero behaviour change unless explicitly approved.

Public APIs, execution order, side effects, error semantics and observable identity all matter here.

Even a cleaner implementation is not an improvement if it quietly changes one of them.

This also changed how I think about abstraction.

Two pieces of code looking similar is not sufficient reason to combine them.

I now prefer to ask whether they share a contract and the same edge cases.

If they do, perhaps there is an abstraction.

If they merely happen to contain similar lines today, duplication may be cheaper.

What the skill looks like now

After several iterations, the structure became smaller than the original checklist.

Conceptually, it is roughly:

Contract
   ↓
Impacted surface
   ↓
Failure & divergence
   ↓
Evidence
   ↓
Lower-priority quality

There are specialised expansions underneath it for effects, forms, caches, permissions, dates, APIs, generated files, dependencies and other areas.

But those are secondary.

The sequence is the important part.

It tells the reviewer where to spend attention before telling it what details it might notice.

That distinction took me longer to see than I expected.

I thought I was writing instructions for an AI

The slightly unexpected part of this experiment is that I am no longer sure the skill is primarily about AI.

Writing it forced me to make some of my own review habits explicit.

Why do I sometimes open five files before commenting on one changed line?

Because I am tracing the impacted surface.

Why does an innocent-looking useEffect make me uncomfortable?

Usually because I have not yet accounted for its lifecycle.

Why am I reluctant to approve a refactor even though the new code is obviously cleaner?

Because cleaner is visible in the diff.

Behaviour preserving needs evidence.

Why do some reviews with fifteen comments feel less useful than reviews with one?

Because the number of observations is not the same thing as the amount of uncertainty removed.

I started with a fairly mechanical question:

How should an AI review frontend code?

I ended up with a different one:

What do I actually do when I believe I am reviewing code well?

The skill is my current answer.

I expect it to change.

That may be the most useful property it has.