service-boundary-and-native

Service boundary and native

Every platform capability — reading "now", sharing, logging an event, fetching remote flags, calling a MethodChannel — crosses the app's layers as an injected interface. The interface names value types only; the concrete SDK lives in exactly one class; the composition root (main) wires one live impl; tests wire a deterministic fake. Abstract exactly what cannot run in a test — nothing more. This is the seam that keeps features pure, SDKs swappable, and the whole app testable headlessly.

Read the reference for the task at hand:

• references/service-interface.md — typed outcomes vs bool/throw, exhaustiveness, @useResult, hand-written env-fakes, the arrow-callback Future-drop hole, single write path.
• references/native-channels.md — MethodChannel placement, the cross-language contract ownership table, versioned-file-vs-shared_preferences traps, native-fast-path independence, the round-trip integration_test.
• references/multi-flavor.md — line-for-line composition roots, build flavors over runtime detection, per-flavor plugin pins, the banned-dependency CI graph gate.

Run scripts/check-service-boundaries.sh and scripts/check-flavor-graph.sh before a PR.

Non-negotiable rules

1. Every side effect is an injected interface, never a concrete SDK at the call site. Features, Notifiers, and repositories depend on the interface; the app imports the real SDK in exactly one live-impl class. WHY: one seam to swap, one place to quarantine platform quirks, zero SDK reach into pure code.
2. Abstract only what cannot run in flutter test. One interface + one real impl + one fake = justified. One interface + one impl + no fake = delete the interface. WHY: interfaces "for symmetry" are dead weight that hide where the real risk (untestable I/O) is.
3. Interface signatures reference value types only. Name a DateTime, a domain value object, a sealed outcome — never a plugin type, never a dart:io symbol. WHY: keeps the interface nameable from any layer and the SDK confined to one class.
4. Every method returns a typed result — failure is control flow, not a swallowed exception. Model a cancel, an empty fetch, an unavailable target as a sealed outcome or Result<T, F extends Failure>, never a thrown-and-forgotten exception. WHY: Dart requires no throws declaration, so an unhandled failure silently vanishes. See error-handling-typed-results for the Result/Failure spine.
5. The provider throws UnimplementedError until overridden — the provider IS the DI. No get_it, no service locator, no second container, no business logic in the provider body. WHY: a forgotten wiring becomes a loud startup failure instead of silent null data or a live SDK opening at import.
6. Wire exactly one live impl per interface at the composition root. main (per flavor) is the only place a live SDK is constructed; app.dart and every widget below are wiring-blind. WHY: the composition root is the single seam where the real world is chosen.
7. Tests install a hand-written fake that honours the contract — fakes over mocks. The fake's failure path must be reachable; a fake that always succeeds is a happy-path lie. implements (not extends) so a new interface method breaks the build. WHY: a passing test must reflect real behaviour, including the failure it exists to guard.
8. The clock is injected via clockProvider (a Clock from package:clock) — "now" has exactly one source. No DateTime.now() / math.Random() reachable from a view, Notifier, repository, or pure core; feature code reads ref.read(clockProvider).now(), pure core takes a Clock or the ambient clock. Never a bespoke ClockService/SystemClock. WHY: this is what makes date/streak/expiry logic deterministic by overriding with Clock.fixed(...). See value-objects-money-and-units for the injected Clock.
9. A mutating service feeds the single write path — persist before publish. A service that changes durable state is consumed by a repository method that commits (one transaction) before any state republishes. WHY: a crash mid-flow must never leave "acknowledged but not durable".
10. Every MethodChannel lives under one lib/native/ directory; nothing else creates one. A channel born inside a widget, repository, or Notifier is a defect regardless of how well it works. WHY: platform channels are the least testable code in the app and must be found in one place.
11. A cross-language shared format is a versioned contract with one owner per side, edited on both sides in the same commit, and proven by an integration_test. WHY: no compiler, analyzer, or unit test catches a renamed key across the language boundary — only a real round-trip does.