Architecture | kaguc — Writing to understand systems.

When to adopt the heavy machinery: thresholds, not opinions

Sat, 29 Aug 2026 00:00:00 +0000

Also in 中文. The decision rules for Trading app architecture.

Every article in this series ends with some version of “adopt this when a measurement demands it.” That advice is worthless as stated. It names no metric, no threshold, and no device, which means in practice the decision gets made by whoever argues most confidently in the meeting.

So here are the numbers. Some are arithmetic and hold everywhere. Some are perception research. Some are conventions I’ll label as conventions. Calibrate them to your product — but calibrate numbers, not vibes.

Before that, the correction that matters more than any threshold.

Not everything waits for a threshold

The series implies one decision rule for everything. That is wrong, and it’s the more dangerous half of the mistake, because “we’ll add it when we need it” applied to the wrong category produces a rewrite or a loss.

Sort every candidate into one of two boxes.

Box A — cost of waiting is bounded. You can add it later at roughly the cost of adding it now. Performance work is almost entirely here: an isolate, a binary codec, native ingest, custom painting, feature packages. If you skip it and you were wrong, the symptom is slowness, which is visible, measurable, and fixable next sprint.

Box B — cost of waiting is unbounded. Retrofitting means touching every call site, or the damage has already happened silently by the time you notice. These get built on day one at any scale, and there is no threshold discussion:

Idempotency keys on irreversible actions, persisted before the first send. Retrofit means auditing every mutation path, and until you do, duplicates are already reaching production.
Server-side authorization for every request. A client-trusting endpoint is a breach that exists from the day it ships.
Sequence numbers on any stream where a gap corrupts state. Without them you cannot even detect the corruption retroactively.
Reconnect and resubscribe. Bolting this on later touches every subscription site, and its absence looks exactly like a working app.
Decimal, not binary floating point, for money. 0.1 + 0.2 != 0.3 is a rounding error in a ledger. Migrating a persisted schema off floats is brutal.
An append-only event log for financial actions. You cannot reconstruct history you never recorded.

The test for Box B: if this is missing, is the failure silent, or does it corrupt data, or does it require touching every call site to add? Any yes means day one.

Everything below is about Box A only. That distinction is the actual answer to “when do I use the heavy stuff.”

First, define the target

A threshold needs three things to be meaningful, and most teams state none of them:

A metric with a percentile. Averages hide exactly the problem you care about. One frame in twenty taking 40 ms is invisible in a mean and clearly visible to a human. Use p95 and p99.

A reference device. “Fast on my phone” is not data. Pick a specific mid-range device roughly three years old and make it the gate. A flagship will pass tests that a large share of your users would fail.

A realistic load. Production message rate, production catalog size, and a session at least 30 minutes long — leaks and cache growth are invisible in a two-minute test.

Written out, a usable target looks like: p95 UI frame under 16 ms, and p99 under 24 ms, with 200 visible symbols at the production feed rate, on the reference device, after 30 minutes.

Now a threshold can be violated, which is what makes it a decision rule instead of an opinion.

The frame budget, which is arithmetic

At 60 Hz you have 16.67 ms per frame for everything; at 120 Hz, 8.33 ms. Two threads must both fit: the UI thread (your Dart, build, layout) and the raster thread (painting into pixels).

Budget roughly half the frame for UI-thread work — so about 8 ms at 60 Hz. The rest is layout, paint, raster, and headroom for the spikes that any real system has. If your Dart work routinely exceeds 8 ms per frame, you are one hiccup from a dropped frame, and dropped frames cluster exactly when the app is busiest.

This is why the numbers below are expressed in milliseconds per frame. It’s the only budget that exists.

Thresholds, element by element

Move decoding to an isolate when parsing occupies more than 2–3 ms per frame at p95, sustained, in the DevTools timeline.

Below that it’s noise. Above it you’re spending a third of your UI budget on parsing. But apply the cheaper fixes first (see the ladder below) — and note that messages sent between isolates are copied, so a chatty isolate can be slower than no isolate at all. Send batches, use TransferableTypedData to move bytes without copying, or use Isolate.run, which transfers its result back rather than copying it.

Switch to a binary protocol when any of: JSON parsing still exceeds ~2 ms per frame after conflation; sustained payload exceeds ~100 KB/s on mobile data; or message rate exceeds roughly 1,000/s.

Under those, JSON’s cost is real but not your bottleneck, and it buys you debuggability that a binary format takes away.

Go native (FFI) when Dart cannot meet the budget after isolate and conflation — realistically above ~10,000 messages/second, or for numeric work over large arrays such as computing indicators across 100k+ bars where you need sub-millisecond determinism.

An honest calibration: at a few thousand messages a second, Dart is fine, and the conflation pattern means your render cost is already independent of feed rate. Most products that reach for native here have a conflation problem, not a language problem.

A counter-threshold applies: if nobody on the team can maintain C++ on two platforms, the answer is no regardless of the measurement. An unmaintainable optimization is a liability, and this is the one place where team capability legitimately overrides a number.

Ship a local database when the catalog exceeds roughly 5,000–10,000 rows or ~1 MB, or whenever search must work offline.

There’s a perception argument that usually settles it earlier: interaction feels instantaneous under about 100 ms (Nielsen’s classic thresholds: 0.1 s instant, 1 s uninterrupted flow, 10 s attention lost). Mobile network p95 round-trip rarely fits in 100 ms. So if search-as-you-type must feel instant, local is not an optimization — it’s the only design that meets the requirement.

Custom-paint your charts when a charting package can’t express what you need — synchronized indicator panes, drawing tools, precise crosshair semantics — or above roughly 2,000 rendered elements, or when the series updates at frame rate. Below that, use the library.

Extract feature packages when the team on one codebase reaches about 4–5 developers, or when incremental builds exceed ~60 seconds, or when the same area produces repeated merge conflicts (say 3+ per month), or when a layer needs testing in isolation.

These are conventions, not physics. The underlying variable is coordination cost, and it rises with people, not with lines of code. Conway’s prediction gives the sanity check: modules should number about what your teams number.

Adopt a shared cross-platform core when you have two or more independent client codebases and a body of domain rules where divergence would be a defect. If one team ships both platforms from one Flutter codebase, the sharing already happened; a separate shared core solves a problem you don’t have.

Add-to-app is not a threshold at all — it’s a situation. You adopt it when an existing native app must keep shipping while you migrate. If there’s nothing to embed into, the question is void.

Try the cheap fixes first, in order

Most threshold violations should never reach an architectural change. Work down this ladder and stop at the first rung that fixes it:

Do less work. Smaller payloads, fewer fields, LIMIT on queries, pagination, fewer visible items. Usually the biggest win and always the cheapest.
Do it less often. Conflate, debounce, cache, memoize. Frame coalescing alone converts many “we need native” situations into non-problems.
Do it in a smaller scope. Narrow the rebuild, split the repaint layer, invalidate less.
Do it elsewhere. Move to an isolate or to the server.
Do it in a faster language. Native, FFI.

Rung 5 is where most of this series’ “heavy machinery” lives, and reaching it before trying 1 through 4 is the most common way teams end up with a complicated architecture and the same performance.

When not to adopt, even past the threshold

Four counter-signals, each of which should stop you:

You can’t operate it. Certificate pinning without a rehearsed rotation and a kill switch is a self-inflicted outage waiting for a cert to expire. Native code without a maintainer is a bug you can’t fix. Capability to run a thing is part of its cost.

The trigger was a spike, not a level. One bad day at market open is not a threshold crossing. Require the violation to be sustained — over a week of real usage, not one profiling session.

A cheaper rung is untried. If you haven’t done 1 through 4 above, you don’t yet know whether you have a problem or a workload.

It’s a one-way door. Reversible decisions deserve fast, cheap deliberation; hard-to-reverse ones deserve more. A binary protocol you can revert in an afternoon is a two-way door. A persisted schema, a public API contract, or a native module three teams now depend on is not — those deserve the slow version of this process.

The procedure

Write the target before you need it: metric, percentile, reference device, load.
Measure under realistic conditions. Not a synthetic benchmark, not a flagship phone.
If violated, walk the ladder from rung 1.
If the ladder is exhausted and the violation is sustained, adopt — and check the four counter-signals first.
Record the decision: what triggered it, what you measured, what you’d need to see to reverse it. Six months later this is the difference between an architecture and an accretion.

Step 5 matters more than it looks. Most bad architecture isn’t a bad decision; it’s a decision nobody can re-examine because the reasoning was never written down.

So is the MVP the whole story?

No — and it shouldn’t read as the ceiling. The reference MVP is the correct starting point for its constraints, and the upgrade table there names the seams. This article supplies the numbers that fire each upgrade. Together they describe a path, not a destination.

Roughly, four tiers, so you can locate yourself:

Tier	Load and team	What it runs
1	<10 updates/s, 1–2 devs	One codebase, REST + WebSocket, JSON, in-memory cache, chart library
2	~100 updates/s, 2–5 devs	+ frame conflation, local catalog DB with delta sync, custom chart painter
3	~1,000 updates/s, several teams	+ decode isolate, binary codec, feature packages, shared domain core if two codebases
4	10,000+ updates/s, many teams, regulated	+ native ingest, custom transport, module registry, full audit and reconciliation

Two things are worth noticing about that table. Every tier is a superset of the previous one, which is what makes the path walkable — nothing is thrown away, seams are filled in. And Box B from the top of this article applies at every tier, including tier 1. A one-developer app that places real orders needs idempotency keys and server-side authorization exactly as much as a tier-4 system does.

That’s the whole judgment framework: correctness has no threshold; performance does; and the threshold is a number on a reference device, not an opinion.

References

API and renderer claims checked against Flutter 3.47.0 / Dart 3.13 (August 2026).

J. Nielsen, “Response Times: The 3 Important Limits”, 1993 — 0.1 s, 1 s, 10 s.
J. Dean, L. A. Barroso, “The Tail at Scale”, CACM 56(2), 2013 — why percentiles, not averages, describe what a user experiences.
J. Bezos, Amazon 2015 Letter to Shareholders, 2016 — Type 1 (one-way door) vs Type 2 (two-way door) decisions.
M. E. Conway, “How Do Committees Invent?”, Datamation, 1968 — system structure mirrors the communication structure of the organization that built it.
D. Goldberg, “What Every Computer Scientist Should Know About Floating-Point Arithmetic”, ACM Computing Surveys 23(1), 1991 — why binary floating point cannot represent decimal money.
Dart docs, Isolates — messages are copied between isolates; Isolate.run transfers its result instead. See also TransferableTypedData.
Flutter docs, Use the Performance view — UI and raster timelines, frame budget, and the rebuild counter.

Back to the overview · The concrete starting point: reference MVP

A reference design: quotes and watchlist MVP in Flutter

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. The closing part of Trading app architecture.

The preceding articles each argue a mechanism. This one commits to a design: a market-data app with search, watchlists, and charts, built by two or three people, with trading added later.

Committing matters. It’s easy to write “it depends”; the useful artifact is a specific plan, the reasoning that produced it, and an explicit account of what it refuses to build.

The constraints, stated honestly

Before choosing anything, the six magnitudes from the overview, answered for this product:

