Skip to content
Footrace Flutter

Glossary

Short definitions, each with one place to see it. Tags: Dart, Flutter, Riverpod, router (go_router), lib (a third-party package), Footrace (this app’s own names).

A

Section titled “A”
  • abstract final class (Dart). Cannot be instantiated or subclassed; used as a namespace of constants. app/lib/app/routes.dart:2, app/lib/design/tokens.dart:9. Dart primer
  • ActiveRaceStore (Footrace). Remembers the id of a race in progress so a killed app can return to it; read by pendingRaceProvider. app/lib/data/storage/active_race_store.dart:6. Failure modes
  • ApiException (Footrace). The one error type repositories throw: backend messages, status code, isNetwork. app/lib/data/api/api_exception.dart:5. Data layer
  • AppConfig (Footrace). Build-time config from --dart-define; the only reader of the defines. app/lib/core/config/app_config.dart:10. Build and release
  • AsyncNotifier (Riverpod). A notifier whose build returns a Future; its state is an AsyncValue. app/lib/features/auth/auth_notifier.dart:18. Riverpod primer
  • AsyncValue (Riverpod). Loading, data or error, optionally carrying the previous value. Consumed with .when(...). app/lib/features/race_tab/race_tab.dart:61.
  • async* / yield (Dart). A function that returns a Stream, emitting with yield. app/lib/data/socket/socket_service.dart:41-45.
  • AuthStatus (Footrace). unknown, signedOut, signedIn: what the router’s redirect switches on. app/lib/features/auth/auth_state.dart:4. Auth flow
  • autoDispose (Riverpod). Frees a provider’s state when nothing listens to it any more, running its onDispose callbacks. app/lib/features/queue/queue_notifier.dart:266.

B

Section titled “B”
  • Bot (steady bot) (Footrace). A server-side opponent. Queueing with bot: true pairs you with it at once; dev and QA only. app/lib/data/repositories/matchmaking_repository.dart:35-38, backend/lib/footrace_web/controllers/api/matchmaking_controller.ex:15.
  • Broadcast stream (Dart). A Stream with any number of listeners that drops events nobody hears. app/lib/tracking/race_tracker.dart:30.
  • build (Flutter). Returns a widget’s children. Runs often; never start work in it. app/lib/design/components/fr_eyebrow.dart:15. Flutter primer
  • BuildContext (Flutter). The widget’s position in the tree (it is the Element); used to look up theme, router and messenger. Flutter primer

C

Section titled “C”
  • Cascade .. (Dart). Calls a method and returns the receiver, not the result. app/lib/features/lobby/lobby_screen.dart:76-78.
  • ChannelException (Footrace). A refused channel join or push, carrying the server’s reason. app/lib/data/socket/channel_transport.dart:18. Realtime
  • Competitor (Footrace). One runner’s entry in a race (has its own id, distinct from the user id). CompetitorState at app/lib/data/models/race_snapshot.dart:119.
  • const (Dart). Compile-time constant; on a constructor, lets instances be built by the compiler and canonicalised. app/lib/features/auth/auth_state.dart:19-21.
  • ConsumerWidget / ConsumerStatefulWidget (Riverpod). Widgets that get a ref. app/lib/app/app.dart:9, app/lib/features/queue/queue_screen.dart:20.
  • context.fr (Footrace). Extension getter returning the FrTheme. app/lib/design/typography.dart:309-313. Design system
  • context.go / context.push (router). go replaces the stack with a location; push adds on top. app/lib/features/queue/queue_screen.dart:82, app/lib/features/race_tab/race_tab.dart:51.

D

Section titled “D”
  • --dart-define (Flutter). Compile-time key/value config read with String.fromEnvironment. Changing one needs a rebuild. app/lib/core/config/app_config.dart:41-48, app/env/dev.json.
  • DEV_TOOLS (Footrace). Define that enables the /dev route; on in debug by default. app/lib/app/router.dart:117-121.
  • Dio (lib). The HTTP client. One shared instance with interceptors. app/lib/data/api/api_client.dart:18-61. Data layer
  • dispose (Flutter, Riverpod). A State’s teardown (deinit); in Riverpod, ref.onDispose callbacks. app/lib/features/race/race_screen.dart:51-55.
  • dynamic (Dart). Type checking off for this value; mostly at JSON boundaries.

E

Section titled “E”
  • Element (Flutter). The long-lived instance behind a widget; holds State. Flutter primer
  • Enhanced enum (Dart). An enum with methods and getters. app/lib/data/models/race_snapshot.dart:5-27.
  • Extension (Dart). Adds members to an existing type, statically. app/lib/design/typography.dart:309.

F

