Engineering handbook · Flutter
How we build
Flutter, on purpose.
A living set of field guides for the patterns we actually ship: how state is layered, how errors are caught and logged, and how navigation is structured. Opinionated, consistent, and interactive, so the conventions are something you can feel, not just read.
The through-lines
Conventions every guide shares.
These decisions repeat across state, errors, and routing. They're the reason the guides feel like one system rather than three tutorials.
01
Plain Dart, no code-gen
Hand-written providers and routes by default. Code generation only where it earns its keep, like multi-argument families.
02
Feature-first MVC + Repo
Each feature holds its own models, repo, controllers, and views. Shared infrastructure lives in core/.
03
DI by passing Ref
Repositories and services take a Ref and read what they need internally, rather than receiving concrete clients through constructors.
04
Route identity as statics
Every screen owns its routeName and routeLocation. GoRoute and navigation reference those, never a loose string.
05
One Failure, one mapper
A typed error model, a single shared mapper at the repository edge, and one reporter that every path funnels through.
06
Observe with PostHog
Exceptions, success events, and screen views all flow to PostHog, so the happy path and the failures are measured together.
The guides
Three deep dives, fully interactive.
Each one runs live in the browser: toggle syntax, throw errors, switch tabs, and watch the architecture respond.
01
State management
Riverpod
Layering state with providers, notifiers, AsyncValue, and streams. Includes the folder structure, a provider-picker wizard, and a flavors/environment setup.
→
02
Error handling & observability
Errors & PostHog
Global catch points, a typed Failure model, one shared mapper, and a single logger to PostHog. Plus success events and automatic screen tracking through GoRouter.
→
03
Navigation
GoRouter
Declarative routing, static-const route identity, and StatefulShellRoute.indexedStack for tabs that keep their state. With a live bottom-nav demo and a route-tree explorer.
→
Growing
Natural next entries: deep linking (the native platform config that pairs with the routing tree), a testing guide (overriding providers and asserting the unhappy paths), and a Next.js companion for the web side of the stack.