Constraint	Our magnitude
Freshness	1-second quotes, a few hundred visible symbols
Irreversibility	none in v1 — read-only
Catalog	~150k instruments, searchable offline
Platforms	iOS + Android, one small team
Teams	one
Threat	public market data; user accounts in v2

Five of six are small. That decides most of the architecture, and it decides it in the direction of less.

The design

WebSocket ──▶ decode (Dart) ──▶ FrameCoalescer ──▶ QuoteStore ──▶ leaf widgets
 │
REST ──▶ catalog delta sync ──▶ SQLite (bundled snapshot) ──▶ search

Transport. One WebSocket for live quotes, REST for everything else. JSON at this rate is fine; a binary codec is a later optimization, not a starting decision.

Ingest. Decode on the UI isolate to begin with. At a few hundred messages a second this measures in microseconds. Move it to an isolate the day the profile says so — not before.

Conflation. The FrameCoalescer from the state article sits between the socket and the store. This one is worth building on day one even at low rates: it is thirty lines, and it makes the render cost independent of the feed rate permanently.

State. Per-symbol ValueNotifiers in a QuoteStore; leaves subscribe individually. Page-level state can be whatever you like — the granularity discipline only matters on the hot path.

Catalog. A prebuilt SQLite file shipped as an asset, copied on first run, delta-synced by version, searched via FTS with pinyin and initials columns, per the offline article.

Charts. CustomPainter with a static layer and a live layer in separate repaint boundaries. Use a charting package first if it fits; write your own when you need indicator panes or drawing tools.

Structure. One package with clear folders. Not a monorepo — see below.

What we deliberately do not build

This list is the actual content of the design. Anything can be added; the discipline is in the sequencing.

No native code, no FFI. A 1 Hz feed does not justify a boundary that costs you stack traces and two toolchains.
No custom binary protocol. JSON over WebSocket until payload size or parse time is measurably a problem.
No shared cross-platform core. One Flutter codebase already covers both platforms; a shared domain layer solves a problem we don’t have.
No package-per-feature monorepo. One team, one app: package boundaries would be overhead, not enforcement.
No add-to-app. Nothing to embed into.
No certificate pinning. Public data, and pinning is an operational commitment we cannot yet honor. Standard TLS, done properly.
No order state machine. No orders. When they arrive, that article becomes mandatory reading, not optional.

Every line is a decision we can reverse. That is the point of writing them down: someone will propose each one, and the answer should be “not yet, and here’s what would change my mind.”

Build order

Phase 1 — catalog and search. Ship the snapshot, build search, list instruments. No live data yet. This proves the largest, least reversible asset (the database and its sync) before anything depends on it.

Phase 2 — live quotes. WebSocket, coalescer, per-symbol notifiers, watchlist screen. Now the reactive path exists end to end. Reconnect with backoff and resubscribe from the start; retrofitting reconnection is painful because it touches every subscription site.

Phase 3 — charts. History over REST, custom painter, two layers. The first screen where raster-thread performance matters, and the first place you profile on a mid-range device.

Phase 4 — accounts and orders. Auth, then the full order reliability design: idempotency keys persisted before send, an unknown state, reconciliation on reconnect. This phase changes the threat model, so the security article applies from its first commit.

Phases 1-3 have no irreversible actions, which is why they can move fast. Phase 4 is where care stops being optional, and it deserves a slower cadence.

The upgrade path

The design’s real quality is not what it does now but where it can grow without a rewrite. Each heavy element has a defined seam and a measured trigger:

Element	Where it plugs in	Adopt when
Isolate for decode	behind the feed interface	UI-thread profile shows decode in frame budget
Binary protocol	codec inside the feed	payload size or parse time measurably hurts
Native/FFI ingest	replaces the feed implementation	conflation in Dart can’t keep up — likely never at this rate
Feature packages	extract from folders	two people repeatedly collide, or a layer needs isolated tests
Shared domain core	extract `domain/`	a second client appears that must not diverge
Order machinery	new module	the first irreversible action ships

The seams are what you design deliberately today: a feed exposed as an interface rather than a concrete socket class, catalog access behind a repository, and business rules kept out of widgets. None of those cost anything now, and each one is what makes a later change an extraction instead of a rewrite.

The one thing to keep

If a reader takes a single idea from this series: write down your six magnitudes before you choose anything, then adopt each heavy element on the day a measurement demands it.

Large architectures are not more advanced. They are the same constraints at full size, plus years of accumulated migration state. Copying one early means paying its coordination costs with none of its scale — which is the most common and most expensive mistake in this whole subject.

References

API and renderer claims checked against Flutter 3.47.0 / Dart 3.13 (August 2026).

M. Fowler, “Yagni”, 2015 — the cost of a presumptive feature is not only building it but carrying it.
D. McKinley, “Choose Boring Technology”, 2015 — innovation tokens, and why JSON over a WebSocket is the right first answer.
J. Bezos, Amazon 2015 Letter to Shareholders, 2016 — Type 1 (one-way door) vs Type 2 (two-way door) decisions.

Previous: Flutter project structure · Back to the overview.

Channels, Pigeon, and FFI: crossing to native without paying per tick

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Flutter implementation notes for Trading app architecture; see also the cross-platform boundary.

There are three ways out of Dart, and they are not interchangeable. Choosing well is less about performance benchmarks than about matching the mechanism to how often you cross and what you need on the other side.

The three mechanisms

Platform channels (MethodChannel, EventChannel) send messages through the engine to platform code. They are asynchronous, they serialize arguments through a codec, and they hop threads. That makes them ideal for platform capabilities — permissions, the camera, biometrics, share sheets — where calls are occasional and the work is on the platform side anyway. Cost is dominated by the per-call overhead, not by argument size.

Pigeon is code generation on top of channels. You declare an interface once, and it generates typed Dart and platform code. The runtime cost is the same as a hand-written channel; what you get is the elimination of an entire class of bug — misspelled method names, mismatched argument shapes, silent type coercion — that channels invite because they are stringly typed and untyped in both directions. If you have more than a couple of channel methods, use it.

dart:ffi calls C directly. It is synchronous, has no serialization, and can share memory with Dart via typed data. It is the only option when you need to touch a native library’s API surface directly or move large buffers cheaply. The catch is exactly its virtue: a synchronous call runs on the calling isolate, so a slow FFI call blocks whatever isolate invoked it — and if that’s the UI isolate, you have dropped frames. As of Flutter 3.47 / Dart 3.13 (August 2026), the supported way to bundle the native side is a build hook (hook/build.dart) in an FFI package — flutter create --template=package_ffi, recommended since Flutter 3.38 — which replaces the old per-platform plugin scaffolding for C code.

The number that decides it

The cost of crossing is paid per call. This one fact settles most designs.

A feed delivering 5,000 messages a second, marshalled individually over a channel, is 5,000 serialization round trips and thread hops per second — and it will be slower than doing all the work in Dart, despite native code being “faster.” You would have paid thousands of transitions to save some decoding.

The same feed, decoded and conflated natively with Dart reading a snapshot once per frame, is 60 crossings a second carrying a batch. Same data, two orders of magnitude fewer boundary costs.

So the rule is the one from the pipeline article, stated for Flutter: cross on the frame, never on the tick. Design the native interface as a small number of coarse operations that move a batch, not as a stream of individual events or a set of property getters.

A concrete shape for a high-rate feed

If you do end up with native ingest, the interface that works looks like this: native owns the socket, decodes, detects gaps, and maintains a current-value table. Dart asks for what changed since it last looked.

final class QuoteBridge {
 QuoteBridge(this._lib);
 final NativeLib _lib;

 /// Copies changed quotes into a reusable buffer. One crossing per frame.
 int drainInto(Float64List out) => _lib.drain(out.address, out.length);
}

Two properties matter here. The buffer is reused rather than allocated per call, so you are not creating garbage 60 times a second. And the call returns a count into a preallocated region rather than constructing objects across the boundary, because allocating Dart objects from native code per element reintroduces the per-item cost you were avoiding.

Then keep the FFI call off the UI isolate if it can ever be slow:

// Long-running or blocking work belongs on its own isolate.
final decoded = await Isolate.run(() => heavyDecode(bytes));

For native code that needs to call into Dart — a completion callback, a push notification from the feed — use NativeCallable, which gives you a function pointer that safely re-enters the Dart isolate. Do not try to invoke Dart from an arbitrary native thread without it.

Memory ownership must be explicit

FFI removes the serialization boundary, and with it the automatic memory management you were implicitly relying on. Decide and document, for every buffer crossing the line, who allocates and who frees.

The two patterns that hold up:

Dart allocates, native fills. Dart owns a typed-data buffer for its whole lifetime and passes it down. Simplest, and my default — there is no ambiguity about lifetime.
Native allocates, Dart frees explicitly. Wrap it so release is not optional: using((arena) { ... }) for scoped allocations, or attach a NativeFinalizer so a dropped Dart object releases its native peer.

The failure here is not a crash you catch in testing. It’s a slow leak that shows up as a memory graph climbing over an hour of use, which is precisely the session length you never test.

EventChannel has no backpressure