Section titled “F”
  • factory constructor (Dart). A constructor that may return an existing object or a subtype; here, almost always fromJson. app/lib/data/models/user.dart:24.
  • FAKE_GPS (Footrace). Define that swaps real GPS for SimulatedLocationSource inside the service; ignored in release. app/lib/core/config/app_config.dart:29.
  • family (Riverpod). A provider parameterised by an argument; one state per argument. app/lib/features/race/race_notifier.dart:397-399.
  • Fixture contract test (Footrace). Decodes every saved backend payload into its model and back. app/test/data/fixture_contract_test.dart. Testing
  • FixQueue (Footrace). Durable per-race queue of GPS fixes on sembast, in the service isolate. app/lib/tracking/upload/fix_queue.dart:38. Tracking
  • FlutterActivity / FlutterAppDelegate (Flutter). The native classes that host the engine. app/android/app/src/main/kotlin/com/footraceapp/footrace_flutter/MainActivity.kt:5, app/ios/Runner/AppDelegate.swift:5.
  • flutter_foreground_task (lib). Runs Dart in an Android foreground service so tracking survives a locked screen. app/lib/tracking/location_service.dart:353-358.
  • FrTheme (Footrace). ThemeExtension with the type and colour roles Material lacks. app/lib/design/typography.dart:135.
  • Fr* components (Footrace). The design system’s widgets: FrCard, FrButton, … app/lib/design/components/. Design system
  • Future (Dart). One asynchronous value; a Promise. Dart primer
  • FutureProvider (Riverpod). A provider whose recipe is one async computation. app/lib/features/race/race_notifier.dart:403.

G

Section titled “G”
  • GlobalKey (Flutter). A key that gives access to a widget’s State from outside. app/lib/features/auth/login_screen.dart:21.
  • GoRoute (router). One path and the screen it builds. app/lib/app/router.dart:42. App shell
  • GpsFix (Footrace). One location sample. app/lib/tracking/gps_fix.dart:4.
  • guard (Footrace). Wraps an HTTP call so any Dio failure becomes ApiException. app/lib/data/api/api_client.dart:87.

H

Section titled “H”
  • Hot reload / hot restart (Flutter). Reload injects code and keeps state; restart reruns main(). Flutter primer

I

Section titled “I”
  • initState (Flutter). Runs once when a State is mounted; acquire resources here. app/lib/features/race/race_screen.dart:42-48.
  • Interceptor (lib, Dio). Hook on every request and error: adds the bearer token, handles 401. app/lib/data/api/api_client.dart:35-59.
  • Isolate (Dart). An independent Dart heap and event loop; talks only by messages. The app has two. Dart primer

K

Section titled “K”
  • Key / ValueKey (Flutter). Controls which Element is reused; also how tests find widgets. app/lib/features/race/race_screen.dart:30. Flutter primer
  • kNoAuth (Footrace). Request flag: no bearer token, and a 401 does not sign out (login, register). app/lib/data/api/api_client.dart:11.

L

Section titled “L”
  • late (Dart). Initialised on first read. app/lib/design/components/fr_section_header.dart:107.
  • LocalDistance (Footrace). Distance computed on the phone for instant feedback; the server’s figure wins when larger. app/lib/features/race/local_distance.dart:9.
  • LocationTaskHandler (Footrace). The code that runs inside the service isolate: samples, buffers, flushes every 2 s, uploads. app/lib/tracking/location_service.dart:37.
  • Lobby (Footrace). Open race requests you can join directly instead of queueing. app/lib/features/lobby/lobby_notifier.dart:33. Matchmaking flow

M

Section titled “M”
  • MaterialApp.router (Flutter). The root app widget, configured by a router. app/lib/app/app.dart:16-20.
  • Mixin / with (Dart). Reusable members, possibly with state, pulled into a class. app/lib/features/queue/queue_screen.dart:35-36.
  • mounted (Flutter). Whether a State is still in the tree; check after every await. app/lib/features/lobby/lobby_screen.dart:72.

N

Section titled “N”
  • Notifier (Riverpod). A class owning a provider’s synchronous state, with methods to change it. app/lib/core/units.dart:9.
  • Null safety (Dart). T? may be null, T never. ?., ??, ??=, !. Dart primer

O

Section titled “O”
  • Override (Riverpod). Replace a provider’s value or notifier in a scope, usually in tests. app/test/support/fakes.dart:544-575. Riverpod primer

P

Section titled “P”
  • Pattern (Dart). QueueWaiting(:final since), (a, b), 'x' || 'y': used in switch and destructuring. app/lib/features/queue/queue_screen.dart:114-144.
  • PermissionGate (Footrace). Notifier that works out which location permissions are missing. app/lib/tracking/permission_gate.dart:108.
  • Phoenix channel (lib, backend). Topic-based messaging over the socket. The app joins waiting:<slug> and race:<id>. backend/lib/footrace_web/channels/user_socket.ex:7-8. Realtime
  • Platform channel (Flutter). Message pipe between Dart and Kotlin/Swift; what plugins use. Flutter primer
  • Plugin (Flutter). A package with Dart API plus native code: geolocator, secure storage, etc.
  • PopScope (Flutter). Intercepts the back gesture. app/lib/features/race/race_screen.dart:98-102.
  • PositionUploader (Footrace). Drains FixQueue to POST /api/races/:id/positions in batches of 50 with backoff. app/lib/tracking/upload/position_uploader.dart:110.
  • @pragma('vm:entry-point') (Dart). Keeps a function alive through AOT tree-shaking so native code can call it. app/lib/tracking/location_service.dart:26.
  • Provider (Riverpod). The basic provider: a cached value from a recipe. app/lib/data/repositories/auth_repository.dart:89.
  • ProviderScope / ProviderContainer (Riverpod). Where provider state lives. The app has one scope at the root. app/lib/main.dart:16.
  • pubspec.yaml (Dart). The package manifest. app/pubspec.yaml.

