Flutter | kaguc — Writing to understand systems.

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.

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

Flutter | kaguc — Writing to understand systems.

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

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

Choosing the store

Bundle the snapshot, copy once

Two versions, never conflated

Search: FTS, plus the columns you actually search

Keep queries off the UI isolate

Sync deltas, not the world

What stays on the server

References

`shouldRepaint` is the whole game

Don’t allocate inside `paint()`