Worth stating on its own, because it surprises people: an EventChannel fed faster than Dart consumes will queue. There is no built-in mechanism for the consumer to say “slow down,” so a fast native producer turns into unbounded buffering and then a memory problem. (The symptom is on record as far back as flutter/flutter#33640: a native producer feeding an EventChannel continuously, and memory climbing at a steady rate.)

If native is the producer of a high-rate stream, conflate on the native side and let Dart pull, or push at a rate you control (once per frame) rather than at the rate data arrives. Applying backpressure is the producer’s job here because the transport won’t do it for you.

Choosing, briefly

Occasional platform capability → Pigeon-generated channel. Type safety is free; the call rate is irrelevant.
A handful of calls, no codegen appetite → a plain MethodChannel is fine. Keep the method surface small.
Large buffers, or a native library you must talk to directly → FFI, with explicit ownership and a helper isolate for anything slow.
High-rate stream → native conflates, Dart drains once per frame over FFI. Never per-message channels.
Anything you can do in Dart at acceptable cost → do it in Dart. The boundary is a permanent tax on debugging, crash reporting, and build complexity, and it should be justified by a measurement rather than an intuition about speed.

That last one is the most common mistake. A stack trace stops at the boundary, your crash reporter needs separate symbol uploads for each side, and a reproduction now involves two toolchains. Cross when the profile says to, and not because native feels faster.

References

API and renderer claims checked against Flutter 3.47.0 / Dart 3.13 (August 2026).

Flutter docs, Writing custom platform-specific code — MethodChannel / EventChannel, codecs, and threading rules.
pigeon on pub.dev — typed code generation over platform channels.
Dart docs, C interop using dart:ffi — @Native, NativeCallable, NativeFinalizer, and Arena / using.
Flutter docs, Bind to native code using FFI and Dart docs, Hooks — hook/build.dart and the package_ffi template.
Dart docs, Isolates — messages are copied between isolates; Isolate.run transfers its result instead. See also TransferableTypedData.
flutter/flutter#33640 — steady memory growth from a native producer feeding an EventChannel faster than Dart consumes.
J. Waldo, G. Wyant, A. Wollrath, S. Kendall, “A Note on Distributed Computing”, Sun Microsystems Laboratories TR-94-29, 1994 — a boundary between address spaces cannot be papered over; latency and partial failure are paid per call.

Previous: Flutter under a firehose · Next: Charts and custom painting

Charts in Flutter: custom painting that holds 60fps

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Flutter implementation notes for Trading app architecture.

Most Flutter performance advice is about the UI thread: fewer rebuilds, smaller subtrees. A chart moves the problem to the raster thread, where the question is not how many widgets you built but how much work you asked the GPU to do, and how often.

Don’t compose a chart out of widgets

The instinct is to make each candle a widget. Six hundred candles then become six hundred widgets to build, lay out, and paint, plus their parents — and every pan gesture redoes all of it.

A chart is one drawing, not many objects. Use a single CustomPainter and draw into a canvas. You give up the framework’s layout and hit-testing for that region, and in exchange you get a cost proportional to pixels rather than to elements, plus complete control over what happens per frame.

The widget tree remains the right tool for the toolbar, the legend, and the crosshair readout. It is the wrong tool for the series itself.

`shouldRepaint` is the whole game

This is the method that decides whether your chart is cheap or ruinous, and returning true — the safe-looking answer — means repainting on every frame forever.

class CandlePainter extends CustomPainter {
 CandlePainter({required this.series, required this.viewport, required this.revision});
 final CandleSeries series;
 final Viewport viewport; // pan/zoom
 final int revision; // bumped when series data changes

 @override
 bool shouldRepaint(CandlePainter old) =>
 old.revision != revision || old.viewport != viewport;
}

Compare a cheap version counter rather than the data itself. Deep-comparing a few thousand candles on every frame is its own performance problem, and identity comparison silently fails the moment you mutate a list in place. A monotonic revision that you bump on every data change is unambiguous and free.

Split static from live

Within one chart, different parts change at wildly different rates. Grid lines, axis labels, and completed candles change when you pan or when a bar closes. The last price line, the crosshair, and the in-progress candle change constantly.

Painting them together means the live element forces a repaint of everything.

So stack two painters, each in its own RepaintBoundary:

Stack(children: const [
 RepaintBoundary(child: CustomPaint(painter: StaticChartPainter(...))), // grid, closed candles
 RepaintBoundary(child: CustomPaint(painter: LivePainter(...))), // last price, crosshair
])

Now a tick repaints a layer containing a couple of lines. The expensive layer — thousands of candles and text labels — is cached as a texture and composited, not redrawn.

This is the single highest-leverage change in most chart implementations, and it follows the same principle as scoping rebuilds on the UI thread: make the invalidated region match the thing that changed.

Don’t allocate inside `paint()`

paint() may run 60 times a second. Everything created there becomes garbage at that rate, and GC pauses are precisely the tail-latency problem you are trying to avoid.

Hoist Paint objects to fields. Reuse Path objects with reset() instead of constructing new ones. Precompute your data-to-pixel transform once per paint rather than per candle. And for large point counts, prefer the batch primitives — drawRawPoints, drawVertices, or a single Path — over thousands of individual drawLine calls, since each canvas call carries overhead that dominates when the shape is tiny.

Text is the hidden cost

Axis labels and price scales look free and are not: laying out text is one of the more expensive operations in a paint pass, and doing it for forty labels every frame will show up in your raster timings.

Cache TextPainter instances keyed by the string, and rebuild them only when the label set changes. Since price and time labels repeat heavily across frames, a small map gets you most of the way.

Interaction: transform the canvas, not the data

Pan and zoom should change a viewport (an offset and a scale) that you apply to the canvas, not rewrite your data:

canvas.save();
canvas.translate(-viewport.offsetX, 0);
canvas.scale(viewport.scaleX, 1);
// draw in data space
canvas.restore();

Recomputing pixel positions for every candle on every gesture frame is the common cause of chart panning that feels heavy. Keep the model in data coordinates and let the canvas transform do the work.

Hit testing runs the other way: convert the pointer position into data coordinates and binary-search the series for the nearest bar. That is a log-n lookup per gesture event instead of a scan.

Shader compilation, briefly

Historically, the first frame that used a new shader could compile it on the spot and drop that frame — the classic “janks once, then never again” bug that only reproduces on a fresh install. Impeller — as of Flutter 3.47 (August 2026) the only renderer on iOS and the default on Android API 29+ — compiles shaders ahead of time and removes this class of stutter. Older Android devices still fall back to the OpenGL/Skia path, so if you support them, test a fresh install there.

The practical guidance is short: stay on Impeller, and keep effects conventional. Exotic blend modes, large blurs, and heavy Opacity over complex subtrees are still expensive on any backend, because they force offscreen render passes. Opacity around a big subtree is the one most often reached for by accident — prefer opacity baked into a Paint color when you are painting anyway.

Measure the raster thread

Open the DevTools performance view and watch the two timelines separately. If UI frames are fine and raster frames are long, the fix is in this article: fewer layers, smaller invalidated regions, cheaper paint operations. If UI frames are long, your problem is upstream in the widget tree and belongs to the state article.

Test with a realistic series — a few thousand bars — on a mid-range device. A chart that is smooth with 50 candles on a flagship tells you nothing about the case that matters.

When to just use a library

If you need a standard line or bar chart that updates a few times a minute, a charting package is the right answer and everything above is premature.

Write your own when you need behavior the library does not have: synchronized indicator panes, custom drawing tools, precise crosshair semantics, tens of thousands of points, or ticking updates at frame rate. Those requirements are what justify owning a painter — not the belief that custom code will be faster in general.

References

API and renderer claims checked against Flutter 3.47.0 / Dart 3.13 (August 2026).

Flutter docs, Impeller rendering engine — the only renderer on iOS; default on Android API 29+ with an OpenGL fallback below; default on desktop since 3.47.
Flutter docs, Shader compilation jank — the first-run stutter, and Impeller as the fix.
Flutter API, CustomPainter and RepaintBoundary — shouldRepaint semantics and layer isolation.
Flutter docs, Performance best practices — const widgets, RepaintBoundary, itemExtent, and why Opacity and saveLayer are expensive.
Flutter docs, Use the Performance view — UI and raster timelines, frame budget, and the rebuild counter.

Previous: Channels, Pigeon, and FFI · Next: Offline storage and local search

Flutter project structure: packages, boundaries, and add-to-app

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Flutter implementation notes for Trading app architecture; the principle is in Modularity and migration.

Folder conventions do not create boundaries. A lib/features/ directory is a suggestion, and any file can import any other file across it. Once more than a few people work in a codebase, suggestions stop holding.

Dart packages are the smallest unit where a boundary is actually enforced — a package cannot import what it doesn’t declare. That is the whole reason to reach for them.

A package per feature

apps/
 trading_app/ # composition root: wiring, routes, flavors
packages/
 design_system/ # tokens, components, theme
 domain/ # entities, value objects, rules — no Flutter import
 data/ # repositories, api client, database
 feature_quotes/
 feature_watchlist/
 feature_orders/

One rule makes this work: features depend on domain, data, and design_system; features never depend on each other; only the app depends on features.

That single constraint is what buys you anything. It means a feature can be developed, tested, and deleted in isolation; that a change to feature_orders cannot break feature_quotes by construction; and that your build system can compile and test them in parallel.

The corollary that people resist: if two features need the same thing, it belongs in domain or a shared package — not imported sideways. Sideways imports are how a modular codebase quietly becomes a monolith with extra pubspec.yaml files.

Keep domain free of Flutter entirely. It should be plain Dart: entities, rules, and the interfaces the outside world implements. That makes it fast to test without a widget binding, and it means the business logic could outlive a UI framework change — the practical form of dependency inversion.

Enforce the rule with a tool

A boundary nobody checks is a boundary that erodes in the first busy sprint. Make violations fail CI.

The cheap version is a lint that forbids importing across features, using custom_lint or an analysis option banning specific import paths. The cheaper version still: because features are separate packages, an undeclared import is already a compile error — you get most of the enforcement for free simply by not putting everything in one package.

Add a check that no package depends on the app, and that domain depends on nothing but Dart. Both are one-line rules that catch real architectural drift.

Routing as a registry

If the app imports every feature’s screens directly, adding a feature means editing the app, and the app becomes the coupling point you tried to avoid.

Instead have each feature expose its routes, and let the app compose them:

// in feature_quotes
final quotesRoutes = <RouteDef>[
 RouteDef('/quotes/:symbol', (ctx, args) => QuoteDetailPage(symbol: args['symbol']!)),
];

// in apps/trading_app
final router = AppRouter([
 ...quotesRoutes,
 ...watchlistRoutes,
 ...ordersRoutes,
]);

Navigation between features then goes through paths rather than through imported widget classes, which is what keeps features from depending on each other while still being able to link to one another. It also gives deep links a single place to be validated — and per the security article, an incoming link must be treated as hostile input and re-checked at the destination, not trusted because it arrived.

Composition at the root only

Dependency injection belongs in the app package. Features declare what they need in constructors; the root builds the object graph.

// apps/trading_app/lib/bootstrap.dart
final db = await openCatalog();
final api = ApiClient(baseUrl: env.apiUrl);
final quotes = QuoteRepository(api: api, db: db);
runApp(App(quotes: quotes));

Reaching for a global service locator from inside a feature undoes this: the feature now has a hidden dependency that doesn’t appear in its constructor, cannot be substituted in a test without global setup, and makes the package non-portable. A locator at the composition root is fine. A locator called from a widget deep in a feature is a global variable with good manners.

Add-to-app, and what it costs

If you are embedding Flutter into an existing native app — the strangler-fig migration — there are four costs to plan for.

Engine startup. The first Flutter screen pays engine initialization. Pre-warm a cached engine during app start so the first navigation isn’t the moment the user waits.

Multiple engines. FlutterEngineGroup lets additional engines share the snapshot and most of the memory cost, which makes several live engines viable where independent engines would not be. It is still not free — prefer one engine with internal routing unless you genuinely need isolated screens.

Two navigation stacks. The native stack and Flutter’s router both exist, and the back button must behave sensibly across the seam. Decide early who owns the stack for a given flow, and route all back handling through that decision rather than patching cases as they surface.

Duplicated state. Session, theme, and locale now live on both sides. Make one side authoritative and push changes across a single channel; do not let both sides maintain their own copy and hope they agree.

Pass initial route and arguments when creating the engine, and return results through one narrow channel rather than several ad-hoc ones — the coarse-boundary rule from the channels article applies to navigation too.

When this is too much

For one to three developers on a single app, this structure is overhead: more pubspec.yaml files, more version wrangling (pub workspaces, Dart 3.6+, remove most of that — one resolution and one lockfile for the repo — but not the rest), slower cold builds, and indirection with nothing on the other side of it.

Start with one package and folders. Extract a package when a boundary starts to hurt — you want to test a layer without a widget binding, two people keep colliding in the same area, or you need to reuse something in a second app. Those are observations. “We might grow” is not, and a small team maintaining a large team’s structure pays coordination costs for an organization it doesn’t have.

References

API and renderer claims checked against Flutter 3.47.0 / Dart 3.13 (August 2026).

Dart docs, Pub workspaces (Dart 3.6+) — one resolution and one lockfile across the packages of a monorepo.
custom_lint on pub.dev — project-specific lints, including import-boundary rules, that fail CI.
R. C. Martin, “The Clean Architecture”, 2012 — the dependency rule: source dependencies point inward, toward policy.
D. L. Parnas, “On the Criteria To Be Used in Decomposing Systems into Modules”, CACM 15(12), 1972 — a module should hide a decision that is likely to change.
M. Fowler, “Inversion of Control Containers and the Dependency Injection pattern”, 2004 — dependency injection vs service locator, and what each costs in testability.
Flutter docs, Add Flutter to an existing app and Multiple Flutter instances — engine warm-up, FlutterEngineGroup, and the cost of several live engines.

Previous: Offline storage and search · Next: A reference design for a quotes MVP

Flutter under a firehose: making rebuild scope match change scope

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Flutter implementation notes for Trading app architecture; the principle behind it is in Real-time data pipelines.

Put 300 symbols on screen, each updating a few times a second, and the standard Flutter approach falls over. Not because Flutter is slow — because the standard approach rebuilds a subtree proportional to the screen on every change proportional to a single cell.

The fix is one idea applied ruthlessly: the rebuilt subtree should be as small as the thing that changed. Everything below is a consequence.

Why the ordinary way fails

The usual shape is a store holding a map of quotes, exposed to the tree, with the list watching it. One tick arrives, the store notifies, and the list rebuilds — 300 rows, each with a handful of widgets, so a thousand-plus build() calls for one number that moved.

At 60 fps you have 16.6 ms per frame for everything: build, layout, paint, raster. A few hundred ticks a second against a screen-sized rebuild will not fit, and the symptom is the worst kind — it’s fine in development with mock data and janky exactly when the market is interesting.

Note that this is not a criticism of any particular state management package. Provider, Bloc, Riverpod, and setState all behave correctly here; the problem is that the granularity was chosen wrong. You can build this badly with any of them, and well with most of them.

Rebuild only the leaf

Give each symbol its own listenable, and let the widget that displays it be the only thing subscribed.

class QuoteStore {
 final _notifiers = <String, ValueNotifier<Quote>>{};

 ValueListenable<Quote> listen(String symbol) =>
 _notifiers.putIfAbsent(symbol, () => ValueNotifier(Quote.empty(symbol)));

 // called from the feed, many times per second
 void apply(Quote q) {
 final n = _notifiers[q.symbol];
 if (n == null) return; // nobody is showing it — do no work
 if (n.value == q) return; // no visible change — do no work
 n.value = q; // notifies exactly one subtree
 }
}

class PriceCell extends StatelessWidget {
 const PriceCell(this.store, this.symbol, {super.key});
 final QuoteStore store;
 final String symbol;

 @override
 Widget build(BuildContext context) => ValueListenableBuilder<Quote>(
 valueListenable: store.listen(symbol),
 builder: (_, q, __) => Text(q.last.toStringAsFixed(2)),
 );
}

The row, the list, and the page never rebuild. A tick for AAPL rebuilds one Text. The cost of an update is now proportional to what changed rather than to what is on screen — which is the property you were after.

Two details in apply() do a lot of work. Skipping symbols nobody is displaying turns an off-screen subscription leak into a no-op, and the equality check absorbs the very common case of a message that carries no visible change.

Conflate onto the frame, not onto the tick

Rebuilding one leaf per tick is cheap, but 20 ticks per second per symbol is still 19 wasted rebuilds — the screen only shows 60 frames, and a human perceives far fewer.

So buffer incoming ticks and flush once per frame:

class FrameCoalescer {
 FrameCoalescer(this._flush);
 final void Function(Iterable<Quote>) _flush;
 final _pending = <String, Quote>{}; // keyed: last one wins
 bool _scheduled = false;

 void add(Quote q) {
 _pending[q.symbol] = q; // conflation, for free
 if (_scheduled) return;
 _scheduled = true;
 SchedulerBinding.instance.scheduleFrameCallback((_) {
 _scheduled = false;
 final batch = _pending.values.toList(growable: false);
 _pending.clear();
 _flush(batch);
 });
 }
}

The map does the conflation: ten ticks for one symbol between two frames collapse to one, automatically, because a later write replaces an earlier one under the same key. This is the register case from the pipeline article expressed in nine lines.

Now your update rate is bounded by the frame rate no matter what the market does. A volatile open costs slightly more decoding and exactly the same rendering.

Keep the list itself cheap

Even with perfect leaf updates, the list can undo your work:

ListView.builder with itemExtent. A known extent lets Flutter skip measuring children to compute scroll geometry — a large win for uniform rows.
const constructors everywhere they’re possible. A const widget is skipped during rebuild instead of being reconstructed and compared.
RepaintBoundary around independently-animating cells, so a flashing price cell doesn’t dirty the whole list’s layer. Use it deliberately: each boundary is a layer, and hundreds of them cost memory.
Hoist the notifier lookup. Calling listen(symbol) inside build() is fine when it’s a cheap map read, but never create the notifier during build if creating it has side effects like subscribing upstream.

Screen visibility should drive subscriptions, or you will pay for data nobody is looking at:

@override
void initState() {
 super.initState();
 _sub = feed.subscribe(widget.symbols); // reference-counted upstream
}

@override
void dispose() {
 _sub.cancel(); // last listener → unsubscribe
 super.dispose();
}

Reference-count in the feed so two widgets showing the same symbol produce one upstream subscription, and the subscription ends when the second one goes. Combine that with app lifecycle: on AppLifecycleState.paused, drop to a slow summary or stop entirely.

Measure the right thread

Flutter has two threads that matter, and they fail differently. The UI thread runs your Dart: build, layout, and the framework. The raster thread turns the result into pixels.

Everything above targets the UI thread. If DevTools shows the raster thread as the bottleneck, rebuild scope is not your problem — you have expensive painting, too many layers, or shader compilation, which is the chart article’s territory.

Use the DevTools rebuild counter to confirm what you assume: put the app under a realistic feed, watch which widgets rebuild, and check the count matches the number of things that actually changed. When those two numbers agree, this problem is solved.

When to skip all of it

If your data changes every few seconds, a single stream feeding one StreamBuilder at the top of the page is correct and this article is overhead. Per-symbol notifiers, frame coalescing, and repaint boundaries are what you reach for when a measurement says a screen-sized rebuild no longer fits in a frame — not before.

References

API and renderer claims checked against Flutter 3.47.0 / Dart 3.13 (August 2026).

Flutter docs, Performance best practices — const widgets, RepaintBoundary, itemExtent, and why Opacity and saveLayer are expensive.
Flutter docs, Flutter architectural overview — the UI and raster threads, and what runs on each.
Flutter API, ValueListenableBuilder and SchedulerBinding.scheduleFrameCallback — the two primitives the leaf-rebuild and frame-coalescing patterns are built on.
Flutter docs, Use the Performance view — UI and raster timelines, frame budget, and the rebuild counter.

Next in the Flutter notes: Channels, Pigeon, and FFI — how to cross to native without paying per tick.

Local-first data: snapshots, deltas, and the two kinds of state

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Part 3 of Trading app architecture.

An app that deals with a large domain holds two kinds of data, and they have nearly opposite properties:

Reference data is the catalog of things that exist — instruments, exchanges, currencies, precision rules. It is large, changes slowly, and is mostly appended to. A user expects to search it instantly, including with no network.

Live data is the current value of things — prices, positions, balances. Each item is tiny, changes constantly, and is worthless when stale.

Most difficulty in “sync” comes from pushing both through one mechanism. Split them and each becomes tractable: live data is a stream (the previous part), and reference data is a replication problem with an unusually easy shape.

Why the catalog belongs on the device

The requirement “search must be instant, always” cannot be met by a network call. Not because a network call is slow on average, but because its worst case is unbounded — and search is judged on the worst case, in an elevator, on a train.

So the device holds the catalog and the network becomes an enhancement rather than a dependency. This is what local-first means in practice: the local copy is good enough to work from, and the network’s job is to make it fresher, not to make it exist.

That inverts the usual failure story. A conventional client is broken while offline. A local-first client is merely stale while offline, and staleness in a slow-changing catalog is often unobservable. The difference in perceived quality is large and it costs you very little, because the underlying data was never fast-moving to begin with.

Snapshot plus deltas, keyed by a monotonic version

The mechanism is small:

The server keeps a monotonically increasing version for the catalog. Every change bumps it. The client stores the version it has reached and asks a single question on launch: what has changed since version n? The server returns the deltas; the client applies them and records the new high-water mark.

That question is the entire protocol, and it has properties worth naming:

Resumable. An interrupted sync loses nothing. You resume from the last version you fully applied — so apply the batch and update the marker in one transaction, or you will eventually skip a delta.
Idempotent. Re-applying a range you already have is harmless if deltas are expressed as upserts and tombstones rather than in-place mutations.
Cheap to verify. Two integers tell you whether a client is current.

This is why the catalog is the easy side of cache invalidation. Invalidation is hard when you must guess whether a cached thing is still valid. Here you never guess: the version answers it exactly, and the data is append-mostly, so the answer is usually “add these few rows.”

Two versions must not be conflated: the data version (how fresh the contents are) and the schema version (what shape the local store is in). App updates change the schema; server changes bump the data. Store and migrate them separately, or one upgrade will make you discard a database you only needed to add a column to.

Shipping the snapshot inside the app

You can start every user at version zero and download the catalog on first launch — a few hundred thousand rows over a mobile network, before they can search anything.

Or you ship a snapshot inside the binary and start them at the version it was built at. First launch, first search, works offline, no spinner.

The trade is install size against first-run experience, and for a catalog that is genuinely required for the product to function, the snapshot usually wins. It is a deliberate exchange of bytes users download once, in the background, from an app store built for it, against a fragile network moment at the least forgiving point in the product.

The catalog then only ever gets deltas. A user who installs a year later gets a bigger delta, which is the one cost of this design and the reason you re-cut the shipped snapshot periodically.

What must never be local-authoritative

The device can own the catalog. It must not own the ledger.

Balances, positions, and order status are the server’s truth. Cache them for display, but treat the cache as a rendering of a remote fact, with two rules: reconcile on reconnect and cold start, and never let a local value participate in a decision that has consequences. Local state answers “what do I show,” never “what is true.”

The line is drawn by a single question: if this value is wrong, is the outcome a stale screen or a wrong action? Stale screen is a caching problem. Wrong action is a correctness problem, and correctness problems live on the server.

Keep the local surface read-mostly

Everything above is easy because the replication is one-way. The server writes, the client reads. There are no conflicts, because there is only one writer.

The moment the client also writes to the same data, you inherit the genuinely hard part of distributed systems: two edits to one record, no global clock, and a need to converge. Now you need conflict resolution — last-write-wins with a version vector, CRDTs, or a server-side merge — and you need to accept that some resolution will be wrong in a way users notice.

There is usually a way to keep local writes off this path: model user-generated state (a watchlist, a note) as its own small collection with its own sync, rather than as edits to the replicated catalog. One-way replication for the big thing, deliberate two-way sync for the small thing you actually need.

Scaling this down

The whole design is forced by three properties: the catalog is large, slow-changing, and needed offline. Remove any one of them and something simpler is correct:

Catalog small enough to fetch in one call? Fetch it and cache in memory.
Changes constantly? It isn’t reference data — treat it as a stream.
Never needed offline? A search endpoint, with the server doing the ranking it is better at anyway.

The failure mode worth avoiding is building version-tracked delta sync for a few hundred rows that would have been a single request. Snapshot-plus-delta is what you graduate to when the catalog gets big enough that re-downloading it is the thing users complain about.

References

M. Kleppmann, A. Wiggins, P. van Hardenberg, M. McGranaghan, “Local-first software: You own your data, in spite of the cloud”, Ink & Switch / Onward! 2019 — the source of the term and the seven ideals behind it.
M. Kleppmann, Designing Data-Intensive Applications, O’Reilly, 2017 — ch. 5 (replication) and ch. 11 (stream processing) are the background for the catalog and feed designs.
J. Kreps, “The Log: What every software engineer should know about real-time data’s unifying abstraction”, LinkedIn Engineering, 2013 (archived) — the log as an append-only sequence where every entry matters, and snapshot + offset as the replication primitive.
M. Shapiro, N. Preguiça, C. Baquero, M. Zawirski, “Conflict-free Replicated Data Types”, SSS 2011 — what you inherit the moment two writers edit one record.

Previous: Order reliability · Next: The cross-platform boundary

Modularity and migration: cutting boundaries that survive

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Part 5 of Trading app architecture.

A long-lived app has a property no design document mentions: it must keep shipping while it changes shape. Nobody gets to stop for a year. That constraint, more than any technical one, determines which architectures survive.

Two old ideas do most of the work here, and a third tells you how to move.

Your architecture will look like your org

Conway’s observation is that a system’s module boundaries end up mirroring the communication boundaries of the organization that produced it. It is not a warning; it’s a prediction that holds well enough to design against.

The practical reading: if eight teams work on one app, you will get roughly eight modules. The only question is whether you chose them. Boundaries that match how people actually work become cheap — a team ships without coordinating. Boundaries that cut across teams become expensive forever, because every change requires a meeting.

So modularity is not only a code-structuring exercise. It is a decision about who can ship without asking whom, and that is why it shows up in build times, review latency, and how often a release is blocked by an unrelated team.

Cut where decisions are likely to change

The criterion is Parnas’s, from 1972, and it is still the most useful sentence about modularity: a module should hide a decision that is likely to change.

Note what it does not say. It doesn’t say group by technical layer — all models here, all views there. That arrangement is the one most teams reach for and it inverts the goal: a typical change is a feature, and a feature touches a model, a view, and a service, so every change touches every module. You have created boundaries that add ceremony and prevent nothing.

The test is simple: take your last ten meaningful changes and see how many modules each touched. If most touched one, your boundaries match reality. If most touched four, your modules are shaped like your file types instead of your changes, and the fix is to cut along features and volatile decisions instead — the market data protocol, the chart engine, the auth flow, the persistence choice.

The core should be handed its dependencies

Once you have modules, the question is which way the arrows point. Dependency inversion answers it: the core declares the interfaces it needs — a network transport, a store, a clock, a logger — and the outside world supplies implementations. The core depends on nothing concrete.

Three things follow, and they are the reason this pattern keeps reappearing in large systems:

The core is testable in isolation, because every collaborator can be replaced with a fake. Including the clock, which is how you test a timeout without waiting for one.
Infrastructure can be replaced without touching business rules. The HTTP client is an implementation detail if and only if nothing in the core names it.
The interface list documents the real dependencies. A core initialized with a dozen injected capabilities tells you exactly what it needs from the world — often a more honest architecture diagram than the one in the wiki.

The corresponding smell is a core that reaches out: constructs its own HTTP client, reads the system clock, calls a singleton logger. It works, and it quietly welds the business rules to the infrastructure. You discover this the day you try to test it.

Registries buy decoupling and charge for safety

When modules must find each other without compile-time dependencies, teams reach for a registry: modules register implementations at startup, consumers look them up by interface.

The benefit is real — modules build and ship independently, and nothing needs a compile-time reference to a sibling.

The cost is equally real: a missing binding is no longer a compile error, it’s a crash at runtime, in a code path someone reaches on a Tuesday. You have traded a guarantee for flexibility.

If you take that trade, pay down the risk deliberately: keep interfaces in small contract modules both sides depend on, and validate the full registry at startup in debug builds so a missing binding fails immediately and loudly rather than deep in a user flow. Flexible wiring is fine; silent flexible wiring is not.

Migrate by growing the new inside the old

Eventually a large app needs a technology it didn’t start with. The instinct is a rewrite, and the reason rewrites fail is structural, not motivational: you are aiming at a moving target. The existing product keeps gaining features while you rebuild, so you must reach parity with something that is still growing, and until you do, you ship nothing.

The strangler-fig approach inverts it. Grow the new system inside the old one, one screen at a time, until the old one can be removed. Concretely that needs four things:

A seam — usually routing or navigation — where a destination can be served by either implementation.
Parity per screen, not per app. One screen at a time is a shippable unit; a whole app is not.
Both runtimes coexisting, with the costs from the previous part accepted explicitly.
A kill switch. If the new implementation misbehaves in production, routing falls back. Without this, incremental migration has the same risk profile as a rewrite, just spread out.

The cost is a period — often years — of maintaining two ways of doing things. That is the price of never having a flag day, and for a product where downtime or a stalled roadmap is unacceptable, it is a good trade. It is also why large apps look “inconsistent” from the outside: you are seeing a migration mid-flight, which is what a healthy long-lived system looks like.

Don’t buy this early

Everything above is priced for coordination problems. If you don’t have them, it’s overhead.

For one to three developers, module boundaries mostly add ceremony: more build configuration, more indirection, more places to look. A registry is strictly worse than calling the thing. The honest default is one codebase with clear internal structure and no enforced boundaries.

Cut a module when a boundary starts to hurt — repeated merge conflicts in one area, build times you notice, ownership nobody can state, a dependency you want to swap and can’t. Those are measurements. “We might grow” is not.

The expensive failure isn’t a missing module. It’s a small team maintaining a large team’s architecture, paying the coordination cost of an organization that doesn’t exist.

References

M. E. Conway, “How Do Committees Invent?”, Datamation, 1968 — system structure mirrors the communication structure of the organization that built it.
D. L. Parnas, “On the Criteria To Be Used in Decomposing Systems into Modules”, CACM 15(12), 1972 — a module should hide a decision that is likely to change.
R. C. Martin, “The Clean Architecture”, 2012 — the dependency rule: source dependencies point inward, toward policy.
A. Cockburn, “Hexagonal Architecture”, 2005 — ports and adapters: the core declares what it needs, the outside supplies it.
M. Fowler, “Strangler Fig Application”, 2004 — grow the new system around the edges of the old until the old can be removed.
M. Fowler, “Inversion of Control Containers and the Dependency Injection pattern”, 2004 — dependency injection vs service locator, and what each costs in testability.

Previous: The cross-platform boundary · Next: The client security model

Order reliability: idempotency, unknown states, and reconciliation

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Part 2 of Trading app architecture.

You tap submit. The request goes out. Nothing comes back.

That is the entire problem, and it has no clean solution — only a choice of which failure you are willing to own. A client that ignores this ships a bug that only appears when the network is bad, which is to say, in exactly the conditions where the money matters most.

The impossibility you must design around

When a request times out, two situations are indistinguishable from the client: the server never received it, or the server executed it and the acknowledgement was lost. There is no message you can send, and no timeout you can tune, that separates those cases. The information does not exist on your side.

So you choose:

At-most-once. Never retry. You never place a duplicate order, and you sometimes silently fail to place one the user asked for. For money, unacceptable — a dropped order is invisible, and the user finds out from the market.

At-least-once. Always retry until acknowledged. You never lose an order, and you sometimes place it twice. Also unacceptable on its own, but this one is fixable.

You take at-least-once and remove the duplicate with an idempotency key: an identifier the client mints for the intent, which the server uses to recognize a repeat. First arrival executes. Every subsequent arrival with that key returns the original result without executing again. The retry becomes safe by construction, and “exactly once” is achieved not at the transport layer, where it is impossible, but at the semantic layer, where it is merely careful bookkeeping.

Mint the key before you send, and persist it

This is the detail that separates a design that works from one that looks identical and doesn’t.

The key must be generated and written to durable storage before the first network call, as part of creating the order intent. Not inside the request builder. Not as a retry-time afterthought.

The reason is the failure you are protecting against. If the app is killed mid-flight, then on relaunch you must be able to ask “did that order go through?” — and you can only ask if the identity of the attempt survived the crash. A key generated in memory at send time dies with the process, and your recovery path invents a new key, which the server correctly treats as a new order. You have implemented duplicate submission with extra steps.

So the sequence is: create the intent, persist it with its key and a pending status, then send. Every retry, in this process or a later one, reuses that key.

Timeout is a state, not a failure

The most common modeling error is a boolean: submitted or not. Reality has a third value.

Model the order as a state machine with an explicit unknown state, entered on timeout or ambiguous error. Unknown means: an action may or may not have happened, and the client is not entitled to guess.

What you do in unknown is the important part: you do not blindly retry, and you do not report failure. You ask. Query order status by the idempotency key, and let the authoritative answer collapse the ambiguity. Only if the server confirms it never saw the request do you resend.

Blind retry is safe only if your idempotency guarantee is airtight end to end, including across app restarts and server deploys. Query-then-decide is safe regardless. On an irreversible action, prefer the design whose safety doesn’t depend on a guarantee elsewhere being perfect.

Telling the user “failed” on a timeout is the same class of error in the opposite direction: they resubmit by hand, and now the duplicate is caused by your UI rather than your network layer. An honest pending state is not a worse user experience. It is the only truthful one.

The server is the only source of truth

A local “sent” is not “accepted.” “Accepted” is not “filled.” Only the endpoint that owns the money can make those statements, and this is the end-to-end principle applied to a domain where it has teeth.

Two consequences for the client:

Optimistic UI must be labeled as optimistic. Showing a pending order immediately is good; showing it as placed is a lie you will occasionally have to retract in front of someone who acted on it.

Reconcile on every reconnect and every cold start. Pull the authoritative order list and let it overwrite local state. Do not merge cleverly. The client’s copy is a cache, and a cache that argues with the origin is just a bug with persistence.

Ordering: version, don’t trust arrival

Status updates for one order can arrive out of order — retries, multiple channels, reconnects. If you apply whatever arrives last, a stale “submitted” can overwrite a fresh “filled,” and your UI now shows a completed order as in-flight.

Give every order a monotonically increasing version or sequence assigned by the server, and drop any update whose version is not newer than what you hold. Last-write-wins by version, never by arrival time. Client clocks are not a substitute; they are wrong, and they are wrong in both directions.

Make illegal transitions loud, too. If you receive filled → submitting, that is not a state to render, it is a defect to log. Silently accepting impossible transitions is how a data bug becomes a customer’s screenshot.

Store events, not just current state

Keep an append-only record of what happened: intent created, submitted, acknowledged, filled. Derive the current state from it.

You want this for three reasons, and only one of them is regulatory. It gives support and engineering a truthful answer to “what did the app actually do at 09:31:04.” It makes reconciliation a comparison rather than a guess. And it turns your postmortems from archaeology into reading.

Mutating a single status field in place destroys exactly the information you will need on the one day you need it badly.

Scaling this down

All of the above is the price of irreversibility. Take that away and it collapses.

If the action is reversible — a saved draft, a like, a preference — a plain request with a retry is correct, and an idempotency key plus a state machine plus an event log plus reconciliation is machinery in search of a problem.

The trigger for adopting this design is not “we handle data,” it’s “an action that cannot be undone by the user.” Payments, orders, transfers, irreversible account changes. When you have one, build all of it. When you don’t, don’t.

References

E. A. Akkoyunlu, K. Ekanadham, R. V. Huber, “Some constraints and tradeoffs in the design of network communications”, SOSP 1975 — the Two Generals problem: agreement over an unreliable channel is impossible, so exactly-once delivery is too.
P. Helland, “Idempotence Is Not a Medical Condition”, ACM Queue 10(4), 2012 — at-least-once plus idempotent handling, and why a timeout must be modeled as an unknown state.
J. H. Saltzer, D. P. Reed, D. D. Clark, “End-to-End Arguments in System Design”, ACM TOCS 2(4), 1984 — a guarantee is only real at the endpoint that can verify it.
L. Lamport, “Time, Clocks, and the Ordering of Events in a Distributed System”, CACM 21(7), 1978 — order by logical version, never by wall clock or arrival.
Stripe, Idempotent requests, and IETF HTTPAPI WG, “The Idempotency-Key HTTP Header Field” — the production shape of client-minted idempotency keys.
M. Fowler, “Event Sourcing”, 2005 — derive current state from an append-only record of what happened.

Previous: Real-time data pipelines · Next: Local-first data and delta sync

Real-time data pipelines: push, backpressure, and conflation

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Part 1 of Trading app architecture.

Most client code assumes a shape: you ask, the server answers, you render. A market data feed breaks that assumption in three places at once. Nobody asks — the data arrives on its own. There is no “answer” — the stream never ends. And the producer is faster than the consumer, permanently, by design.

Get those three straight and the architecture of a real-time client mostly writes itself.

Why the data must be pushed

The naive approach is to poll: ask every n milliseconds. It fails on arithmetic before it fails in production.

Polling puts a floor under your staleness equal to the interval. Want data no more than 100 ms old? Poll ten times a second. Now multiply: every symbol on screen, every open client. The server does full request-handling work on every tick regardless of whether anything changed — and most of the time nothing has. You are paying for the clock, not for the information.

Push inverts the cost. Work happens when the data changes. An idle market costs an idle connection; a volatile one costs exactly the messages that carry news. That is the property you want: cost proportional to change, not to time.

The price of push is that a connection is no longer an event, it is state you own. That state needs:

Heartbeats, because TCP will happily hold a connection that is functionally dead. Without an application-level ping you cannot distinguish “quiet market” from “we were severed twenty minutes ago.” Silence must be made falsifiable.
Reconnect with exponential backoff and jitter. Backoff so you don’t hammer a struggling server; jitter because without it every client that dropped at the same moment returns at the same moment, and your recovery becomes a second outage.
A resume token, so reconnecting doesn’t mean starting from nothing.

Gaps, and the difference between a log and a register

Every message carries a sequence number. Not for bookkeeping — for detecting the messages you didn’t get. A silently dropped update in a price feed isn’t missing data, it’s wrong data: your client is now displaying a number it believes is current and isn’t.

What you do about a gap depends on what kind of stream it is, and this is the classification that drives everything downstream:

A register holds a current value. The last write wins; earlier writes are irrelevant once superseded. A last-traded price is a register — if you missed three ticks and the fourth arrives, you have lost nothing that the fourth doesn’t already tell you.

A log is a sequence of deltas where each one is meaningful. An order book maintained by incremental updates is a log — miss one and every subsequent update is applied to a corrupt base. The damage is permanent and silent; it compounds.

So: for a register, a gap is a hiccup. For a log, a gap is a resync — discard local state, request a fresh snapshot, apply increments from that snapshot’s sequence forward. The universal pattern is snapshot plus increments, with the snapshot’s sequence number as the join point.

Write down, for each stream in your product, whether it is a log or a register. It is a five-minute exercise that decides the next section for you.

Backpressure is the real design problem

Your consumer is a phone. Your producer is a market. Under load the producer wins, and “wins” means your queue grows without bound until the process dies.

There are only three honest responses:

Buffer everything. Correct in principle, fatal in practice — memory grows without limit, and worse, the data you eventually render is old. You built a queue that converts a freshness problem into a latency problem and then into a crash.

Drop. Shed messages when behind. Legitimate for a register, catastrophic for a log.

Conflate. Keep only the newest value per key, coalescing anything that arrives before you can consume it. Ten ticks for a symbol between two frames collapse into one. This is the right answer for registers, and it is not a degradation: rendering the latest price is exactly correct, because the intermediate ticks were already superseded before a human could perceive them.

Conflation is the single highest-leverage idea in a real-time client, and it follows directly from the register/log split. You cannot conflate a log; you must never buffer a register.

Decouple tick rate from frame rate

A screen refreshes 60 times a second. A liquid symbol can update far more often than that. So updates-per-second above 60 have no representable meaning on the client — they can only cost you.

The architecture that follows: an ingest path that decodes and conflates into a per-symbol current-value map, and a render path that samples that map once per frame. Ticks and frames are now independent. A tenfold burst in market activity changes the ingest cost slightly and the render cost not at all.

The common failure is wiring the socket directly to UI state, so every message triggers a re-render. That design works beautifully in testing and collapses on the first volatile open, because you accidentally coupled your frame rate to the market’s.

Where the native boundary belongs

If you cross a language boundary (Dart to C++, JVM to native), the cost is mostly per call, not per byte. That single fact places the boundary for you.

Put decode, gap detection, conflation, and fan-out on the fast side. Cross once per frame with a batch of changed symbols. Do not cross per message.

A client that calls across the boundary for every tick can be slower than one that does everything in the managed language, because it pays thousands of transition costs to save a decode. The reason to go native here is not that “C++ is fast” — it’s that a managed runtime’s tail latency is unpredictable. A garbage collection pause is invisible in your average and clearly visible as a stutter at the worst moment. You go native for timing determinism on the hot path, and only for that.

Subscriptions are a lifecycle, not a call

The last piece is bookkeeping that is easy to underestimate:

Reference-count subscriptions per symbol. Two widgets showing the same symbol should produce one subscription, and it should end when the second one leaves.
Resubscribe on reconnect. Server-side subscription state died with the socket. If your client assumes otherwise, it shows a frozen screen that looks exactly like a quiet market — the worst possible failure, because it is indistinguishable from working.
Degrade in the background. An app that isn’t visible should unsubscribe or drop to a slow summary. This is the difference between a well-behaved app and one users uninstall for battery reasons.

When you need none of this

Everything above is forced by one number: how often your data changes relative to how fast a human perceives it. If a value updates every few seconds, a WebSocket handing JSON straight to your UI state is the correct design, and every mechanism above is waste.

The discipline is to add each piece when a measurement demands it, in roughly this order: push before polling hurts; sequencing when correctness demands it; conflation when the queue grows; a native boundary only when profiling shows the decode loop, and never before.

References

J. Kreps, “The Log: What every software engineer should know about real-time data’s unifying abstraction”, LinkedIn Engineering, 2013 (archived) — the log as an append-only sequence where every entry matters, and snapshot + offset as the replication primitive.
Reactive Streams specification, 2015 — backpressure as a first-class contract between producer and consumer; the three honest responses (buffer, drop, conflate) are what a consumer can do when it has none.
M. Brooker, “Exponential Backoff and Jitter”, AWS Architecture Blog, 2015 — why backoff without jitter turns recovery into a second outage.
J. Dean, L. A. Barroso, “The Tail at Scale”, CACM 56(2), 2013 — why percentiles, not averages, describe what a user experiences.
Binance, WebSocket Streams — “How to manage a local order book correctly” — a public specification of snapshot + increments joined at a sequence number.

Next: Order reliability — why exactly-once doesn’t exist, and what to do instead.

Shipping a database with your Flutter app: offline catalogs and instant search

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Flutter implementation notes for Trading app architecture; the principle is in Local-first data.

The design from the local-first article — ship a snapshot, sync deltas by version — has a specific and slightly fiddly Flutter implementation. Here it is concretely.

Choosing the store

sqflite gives you SQLite with raw SQL. drift sits on top of it (or on its own engine) and adds typed queries, migrations, and first-class isolate support. For a catalog with a schema you will evolve, drift’s migration story alone justifies it; for a handful of key-value settings, shared_preferences and nothing else is correct.

The mistake worth avoiding is reaching for a document store because it looks simpler, then discovering you need prefix search over several hundred thousand rows with ranking. That is a relational problem with a mature answer, and SQLite is on the device already.

Bundle the snapshot, copy once

Ship the prebuilt database as an asset and copy it into the app’s documents directory on first launch. The copy is necessary because assets are read-only and SQLite needs a writable file.

Future<File> ensureCatalog() async {
 final dir = await getApplicationDocumentsDirectory();
 final file = File(p.join(dir.path, 'catalog.db'));
 final shippedVersion = 812; // bumped when you re-cut the asset

 if (await file.exists() && await _dataVersion(file) >= shippedVersion) {
 return file; // user's copy is newer — keep it
 }
 final bytes = await rootBundle.load('assets/db/catalog.db');
 await file.writeAsBytes(bytes.buffer.asUint8List(), flush: true);
 return file;
}

The comparison in the middle is the part people get wrong. After an app update you must not blindly overwrite: a user who has been syncing deltas for months may hold a newer catalog than the one you just shipped. Copy only when the bundled snapshot is actually ahead, and let delta sync handle the rest.

The other detail is that the copy happens on first launch, which is the moment you least want a long block. Copying tens of megabytes takes real time, so do it off the UI isolate and show a determinate first-run state rather than a frozen splash.

Two versions, never conflated

Keep these separate, as the principle article insists:

Data version — how fresh the contents are. It moves when the server publishes changes, and drives delta sync. Store it in a metadata table you control.
Schema version — the shape of the tables. It moves when your app changes, and drives migrations. SQLite’s user_version, or drift’s schemaVersion, is the natural home.

Conflating them produces one of two failures: an app update that discards a synced catalog to reinstall the snapshot, or a migration that never runs because the version counter was busy tracking data.

@override
MigrationStrategy get migration => MigrationStrategy(
 onUpgrade: (m, from, to) async {
 if (from < 3) await m.addColumn(instruments, instruments.board);
 // data version untouched — the catalog contents survive
 },
 );

Search: FTS, plus the columns you actually search

Instant search over a few hundred thousand rows is what SQLite’s full-text search is for. Create an FTS5 table alongside the main one and query it, rather than running LIKE '%...%', which cannot use an index and degrades linearly.

The interesting part is multilingual matching. Users search a Chinese instrument by its Chinese name, its English name, its ticker, its pinyin, or the initials of its pinyin — and they expect all five to work. That is not a tokenizer problem; it is a data problem. Generate the variants at build time and store them as searchable columns:

column	example
`symbol`	`00700`
`name_zh`	腾讯控股
`name_en`	Tencent Holdings
`pinyin`	tengxunkonggu
`initials`	txkg

Then one FTS query with prefix matching covers every entry style, and ranking is a matter of ordering by which column matched and by a popularity score you ship with the catalog. Doing this at build time rather than on the device keeps startup free and makes the behavior identical across platforms.

Keep queries off the UI isolate

A query over a large table will block whatever isolate runs it, and on the UI isolate that means dropped frames during typing — the worst possible place, since search-as-you-type is exactly when responsiveness is judged.

Drift supports running the database in a background isolate, which is the clean answer (drift 2.x, NativeDatabase.createInBackground):

final db = AppDatabase(NativeDatabase.createInBackground(file));

Then debounce input (a query per keystroke is wasted work), cancel superseded queries, and keep result sets small with LIMIT — nobody scrolls past the first few dozen matches, and fetching a thousand rows to display twenty is pure cost.

Sync deltas, not the world

Once the snapshot is in place, the client only asks what changed:

final since = await meta.dataVersion();
final delta = await api.catalogChanges(since: since);
await db.transaction(() async {
 await db.upsertAll(delta.changed);
 await db.deleteAll(delta.removed);
 await meta.setDataVersion(delta.version); // same transaction, always
});

The transaction boundary is the whole correctness argument: apply the rows and advance the marker atomically, or a crash between them leaves you permanently skipping a range. Express deltas as upserts and tombstones so re-applying an overlapping range is harmless.

What stays on the server

The catalog is safe to hold locally because it is public, slow-moving, and read-only. Balances, positions, and order status are none of those things. Cache them for display if you like, but they are a rendering of a remote fact — refresh on resume, and never let a locally cached number participate in a decision.

The user’s own data — a watchlist, notes — is a third category: small, user-owned, and written on the device. Give it its own table and its own two-way sync rather than mixing writes into the replicated catalog, which keeps the big replication one-way and conflict-free.

References

API and renderer claims checked against Flutter 3.47.0 / Dart 3.13 (August 2026).

drift and its Isolates guide — NativeDatabase.createInBackground, DriftIsolate, computeWithDatabase; sqflite for the raw-SQL alternative.
SQLite, FTS5 Extension; The LIKE optimization — why LIKE '%…%' cannot use an index; PRAGMA user_version — the natural home for the schema version.
M. Kleppmann, A. Wiggins, P. van Hardenberg, M. McGranaghan, “Local-first software: You own your data, in spite of the cloud”, Ink & Switch / Onward! 2019 — the source of the term and the seven ideals behind it.

Previous: Charts in Flutter · Next: Project structure and add-to-app

The client security model: an input, never an authority

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Part 6 of Trading app architecture.

Start from an uncomfortable premise: the device is not yours. It belongs to someone who may be curious, compromised, or hostile, and who can inspect memory, intercept traffic, patch the binary, and replay any request your app can make.

That premise is not pessimism. It is the only assumption that produces a design that still holds when it turns out to be true.

The one rule

The client is an input, never an authority.

Every security-relevant decision — can this user do this, what does it cost, what are the limits, is this allowed right now — is made on the server, from server-held state. The client may also check, for a fast and pleasant experience, but its check is a convenience, and the server must behave identically whether or not the client bothered.

The test is direct: if someone crafted your app’s requests by hand, ignoring every check in your UI, would anything bad happen? If yes, that check was load-bearing, and load-bearing checks cannot live on a device you don’t control.

This is the same principle as orders being confirmed only by the server, applied to authorization instead of state. Client-side validation is user experience. Server-side validation is security. They look similar in code and are not the same thing at all.

Client hardening buys time, not prevention

Obfuscation, root and jailbreak detection, integrity checks, anti-debugging, encrypted local storage — these are worth shipping, and it is worth being precise about what they do.

They raise the cost and the time of an attack. They do not prevent it. Every one of them runs on the attacker’s hardware, and anything that runs there can be found and removed by someone patient enough.

The useful framing: hardening is a rate limiter on attacker effort. That’s valuable — most attacks are opportunistic, and cost is a real deterrent. It becomes dangerous only when someone starts treating it as a guarantee, and designs a server that trusts a client which “proved” it wasn’t tampered with. Then a single bypass unlocks everything, because the real control was never there.

So: layer the defenses, assume each layer fails, and make sure the thing behind them is a server that would have said no anyway.

There are no secrets in a binary

Anything shipped inside the app is readable. Strings, keys, endpoints, certificates, the clever thing you spread across three files and XOR’d — all recoverable by someone with a disassembler and an afternoon.

The consequences are concrete:

No API secrets in the app. A shared secret embedded in a client is a public secret with extra steps. If a credential grants privilege, it cannot ship in the binary.
Authenticate to get short-lived tokens. The app proves identity with something the user supplies, then holds a token that is narrow in scope and short in life. What leaks then is a token that expires, not a key that doesn’t.
Sign on the server. If a request must be signed with a key, the key belongs where the server is.
Use the platform keystore for tokens at rest, and still assume a rooted device can reach them. Keystore raises cost; it doesn’t make the device trustworthy.

Encrypting a secret in the binary just means the decryption key is also in the binary. That is not a criticism of the technique — it’s the definition of the situation.

The effective policy is the lowest layer

A rule worth generalizing beyond security: a system does what its lowest, most specific configuration says, not what its top-level declaration claims.

Platforms have layered policy — a manifest declaration, a configuration file, a per-domain override, a build-type variant. When they disagree, the more specific layer wins, and it is entirely possible for a reassuring top-level flag to be silently negated by something underneath it. A team can read the top line, conclude the system is safe, and be wrong for years, because nothing errors — the override is a legitimate feature.

The practice that follows: audit effective behavior, not declared intent. Read the final merged configuration for the build you actually ship. Verify with observation — inspect real traffic, confirm the runtime state — rather than reading the declaration and trusting it. “What did we declare” and “what does it do” are different questions, and only the second one has consequences.

Every entry point is an undocumented API

The attack surface isn’t only the network. Anything another app or a web page can invoke is an interface you are exposing, whether or not you documented it:

Exported components and deep links. If another app can launch your screen with parameters, those parameters are attacker-controlled input. Validate the scheme, host, and path strictly against an allowlist; never let a link alone authorize a sensitive action; and require the session to be re-checked at the destination rather than assuming the caller was legitimate.
Web-to-native bridges. A bridge exposes a set of callable functions to whatever page is loaded. That set is a public API with the privileges of your app. Restrict which origins can use it, keep the surface minimal, and validate every argument as hostile input. A bridge that can reach account or payment functionality should assume the page calling it is malicious.
Custom URL schemes and inter-app messaging. Same reasoning: you cannot verify who is calling, so the call must not be the authorization.

Each of these is a place where a feature (“let partners deep-link into the app”) quietly becomes an interface, and interfaces need threat models.

Transport, and the pinning trade

Encrypt everything, and be sure of it — the failure mode here is not “we forgot TLS,” it’s a narrow exception for one legacy endpoint that quietly becomes a global allowance.

Certificate pinning is a genuine trade rather than a best practice. It defeats interception with an installed root, which is the realistic attack on a user’s device. It also means a certificate rotation you didn’t plan for can brick every installed copy of your app. If you pin: pin to an intermediate or include backup pins, ship a remote kill switch, and rehearse rotation before you need it. If you can’t operate that reliably, standard TLS validation done properly is better than pinning done fragilely.

Scaling this down

Most of the above is proportional to what an attacker gains. If your app holds public data and reversible actions, exotic hardening is the wrong place to spend.

What is not optional at any scale, because it’s where real incidents come from: authorization enforced on the server for every request, no secrets in the binary, TLS with no exceptions, short-lived scoped tokens, and treating every deep link and bridge call as hostile input.

The unglamorous list is the one that matters. Breaches are rarely elegant — they are a forgotten endpoint that trusts a client-supplied user id, a debug flag that shipped, an internal address left reachable. Get those right first, and add hardening because you have something worth the attacker’s time, not because it feels rigorous.

References

J. H. Saltzer, M. D. Schroeder, “The Protection of Information in Computer Systems”, Proc. IEEE 63(9), 1975 — complete mediation (check every access at the authority) and open design (no security in a secret mechanism).
OWASP, Mobile Application Security Verification Standard (MASVS) — the control groups this article compresses: storage, crypto, auth, network, platform interaction, resilience.
OWASP, Pinning Cheat Sheet — when pinning helps, when it bricks you, and how to rotate.
Android developers, Network security configuration — a concrete example of layered policy where the per-domain entry overrides the base config.

Previous: Modularity and migration · Back to the overview.

The cross-platform boundary: share what must not diverge

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. Part 4 of Trading app architecture.

The cross-platform debate is usually conducted as a framework comparison, which is why it never resolves. The prior question decides most of it: which parts of your app must be identical on iOS and Android, and which parts should not be?

Answer that and the framework choice narrows to a couple of reasonable options. Skip it and no amount of benchmarking will help, because you are arguing about tools while the requirement is undefined.

The test: is divergence a bug or a feature?

Take any layer of your app and ask what happens if the two platforms behave differently.

For an order validator, a fee calculation, an options pricing rule, a state machine, a protocol encoder: divergence is a defect. Two independent implementations of the same financial rule will drift — not maybe, will. They drift on the edge cases first, which in this domain are also the expensive cases. Nobody notices for months, and the bug report arrives as a customer whose numbers didn’t match.

For navigation transitions, gesture physics, date pickers, permission flows, accessibility, share sheets: divergence is correct. Users have platform expectations, and code that flattens them produces an app that feels subtly wrong on both. Effort spent unifying this layer buys negative value.

That’s the whole rule: share the layer where difference is a defect, keep native the layer where difference is the point.

Notice this is a correctness argument, not an efficiency one. DRY is usually justified as “write it once,” which invites the counterargument that duplication is sometimes cheaper. That counterargument is fine for UI and irrelevant for domain rules, because there the cost of duplication isn’t typing — it’s two divergent truths about money.

Sharing is not free, and the costs are structural rather than obvious:

A boundary appears. Shared code and platform code must talk. That interface needs types both sides understand, serialization, and error mapping. It is now a thing to design and version.

A runtime arrives. A second runtime means memory, startup cost, and a debugger that no longer sees the whole picture. When something breaks at the boundary, you are debugging two systems and the seam between them.

The team splits. Someone must be fluent in the shared layer and its toolchain. At small scale that is one person, which is a bus factor rather than a plan.

So the question isn’t “does sharing help” — it’s “does the divergence risk in this layer exceed the boundary cost.” For domain logic, usually yes. For a settings screen, usually no.

The three positions

Fully native, twice. Maximum platform fidelity, zero boundary cost, and every rule written twice. Reasonable when the shared logic is thin or the platform surface is most of the product.

Share the logic, keep native UI. The domain, models, and validation live in one codebase; each platform renders it. This targets exactly the layer where divergence is a defect and leaves the layer where it isn’t. The cost is that boundary and its toolchain.

Share the UI too. One codebase draws both platforms. Fastest to a feature-complete app with one team, and the reason most small teams should start here. The cost arrives later and from a predictable direction: platform capabilities. Every camera, biometric, background, or notification feature eventually needs a plugin, and a plugin is native code with extra steps. Budget for that from the start instead of being surprised by it.

The mixed model, and what it really costs

Large apps often end up mixed: a native shell with a cross-platform UI framework embedded for some screens. This is usually not indecision — it is the honest shape of a migration, and it’s the right pattern when you cannot stop shipping to rewrite (more on that next).

It has real costs worth naming before you choose it:

Runtime memory. Each embedded engine has a footprint. Multiple live engines multiply it, and the mitigation — caching and reusing engines — is itself a lifecycle problem you now own.
Two navigation stacks. The native stack and the framework’s router must be unified, or back-button behavior becomes a permanent source of bugs.
State on both sides. Session, theme, and locale now exist twice and must be kept in agreement. Every duplicated piece of state is a future desync.
Debugging across runtimes. A stack trace stops at the boundary. Crash and performance tooling must be configured to see both sides, or half your incidents become guesswork.

Make the boundary coarse

Whatever you share, the interface between the shared core and the platform should be coarse-grained.

The cost of crossing a boundary — serialization, marshalling, a runtime transition — is paid per call, not per byte. A chatty interface with dozens of small property reads can be dramatically slower than one call returning a complete object, even though it moves less data. This is the same lesson as batching updates at a native boundary in part one, and it generalizes: design boundaries as few, meaningful operations, not as remote field access.

There’s a design benefit too. A coarse interface expresses intent (“place this order,” “give me this screen’s data”), which stays stable while implementations change underneath. A fine-grained interface exposes structure, and structure changes constantly.

Choosing, honestly

Two variables decide it: how much of your product is domain logic that must not diverge, and how many people you have.

One small team, mostly UI over an API: share everything. One codebase, native modules where the platform demands it.
Small team, meaningful domain logic: share everything, but keep that logic in its own layer with no UI dependencies — so it can be extracted later without a rewrite.
Multiple platform teams, substantial domain logic: share the logic, keep UI native. This is where the boundary cost is clearly repaid.
Single platform: the question does not exist. Don’t pay for optionality you have no evidence you’ll use.

The mistake that costs the most is choosing a sharing strategy for a team size you don’t have yet. Architecture that anticipates an organization you might build is how small teams end up maintaining a large team’s overhead with a small team’s capacity.

References

J. Waldo, G. Wyant, A. Wollrath, S. Kendall, “A Note on Distributed Computing”, Sun Microsystems Laboratories TR-94-29, 1994 — a boundary between address spaces cannot be papered over; latency and partial failure are paid per call.
A. Hunt, D. Thomas, The Pragmatic Programmer, 1999 — DRY, stated as a rule about knowledge, not about typing.
M. E. Conway, “How Do Committees Invent?”, Datamation, 1968 — system structure mirrors the communication structure of the organization that built it.
Flutter docs, Add Flutter to an existing app and Multiple Flutter instances — engine warm-up, FlutterEngineGroup, and the cost of several live engines.

Previous: Local-first data · Next: Modularity and migration

Trading app architecture: six constraints and what they force

Fri, 28 Aug 2026 00:00:00 +0000

Also in 中文. A six-part series.

You cannot pick a trading client’s architecture by taste. Most of it is decided before you write a line — by how fast the data changes, what a wrong order costs, how big the catalog is, how many platforms and teams you have, and the fact that the app runs on a device you don’t control.

So the useful question is not “which stack.” It is: what does each of those constraints force, and what happens to the design when your version of that constraint is smaller?

That second half is the part worth caring about. Large financial apps converge on a recognizable shape, and the shape is often copied by teams who don’t share the constraints that produced it. What follows is the reasoning behind each element — informed by taking a large trading app apart and checking that the theory matched what a team at real scale actually built — and then the conditions under which each element is simply unnecessary.

The six constraints

1. Freshness. Market data is a high-rate, unbounded stream whose value decays in milliseconds. It cannot be polled, the consumer is permanently slower than the producer, and a silently dropped update is not missing data but wrong data. This forces a pushed, sequenced, back-pressured transport, and a decision about which streams may be conflated and which must be resynced. → Real-time data pipelines: push, backpressure, and conflation

2. Irreversibility. An order cannot be undone by the user, and exactly-once delivery does not exist. This forces an idempotency key minted and persisted before the first send, an explicit unknown state on timeout, reconciliation instead of blind retry, and a server that is the only source of truth. → Order reliability: idempotency, unknown states, and reconciliation

3. A large catalog. Hundreds of thousands of instruments, searchable instantly, including offline. This forces separating slow-changing reference data from fast-changing values, shipping a snapshot on the device, and syncing deltas against a monotonic version — while the ledger stays authoritative on the server. → Local-first data: snapshots, deltas, and the two kinds of state

4. Two platforms, one truth. iOS and Android must agree exactly on financial rules, and should not agree on interaction idioms. This forces sharing the layer where divergence is a defect and keeping native the layer where divergence is correct — and paying attention to the cost of the boundary between them. → The cross-platform boundary: share what must not diverge

5. Many teams, many years. The system must keep shipping while it changes shape. This forces module boundaries drawn around decisions likely to change, a core that receives its dependencies rather than reaching for them, and migration by growing the new inside the old instead of rewriting. → Modularity and migration: cutting boundaries that survive

6. An untrusted device. Every control you ship can be removed. This forces treating the client as an input and never an authority, keeping no secrets in the binary, auditing effective rather than declared policy, and treating every deep link and bridge call as hostile input. → The client security model: an input, never an authority

Flutter implementation notes

The six above are framework-neutral. This second group takes the same constraints down to a concrete Flutter build — with the patterns, the costs, and a reference design you could start from on Monday.

Flutter under a firehose — per-symbol notifiers, frame coalescing, and making rebuild scope match change scope
Channels, Pigeon, and FFI — the three ways out of Dart, memory ownership, and why EventChannel has no backpressure
Charts that hold 60fps — custom painting, static and live layers, and an honest shouldRepaint
Shipping a database with your app — bundled SQLite, data version vs schema version, FTS with pinyin search
Project structure and add-to-app — packages as enforced boundaries, routing as a registry, what embedding costs
A reference design: quotes MVP — a committed plan, what it deliberately doesn’t build, and the trigger for each upgrade

The decision rules

Every part above ends with “adopt it when a measurement demands it,” which is meaningless until someone names the measurement. One article supplies the numbers — frame budgets, message rates, catalog sizes, team sizes — the ladder of cheaper fixes to exhaust first, and the counter-signals that should stop you even past a threshold.

It also draws the distinction the rest of the series glosses over: correctness has no threshold. Idempotency keys, server-side authorization, sequence numbers, and decimal money are day-one work at any scale, because the cost of retrofitting them is unbounded. Only performance decisions wait for a number.

When to adopt the heavy machinery: thresholds, not opinions

Which of these are actually yours?

Each requirement came from a constraint, and constraints have magnitude. Shrink one and the requirement it produced collapses into something much smaller:

If your reality is…	The requirement…	becomes…
Data changes at human speed	pushed, sequenced, conflated pipeline	a WebSocket into UI state
Actions are reversible	idempotency key, unknown state, reconciliation	a request with a retry
Small or server-side catalog	on-device snapshot + delta sync	a search endpoint
One platform, or thin domain logic	shared cross-platform core	build it once, natively
One small team	module registry, ports and adapters	one codebase, no enforced boundaries
Low-value or public data	layered hardening	standard auth and TLS, done properly

Read the right column. For a small team building a quotes-and-watchlist MVP, this reasoning produces: one cross-platform codebase, REST plus a WebSocket, a search endpoint, no shared-core layer, no native performance work, no custom transport. That is not a simplified version of the large architecture. For those constraints it is the correct architecture, and the large one would be a mistake.

The large app is not more advanced. It is the same six constraints at full magnitude, plus years of accumulated migration state that no one would choose deliberately.

How to use this

Write down your own six magnitudes honestly. Work out what each one forces. Build only that.

Then adopt each heavy element on the day a measured constraint demands it — the queue actually grows, the profile actually points at the decode loop, the merge conflicts actually recur — and not one sprint earlier. Most of the cost of a large architecture is paid by teams who adopted it in anticipation of a scale they never reached.

What compounds is the map from constraints to structure. The structure itself is disposable, and someone else’s structure, copied, is a liability with good PR.

References

D. L. Parnas, “On the Criteria To Be Used in Decomposing Systems into Modules”, CACM 15(12), 1972 — a module should hide a decision that is likely to change.
M. E. Conway, “How Do Committees Invent?”, Datamation, 1968 — system structure mirrors the communication structure of the organization that built it.
J. H. Saltzer, D. P. Reed, D. D. Clark, “End-to-End Arguments in System Design”, ACM TOCS 2(4), 1984 — a guarantee is only real at the endpoint that can verify it.
M. Kleppmann, Designing Data-Intensive Applications, O’Reilly, 2017 — ch. 5 (replication) and ch. 11 (stream processing) are the background for the catalog and feed designs.
J. Bezos, Amazon 2015 Letter to Shareholders, 2016 — Type 1 (one-way door) vs Type 2 (two-way door) decisions.

The series is grounded in a static architectural analysis of a large trading app: what layers exist and how they communicate. No running app, no source recovery, no private protocols — and the detailed teardown notes stay out of the series deliberately, because the transferable part is the reasoning, not the artifact.

Architecture | kaguc — Writing to understand systems.

When to adopt the heavy machinery: thresholds, not opinions

Not everything waits for a threshold

First, define the target

The frame budget, which is arithmetic

Thresholds, element by element

Try the cheap fixes first, in order

When not to adopt, even past the threshold

The procedure

So is the MVP the whole story?

References

A reference design: quotes and watchlist MVP in Flutter

The constraints, stated honestly

The design

What we deliberately do not build

Build order

The upgrade path

The one thing to keep

References

Channels, Pigeon, and FFI: crossing to native without paying per tick

The three mechanisms

The number that decides it

A concrete shape for a high-rate feed

Memory ownership must be explicit

EventChannel has no backpressure

Choosing, briefly

References

Charts in Flutter: custom painting that holds 60fps

Don’t compose a chart out of widgets

shouldRepaint is the whole game

Split static from live

Don’t allocate inside paint()

Text is the hidden cost

Interaction: transform the canvas, not the data

Shader compilation, briefly

Measure the raster thread

When to just use a library

References

Flutter project structure: packages, boundaries, and add-to-app

A package per feature

Enforce the rule with a tool

Routing as a registry

Composition at the root only

Add-to-app, and what it costs

When this is too much

References

Flutter under a firehose: making rebuild scope match change scope

Why the ordinary way fails

Rebuild only the leaf

Conflate onto the frame, not onto the tick

Keep the list itself cheap

Subscribe from the widget lifecycle

Measure the right thread

When to skip all of it

References

Local-first data: snapshots, deltas, and the two kinds of state

Why the catalog belongs on the device

Snapshot plus deltas, keyed by a monotonic version

Shipping the snapshot inside the app

What must never be local-authoritative

Keep the local surface read-mostly

Scaling this down

References

Modularity and migration: cutting boundaries that survive

Your architecture will look like your org

Cut where decisions are likely to change

The core should be handed its dependencies

Registries buy decoupling and charge for safety

Migrate by growing the new inside the old

Don’t buy this early

References

Order reliability: idempotency, unknown states, and reconciliation

The impossibility you must design around

Mint the key before you send, and persist it

Timeout is a state, not a failure

The server is the only source of truth

Ordering: version, don’t trust arrival

Store events, not just current state

Scaling this down

References

`shouldRepaint` is the whole game

Don’t allocate inside `paint()`