Q

Section titled “Q”
  • QueueState (Footrace). Sealed state of matchmaking: idle, joining, waiting, matched, cancelled, error. app/lib/features/queue/queue_notifier.dart:15.

R

Section titled “R”
  • Race type (Footrace). A distance on offer (five_km, …), identified by its slug. app/lib/data/models/race_type.dart.
  • RaceEvent (Footrace). Sealed type of server pushes on race:<id>. app/lib/data/socket/race_channel.dart:5.
  • RaceSnapshot (Footrace). The engine’s state: race info plus every competitor. app/lib/data/models/race_snapshot.dart:165.
  • RaceState / RacePhase (Footrace). The race screen’s state and its phase (loading, countdown, racing, finished, aborted, error). app/lib/features/race/race_notifier.dart:20-24.
  • RaceUploadTarget (Footrace). What the UI isolate hands the service isolate before a race: race id, base URL, token, queue path. app/lib/tracking/upload/race_upload_target.dart:4.
  • Record (Dart). An anonymous typed tuple. app/lib/data/socket/channel_transport.dart:57.
  • redirect (router). Runs before every navigation and may send the user elsewhere; the auth gate. app/lib/app/router.dart:136-147.
  • ref.watch / ref.read / ref.listen (Riverpod). Subscribe, read once, react without rebuilding. Riverpod primer
  • refreshListenable (router). Makes the router re-run redirect when it fires. app/lib/app/router.dart:38.
  • RenderObject (Flutter). Does layout and paint. Flutter primer
  • Repository (Footrace). Abstract class + Api... implementation per backend area; the only code that knows URLs. app/lib/data/repositories/.

S

Section titled “S”
  • Sealed class (Dart). Closed set of subclasses; switch over it is exhaustive. app/lib/features/queue/queue_notifier.dart:15.
  • sembast (lib). Pure-Dart document database; stores the fix queue. app/lib/tracking/upload/fix_queue.dart:1.
  • setState (Flutter). Mark this State dirty so build runs next frame. app/lib/design/components/fr_card.dart:122.
  • Service isolate (Footrace). The second isolate, run by the foreground service, that samples GPS and uploads. Tracking
  • SocketTransport / ChannelTransport (Footrace). The narrow socket interfaces the app codes against; faked in tests. app/lib/data/socket/channel_transport.dart:33-61.
  • StatefulShellRoute (router). Bottom-tab shell where each tab keeps its own stack. app/lib/app/router.dart:48.
  • StatelessWidget / StatefulWidget / State (Flutter). Widget without / with a long-lived state object. Flutter primer
  • StateProvider (Riverpod). A bare mutable value; legacy style, used once. app/lib/features/leaderboard/leaderboard_notifier.dart:7.
  • Stream / StreamSubscription (Dart). Async sequence; a listen handle you must cancel. app/lib/features/race/race_notifier.dart:117-119.
  • StreamProvider (Riverpod). Exposes a stream’s latest event as AsyncValue. app/lib/data/socket/socket_service.dart:41.

T

Section titled “T”
  • Tear-off (Dart). A function or constructor referenced without calling it: DateTime.now, AuthNotifier.new. app/lib/core/clock.dart:7.
  • testApp / testOverrides (Footrace). Boot the app, or a container, with every platform provider faked. app/test/support/fakes.dart:485, :524. Testing
  • ThemeExtension (Flutter). Custom data attached to ThemeData. app/lib/design/typography.dart:135.
  • Tokens (Footrace). Named colours, spacing, radii, shadows. app/lib/design/tokens.dart.
  • TokenStore (Footrace). Where the JWT lives (Keychain/Keystore). app/lib/data/storage/token_store.dart:6.
  • typedef (Dart). Names a type, usually a function type. app/lib/core/clock.dart:5.

U

Section titled “U”
  • UnitsFormatter (Footrace). Every distance, pace and time string. app/lib/core/units.dart:27.
  • UserCache (Footrace). Last signed-in user in SharedPreferences, for offline start. app/lib/data/storage/user_cache.dart:10.

W

Section titled “W”
  • WaitingChannel (Footrace). Client for waiting:<slug>, which pushes match. app/lib/data/socket/waiting_channel.dart:107, backend/lib/footrace_web/channels/waiting_channel.ex:21.
  • Widget (Flutter). Immutable description of UI. Flutter primer
  • Widgetbook (lib). The component catalog app in widgetbook/. app/widgetbook/lib/main.dart:15. Design system
  • WidgetsBindingObserver (Flutter). Mixin for app lifecycle callbacks (paused, resumed). app/lib/features/queue/queue_screen.dart:60-71.