# flutter/flutter — codebase unpack

> Canonical page: https://codevetter.com/unpack/flutter

This is a deterministic Repo Unpack scan of flutter/flutter — a structural map, not a review, security audit, or maintainer-endorsed description.

- Scanned commit: acb8fd51143a49384799557cb1df6ecead61a55a (2026-09-22)
- Last upstream commit: Roll Dart SDK from 907d0c1bcd40 to b3460e4fb2b2 (1 revision) (#193144)
- Generated by codevetter 1.12.0 on 2026-09-22
- 4000 files scanned · 32.1 MB

## Languages

- C++: 1823 files
- C: 1784 files
- Markdown: 480 files
- Java: 314 files
- YAML: 314 files
- JSON: 256 files
- Swift: 141 files
- Kotlin: 107 files

## Repository structure

- engine/ — 1028 files
- dev/ — 1028 files
- packages/ — 1028 files
- examples/ — 570 files
- docs/ — 205 files
- .github/ — 42 files
- .agents/ — 41 files
- bin/ — 30 files

Probable source entrypoint: `packages/` (inferred from the tree, not upstream docs)

## Structural health signals

Average score 7.3/10 across 96 files; 25 hotspots. These are deterministic review leads, not proof of a bug.

## Recent history

- acb8fd51143a (2026-09-22) Roll Dart SDK from 907d0c1bcd40 to b3460e4fb2b2 (1 revision) (#193144)
- a2810c0ff080 (2026-09-22) Roll Dart SDK from 4c572fafd056 to 907d0c1bcd40 (4 revisions) (#193141)
- f6c140c9d533 (2026-09-22) Roll pub packages (#193138)
- a3ca57056ced (2026-09-21) Roll pub packages (#193129)
- 860ac7c6182e (2026-09-21) [Linux] Request a frame when a view starts rendering (#192911)

## Overview

flutter/flutter is the monorepo for the Flutter SDK. It contains the Dart framework (packages/flutter), the `flutter` CLI tool (packages/flutter_tools) that users invoke through the bin/flutter shell script, the merged C++ engine source (engine/src/flutter) built with GN/Ninja and pinned third-party deps in DEPS, and a large test/CI estate (dev/, .ci.yaml, .github/workflows). The tool bootstraps itself by downloading a Dart SDK and compiling an app-jit snapshot before dispatching to ~35 subcommands; the engine exposes a stable C embedder API plus platform embedders for Android, iOS/macOS, Windows, Linux, and Fuchsia.

## System map

The repo is a multi-language monorepo: shell entrypoints (bin/) bootstrap a Dart CLI (packages/flutter_tools), the Dart framework (packages/flutter) is the runtime library apps import, and the engine C++ code (engine/src/flutter) is built with GN and pinned external deps via DEPS. Runtime boundaries are: user shell -> flutter tool process -> device/emulator process running the engine -> Dart isolate running dart:ui + framework. Storage is the local bin/cache directory plus pub caches; external integrations are Google Cloud Storage artifact downloads, pub.dev, Gradle/Xcode toolchains, and the VM service protocol. CI is driven by LUCI via .ci.yaml which defers to dev/bots/test.dart shards; GitHub Actions only runs auxiliary checks.
- bin/flutter resolves its own path through symlinks via follow_links(), sources bin/internal/shared.sh, and calls shared::execute(); on Windows-like shells (MINGW/CYGWIN/MSYS) it execs flutter.bat instead. — [bin/flutter#L39-64](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/flutter#L39-L64)
- shared::execute() in shared.sh computes FLUTTER_ROOT, runs update_engine_version.sh, downloads the Dart SDK via bin/internal/update_dart_sdk.sh when the snapshot stamp is stale, compiles bin/cache/flutter_tools.snapshot with `dart --snapshot-kind=app-jit`, then execs the snapshot. — [bin/internal/shared.sh#L118-283](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L118-L283) [bin/internal/update_dart_sdk.sh](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/update_dart_sdk.sh)
- Snapshot invalidation is keyed on `git rev-parse HEAD` + FLUTTER_TOOL_ARGS stored in flutter_tools.stamp, and on pubspec.yaml being newer than pubspec.lock; updates are serialized with a flock/shlock/mkdir lock on fd 7 at bin/cache/.upgrade_lock. — [bin/internal/shared.sh#L124-180](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L124-L180) [bin/internal/shared.sh#L48-113](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L48-L113)
- The Dart-side tool entrypoint is packages/flutter_tools/bin/flutter_tools.dart, which just calls executable.main() in lib/executable.dart; main() builds a context overrides map and the command list via generateCommands(), then calls runner.run(). — [packages/flutter_tools/bin/flutter_tools.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/bin/flutter_tools.dart) [packages/flutter_tools/lib/executable.dart#L78-188](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L78-L188) [packages/flutter_tools/lib/executable.dart#L231-373](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L231-L373)
- runner.run() wraps execution in runInContext and runZonedGuarded, bootstraps ToolDependencies from ~35 globals (fs, platform, processManager, xcode, androidSdk, cache, analytics...), constructs FlutterCommandRunner, registers commands, and funnels all errors through _handleToolError. — [packages/flutter_tools/lib/runner.dart#L32-199](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L32-L199)
- The repo is a pub workspace: root pubspec.yaml lists ~70 workspace members spanning packages/*, dev/*, and examples/*, so a single pub get resolves the whole tree. — [pubspec.yaml#L1-80](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/pubspec.yaml#L1-L80)
- The engine lives in-repo under engine/src/flutter with a GN build (engine/src/flutter/BUILD.gn); third-party revisions (dart_revision, skia_revision, clang_version, reclient) are pinned in DEPS and synced with gclient. — [engine/src/flutter/BUILD.gn](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/BUILD.gn) [DEPS#L1-60](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/DEPS#L1-L60)
- The Dart<->C++ runtime boundary is dart:ui in engine/src/flutter/lib/ui: functions in hooks.dart are annotated @pragma('vm:entry-point') and are invoked directly by the engine (e.g. _runMain, _addView) to deliver platform events into PlatformDispatcher. — [engine/src/flutter/lib/ui/hooks.dart#L7-80](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/lib/ui/hooks.dart#L7-L80) [engine/src/flutter/lib/ui/platform_dispatcher.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/lib/ui/platform_dispatcher.dart)
- The embedder boundary is a stable C API in engine/src/flutter/shell/platform/embedder/embedder.h, with per-platform embedders under shell/platform/{android,darwin,windows,linux,fuchsia}; Android's embedder is the Java io.flutter.embedding.engine.FlutterEngine. — [engine/src/flutter/shell/platform/embedder/embedder.h](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/platform/embedder/embedder.h) [engine/src/flutter/shell/platform/android/io/flutter/embedding/engine/FlutterEngine.java](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/platform/android/io/flutter/embedding/engine/FlutterEngine.java) [engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h)
- Prebuilt engine artifacts are downloaded by packages/flutter_tools/lib/src/cache.dart from https://storage.googleapis.com (realm- and FLUTTER_STORAGE_BASE_URL-adjustable), organized by DevelopmentArtifact values gated behind Feature flags, and stamped under bin/cache. — [packages/flutter_tools/lib/src/cache.dart#L43-120](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/cache.dart#L43-L120) [packages/flutter_tools/lib/src/cache.dart#L537-590](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/cache.dart#L537-L590)
- CI source of truth is .ci.yaml (~7800 lines) consumed by LUCI/Cocoon; the flutter_drone recipe defers to dev/bots/test.dart with the shard key; GitHub workflows like tool-test-general.yml only run focused checks (e.g. SHARD=tool_tests SUBSHARD=general). — [.ci.yaml#L1-14](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.ci.yaml#L1-L14) [.github/workflows/tool-test-general.yml#L1-35](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.github/workflows/tool-test-general.yml#L1-L35) [dev/bots/test.dart#L87-140](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L87-L140)
- Physical-device end-to-end testing runs through dev/devicelab with its own task runner (dev/devicelab/bin/run.dart) and task library. — [dev/devicelab/bin/run.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/devicelab/bin/run.dart) [dev/devicelab/lib/framework](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/devicelab/lib/framework)

## Feature catalog

User-facing surface is dominated by the `flutter` CLI: generateCommands() registers ~35 FlutterCommand subclasses covering the whole app lifecycle (create, run, build, test, analyze, doctor, drive, install, screenshot, symbolize, upgrade/downgrade, channel, precache, clean, config, devices, emulators, logs, attach, daemon, debug-adapter, widget-preview, shell-completion, gen-l10n, assemble, plus hidden dev commands like update-packages and ide-config). Build subcommands fan out per platform (apk, appbundle, aar, ios, ios-framework, macos, macos-framework, linux, windows, web, swift-package). The framework packages provide the runtime libraries (material, cupertino, widgets, services, etc.) and companion packages (flutter_test, flutter_driver, integration_test, flutter_goldens, flutter_localizations, flutter_web_plugins, fuchsia_remote_debug_protocol).
- generateCommands() in executable.dart is the full CLI command table: AnalyzeCommand, AssembleCommand, AttachCommand, BuildCommand, ChannelCommand, CleanCommand, ConfigCommand, CustomDevicesCommand, CreateCommand, DaemonCommand, DebugAdapterCommand, DevicesCommand, DoctorCommand, DowngradeCommand, DriveCommand, EmulatorsCommand, GenerateCommand, GenerateLocalizationsCommand, InstallCommand, LogsCommand, PackagesCommand, PrecacheCommand, RunCommand, ScreenshotCommand, ShellCompletionCommand, TestCommand, WidgetPreviewCommand, UpgradeCommand, SymbolizeCommand, IdeConfigCommand, UpdatePackagesCommand. — [packages/flutter_tools/lib/executable.dart#L231-373](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L231-L373)
- RunCommandBase (shared by `flutter run` and `flutter drive`) exposes dozens of debugging flags: build modes, --dart-define, flavors, DDS options, DevTools options, trace-* profilers, --enable-impeller, --wasm, web renderer selection, wireless device refresh, and start-paused. — [packages/flutter_tools/lib/src/commands/run.dart#L36-150](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/run.dart#L36-L150)
- `flutter run` picks HotRunner when shouldUseHotMode(buildInfo) is true (and not web), otherwise ColdRunner; the choice determines whether hot reload/restart keybindings are offered. — [packages/flutter_tools/lib/src/commands/run.dart#L611-660](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/run.dart#L611-L660) [packages/flutter_tools/lib/src/run_hot.dart#L79-120](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L79-L120) [packages/flutter_tools/lib/src/run_cold.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_cold.dart)
- `flutter test` is implemented by TestCommand (commands/test.dart) and runs tests through the flutter_tester device or Chrome for web tests; it can build native assets via TestCompilerNativeAssetsBuilder. — [packages/flutter_tools/lib/src/commands/test.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/test.dart) [packages/flutter_tools/lib/executable.dart#L362-366](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L362-L366)
- `flutter doctor` runs a list of DoctorValidators (android_workflow, xcode, etc.) and prints diagnostics; DoctorCommand receives the shared globals.doctor singleton until migration to DI completes. — [packages/flutter_tools/lib/src/commands/doctor.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/doctor.dart) [packages/flutter_tools/lib/src/doctor.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/doctor.dart) [packages/flutter_tools/lib/executable.dart#L319-326](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L319-L326)
- `flutter daemon` exposes a JSON-over-stdio protocol for IDEs: messages are bracketed [json] frames parsed into DaemonMessage/DaemonEventData, support binary payloads via _binaryLength, and dispatch to registered Domain handlers (device, app, devtools, emulator, daemon domains). — [packages/flutter_tools/lib/src/daemon.dart#L14-45](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/daemon.dart#L14-L45) [packages/flutter_tools/lib/src/commands/daemon.dart#L307-422](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/daemon.dart#L307-L422)
- `flutter create` scaffolds projects from Mustache templates in packages/flutter_tools/templates (app, module, package, plugin, add_to_app, package_ffi, etc.) rendered via MustacheTemplateRenderer. — [packages/flutter_tools/lib/src/commands/create.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/create.dart) [packages/flutter_tools/templates](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/templates) [packages/flutter_tools/lib/executable.dart#L297-304](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L297-L304)
- `flutter build` is a BuildCommand umbrella whose subcommands are defined in commands/build_*.dart; Android builds go through AndroidGradleBuilder (android/gradle.dart), Apple builds through Xcode wrappers, web through Dart->JS/Wasm compilers. — [packages/flutter_tools/lib/src/commands/build.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/build.dart) [packages/flutter_tools/lib/src/commands/build_apk.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/build_apk.dart) [packages/flutter_tools/lib/src/commands/build_web.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/build_web.dart) [packages/flutter_tools/lib/src/android/gradle.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/android/gradle.dart)
- Feature flags gate platform support: FeatureFlags.allFeatures lists ~21 flags (web, linux/macos/windows desktop, android, ios, fuchsia, custom devices, native assets, swift package manager, windowing, lldb debugging, UIScene migration, riscv64, hcpp, tool extensions) toggled via `flutter config` and Feature.configSetting. — [packages/flutter_tools/lib/src/features.dart#L25-135](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/features.dart#L25-L135)
- `flutter precache` downloads DevelopmentArtifacts (android_gen_snapshot, android_maven, ios, web, macos, windows, linux, fuchsia, flutter_runner, universal, informative) into bin/cache/artifacts. — [packages/flutter_tools/lib/src/commands/precache.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/precache.dart) [packages/flutter_tools/lib/src/cache.dart#L53-120](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/cache.dart#L53-L120)
- packages/flutter is the framework library exporting widgets/material/cupertino/services/rendering/etc.; packages/flutter_test provides the test harness, flutter_driver and integration_test drive apps end-to-end, flutter_goldens compares golden images against Skia Gold. — [packages/flutter/lib/material.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/material.dart) [packages/flutter_test/lib/flutter_test.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_test/lib/flutter_test.dart) [pubspec.yaml#L70-80](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/pubspec.yaml#L70-L80)
- Hidden/dev-only commands include AssembleCommand (direct build-system target invocation used by Xcode/Gradle backends), UpdatePackagesCommand, IdeConfigCommand, DebugAdapterCommand (DAP server for editors), and ShellCompletionCommand. — [packages/flutter_tools/lib/src/commands/assemble.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/assemble.dart) [packages/flutter_tools/lib/src/commands/debug_adapter.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/debug_adapter.dart) [packages/flutter_tools/lib/executable.dart#L370-373](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L370-L373)

## Data flow

Tool data flow: argv -> executable.main -> FlutterCommandRunner (args package) -> FlutterCommand.verifyThenRun -> runCommand; all services resolve through an AppContext DI layer fed by globals.dart and the overrides map in executable.main. Runtime data flow: `flutter run` compiles Dart to kernel via ResidentCompiler, syncs sources+assets to the on-device DevFS over HTTP, and talks to the Dart VM service (vm_service package) for reload/attach; hot restart alternates a `.swap` dill name to dodge memory-mapped files. Framework data flow: runApp mounts the widget tree, drawFrame pumps build->layout->paint->composite into a Scene sent to the engine; MethodChannel calls serialize via codecs over BinaryMessenger into dart:ui's PlatformDispatcher.sendPlatformMessage, then through the engine's platform message handler to the embedder.
- Argument parsing is two-stage: findCommandName() in executable.dart does a throwaway parse to locate the command (handling -h/-? //? help idioms), then FlutterCommandRunner's real ArgParser (allowTrailingOptions: false) dispatches to the FlutterCommand. — [packages/flutter_tools/lib/executable.dart#L78-208](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L78-L208) [packages/flutter_tools/lib/src/runner/flutter_command_runner.dart#L63-120](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/runner/flutter_command_runner.dart#L63-L120)
- FlutterDevice.create() wires the per-device compile pipeline: a DevelopmentShaderCompiler wrapping ShaderCompiler for Impeller shaders, and a ResidentCompiler (via residentCompilerFactory) for incremental Dart kernel generation targeting device.targetPlatform. — [packages/flutter_tools/lib/src/resident_runner.dart#L62-100](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/resident_runner.dart#L62-L100) [packages/flutter_tools/lib/src/compile.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/compile.dart)
- DevFS (devfs.dart) is the transport for hot development: it uploads compiled kernel files and asset diffs to a per-app filesystem served by the VM service on the device. — [packages/flutter_tools/lib/src/devfs.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/devfs.dart) [packages/flutter_tools/lib/src/resident_runner.dart#L30-48](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/resident_runner.dart#L30-L48)
- HotRunner._reloadSources() orchestrates reload: projectFileInvalidator computes changed files, ResidentCompiler.recompile emits a partial dill, devFS pushes it, _reloadSourcesService calls VM reloadSources, then _reassembleHelper triggers WidgetsBinding reassemble in the app. — [packages/flutter_tools/lib/src/run_hot.dart#L29-67](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L29-L67) [packages/flutter_tools/lib/src/run_hot.dart#L957-1040](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L957-L1040)
- Hot restart rewrites main.dart.dill into the device DevFS under alternating names (with/without .swap) because the previous dill may still be memory-mapped by the Windows embedder. — [packages/flutter_tools/lib/src/run_hot.dart#L109-120](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L109-L120)
- The BuildSystem executes a Target DAG where each Target declares Source-pattern inputs/outputs; FileStore hashes file contents (md5/timestamp) and stamp files record inputs+outputs per run so unchanged targets are skipped; work is pooled at kMaxOpenFiles=64 concurrent file ops. — [packages/flutter_tools/lib/src/build_system/build_system.dart#L29-100](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/build_system/build_system.dart#L29-L100)
- App startup in the framework: runApp(app) -> WidgetsFlutterBinding.ensureInitialized() -> binding.wrapWithDefaultView(app) -> scheduleAttachRootWidget -> scheduleWarmUpFrame; frames then flow through handleBeginFrame/handleDrawFrame (documented 10-phase pipeline) -> drawFrame -> scene handed to the engine. — [packages/flutter/lib/src/widgets/binding.dart#L1887-1957](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src/widgets/binding.dart#L1887-L1957) [packages/flutter/lib/src/widgets/binding.dart#L1483-1540](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src/widgets/binding.dart#L1483-L1540)
- Platform channel flow: MethodChannel._invokeMethod encodes calls with a MethodCodec, sends through binaryMessenger -> dart:ui PlatformDispatcher.sendPlatformMessage -> engine.cc's platform message handling -> the embedder's registered channel handler; built-in channels are named in engine.cc (flutter/assets, flutter/lifecycle, flutter/navigation, flutter/localization, flutter/settings, flutter/isolate). — [packages/flutter/lib/src/services/platform_channel.dart#L291-418](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src/services/platform_channel.dart#L291-L418) [engine/src/flutter/lib/ui/platform_dispatcher.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/lib/ui/platform_dispatcher.dart) [engine/src/flutter/shell/common/engine.cc#L23-28](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/common/engine.cc#L23-L28)
- Tool persistent state lives in bin/cache plus user config: Config (flutter config settings), PersistentToolState, and unified_analytics telemetry gated by --disable-analytics/--enable-analytics/--suppress-analytics handled in runner.run before dispatch. — [packages/flutter_tools/lib/runner.dart#L119-148](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L119-L148) [packages/flutter_tools/lib/src/persistent_tool_state.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/persistent_tool_state.dart)
- Crash path: unhandled errors in the zone go to _handleToolErrorImpl -> CrashReportSender.sendReport (skipped when running on a bot or with --local-engine) and a local flutter_*.log file is written to the cwd (falling back to system temp) containing command, exception, stack, and `flutter doctor` output. — [packages/flutter_tools/lib/runner.dart#L208-397](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L208-L397) [packages/flutter_tools/lib/src/reporting/crash_reporting.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/reporting/crash_reporting.dart)
- The daemon protocol multiplexes IDE traffic: DaemonConnection parses [json] envelopes and optional binary streams, dispatches to Domain handlers registered with registerDomain() (app, device, emulator, devtools), and emits events back over stdout. — [packages/flutter_tools/lib/src/daemon.dart#L14-45](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/daemon.dart#L14-L45) [packages/flutter_tools/lib/src/commands/daemon.dart#L307-422](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/daemon.dart#L307-L422)

## Behavior traces

Three end-to-end flows were traced. (1) CLI bootstrap: bin/flutter -> shared.sh -> Dart SDK fetch + snapshot compile -> flutter_tools.dart -> executable.main -> runner.run -> FlutterCommandRunner -> FlutterCommand.runCommand. (2) `flutter run` hot path: RunCommand picks HotRunner -> FlutterDevice.create (ResidentCompiler + shader compiler) -> device launch -> attach to VM service -> keystroke-triggered _reloadSources -> DevFS push -> VM reloadSources -> reassemble. (3) On-device app start: embedder creates Shell/Engine -> RuntimeController.LaunchRootIsolate -> dart:ui _runMain -> user main() -> runApp -> WidgetsFlutterBinding frame pipeline -> rasterized by the engine's Animator/Rasterizer.
- Bootstrap order (posix): bin/flutter -> follow_links -> source bin/internal/shared.sh -> shared::execute -> update_engine_version.sh -> staleness check on flutter_tools.stamp -> _wait_for_lock -> update_dart_sdk.sh -> pub_upgrade_with_retry (10 tries) -> `dart --snapshot-kind=app-jit` compile -> exec dart flutter_tools.snapshot "$@". — [bin/flutter#L51-64](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/flutter#L51-L64) [bin/internal/shared.sh#L118-191](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L118-L191) [bin/internal/shared.sh#L196-283](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L196-L283)
- Guard rails in bootstrap: shared::execute refuses to run without git on PATH and without $FLUTTER_ROOT/.git (must be a real clone), warns when EUID==0 outside Docker/CI, and sources bin/internal/bootstrap.sh first if present. — [bin/internal/shared.sh#L196-242](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L196-L242)
- Tool dispatch order: bin/flutter_tools.dart main -> executable.main (sets Cache.flutterRoot via defaultFlutterRoot) -> runner.run -> runInContext -> ToolDependencies.bootstrap -> FlutterCommandRunner -> commands().forEach(runner.addCommand) -> runner.run(args) -> FlutterCommand.verifyThenRun -> runCommand. — [packages/flutter_tools/bin/flutter_tools.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/bin/flutter_tools.dart) [packages/flutter_tools/lib/executable.dart#L105-188](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L105-L188) [packages/flutter_tools/lib/runner.dart#L55-150](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L55-L150)
- Error exit contract: UsageException -> exit 64; ToolExit -> its exitCode or 1; ProcessExit(immediate) -> direct exit; missing-git ProcessException -> friendly message + exit 1; anything else -> crash report path with exit 1. — [packages/flutter_tools/lib/runner.dart#L232-354](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L232-L354)
- `flutter run` flow: RunCommand.runCommand computes BuildInfo via getBuildInfo(), picks hotMode = shouldUseHotMode(buildInfo), constructs HotRunner(flutterDevices, debuggingOptions...) or ColdRunner, then ResidentRunner.run() launches the app on each Device and attaches to the VM service (vmservice.dart). — [packages/flutter_tools/lib/src/commands/run.dart#L611-660](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/run.dart#L611-L660) [packages/flutter_tools/lib/src/commands/run.dart#L695-840](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/run.dart#L695-L840) [packages/flutter_tools/lib/src/resident_runner.dart#L1082](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/resident_runner.dart#L1082) [packages/flutter_tools/lib/src/vmservice.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/vmservice.dart)
- Hot reload flow: user presses r -> HotRunner.reload -> _reloadSources -> projectFileInvalidator finds changed sources -> ResidentCompiler.recompile -> devFS update -> _reloadSourcesService issues VM-service reloadSources -> _reassembleHelper invokes reassemble in the app -> DeviceReloadReport aggregated per view; timings tracked via named Stopwatches (reloadSources:reload, :vm, :reassemble). — [packages/flutter_tools/lib/src/run_hot.dart#L178-265](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L178-L265) [packages/flutter_tools/lib/src/run_hot.dart#L957-1040](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L957-L1040) [packages/flutter_tools/lib/src/run_hot.dart#L72-77](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L72-L77)
- Engine app launch flow: the embedder (embedder.h API or platform embedder like FlutterEngine.java) creates a Shell, which constructs Engine with a RuntimeController; Engine::Run/LaunchRootIsolate starts the Dart isolate, which enters dart:ui's _runMain (hooks.dart) -> user's main() -> runApp -> WidgetsFlutterBinding.ensureInitialized + scheduleAttachRootWidget + scheduleWarmUpFrame. — [engine/src/flutter/shell/common/engine.cc#L36-90](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/common/engine.cc#L36-L90) [engine/src/flutter/shell/common/engine.cc#L248-282](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/common/engine.cc#L248-L282) [engine/src/flutter/lib/ui/hooks.dart#L424](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/lib/ui/hooks.dart#L424) [packages/flutter/lib/src/widgets/binding.dart#L1887-1957](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src/widgets/binding.dart#L1887-L1957)
- Frame pipeline order (documented in binding.dart): transient callbacks -> handleBeginFrame (animations, transient frame callbacks) -> microtasks -> handleDrawFrame -> build/layout/paint -> compositing -> semantics -> finalization; super.drawFrame() ordering keeps the layer stack consistent. — [packages/flutter/lib/src/widgets/binding.dart#L1483-1577](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src/widgets/binding.dart#L1483-L1577)
- `flutter test` flow on CI: LUCI target -> flutter_drone recipe -> `dart dev/bots/test.dart` -> selectShard() picks the shard runner (e.g. frameworkTestsRunner, _runToolTests) -> suite runner invokes `flutter test` with flutterTestArgs; --local-engine flags are exported as FLUTTER_LOCAL_ENGINE env vars for subprocesses. — [dev/bots/test.dart#L87-140](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L87-L140) [.ci.yaml#L9-10](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.ci.yaml#L9-L10)
- First-run persistence flow: when artifacts are missing, commands call Cache.updateAll -> downloads zip from storage.googleapis.com -> unzip into bin/cache/artifacts -> stamp files written; failed downloads leave no partial artifacts because downloads go through temp files (cache.dart Net/HttpClient path). — [packages/flutter_tools/lib/src/cache.dart#L246-253](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/cache.dart#L246-L253) [packages/flutter_tools/lib/src/cache.dart#L537-590](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/cache.dart#L537-L590) [packages/flutter_tools/lib/src/flutter_cache.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/flutter_cache.dart)

## Testing signals

Testing is extensive and shard-oriented. dev/bots/test.dart is the single entrypoint: it maps SHARD/SUBSHARD env vars to suite runners under dev/bots/suite_runners and randomizes test order within shards (seeded via --test-randomize-ordering-seed). Framework unit/widget tests live in packages/flutter/test mirroring lib/; tool tests live in packages/flutter_tools/test split into shard dirs (general.shard, commands.shard/{hermetic,permeable}, web.shard, integration.shard, android_*_integration.shard). Engine C++ unit tests sit next to sources (*_unittests.cc). Golden-image testing goes through packages/flutter_goldens (Skia Gold), device-level integration through dev/devicelab and dev/integration_tests, and coverage via .github/workflows/coverage.yml.
- dev/bots/test.dart is the repo-wide test entrypoint: `dart dev/bots/test.dart` runs all tests; SHARD and SUBSHARD env vars select subsets (e.g. SHARD=framework_tests SUBSHARD=widgets, SHARD=tool_tests SUBSHARD=general); --dry-run lists what would run. — [dev/bots/test.dart#L1-42](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L1-L42) [dev/bots/test.dart#L87-140](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L87-L140)
- Tests within a shard are executed in random order to catch inter-test dependencies; --test-randomize-ordering-seed=<n> reproduces a given order. — [dev/bots/test.dart#L35-38](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L35-L38) [dev/bots/test.dart#L103-105](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L103-L105)
- Suite runners are modular: dev/bots/suite_runners/run_*.dart files each own one shard (framework, web, analyze, customer_testing, docs, verify_binaries_codesigned, fuchsia_precache, skp_generator, android hardware smoke, java17 integration, preview integration). — [dev/bots/suite_runners](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/suite_runners) [dev/bots/test.dart#L52-69](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L52-L69)
- Framework tests live in packages/flutter/test mirroring lib/ structure (animation, cupertino, material, widgets, services, semantics, rendering, ...); flutter_test provides testWidgets/pumpWidget and _goldens_io.dart/_goldens_web.dart for golden comparisons. — [packages/flutter/test](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/test) [packages/flutter_test/lib/flutter_test.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_test/lib/flutter_test.dart)
- Tool tests are sharded by directory: packages/flutter_tools/test/{general.shard,commands.shard,web.shard,integration.shard,android_java17_integration.shard,android_preview_integration.shard}; commands.shard is further split into hermetic and permeable subdirs. — [packages/flutter_tools/test](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/test)
- Engine C++ code uses gtest-style unit tests co-located with sources (engine_unittests.cc, animator_unittests.cc, rasterizer_unittests.cc, pipeline_unittests.cc, persistent_cache_unittests.cc) under engine/src/flutter/shell/common; there is also engine/src/flutter/testing for harnesses. — [engine/src/flutter/shell/common/engine_unittests.cc](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/common/engine_unittests.cc) [engine/src/flutter/shell/common/rasterizer_unittests.cc](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/common/rasterizer_unittests.cc) [engine/src/flutter/testing](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/testing)
- Device-lab integration tests run on real hardware via dev/devicelab (bin/run.dart task runner + lib/tasks task library); dev/integration_tests contains ~35 test apps wired into the pub workspace. — [dev/devicelab/bin/run.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/devicelab/bin/run.dart) [dev/devicelab/lib/tasks](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/devicelab/lib/tasks) [pubspec.yaml#L38-67](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/pubspec.yaml#L38-L67)
- CI wiring: .ci.yaml declares per-commit LUCI targets with platform_properties (OS, cores, device_type, kvm, dependencies like android_sdk/open_jdk/gradle_dists versions) and enabled_branches master + release candidates. — [.ci.yaml#L14-80](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.ci.yaml#L14-L80)
- GitHub Actions runs auxiliary checks only: tool-test-general.yml runs the tool_tests general subshard on PRs touching dev/, packages/flutter_tools/, bin/, engine/, .ci.yaml, DEPS; coverage.yml handles coverage. — [.github/workflows/tool-test-general.yml#L1-35](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.github/workflows/tool-test-general.yml#L1-L35) [.github/workflows/coverage.yml](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.github/workflows/coverage.yml)
- Static analysis is enforced: root analysis_options.yaml + analysis_options_common.yaml apply repo-wide lints, and dev/bots/analyze.dart is a custom analysis shard runner (plus check_code_samples.dart, check_examples_cross_imports.dart). — [analysis_options.yaml](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/analysis_options.yaml) [dev/bots/analyze.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/analyze.dart) [dev/bots/check_code_samples.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/check_code_samples.dart)
- Test ownership is tracked in TESTOWNERS at repo root; dev/forbidden_from_release_tests guards that certain tests never run on release branches. — [TESTOWNERS](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/TESTOWNERS) [dev/forbidden_from_release_tests](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/forbidden_from_release_tests)
- Coverage/testing gaps are partially self-reported: framework_coverage is its own shard (run_framework_coverage_tests.dart) implying measured coverage enforcement rather than incidental. (inferred) — [dev/bots/suite_runners/run_framework_coverage_tests.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/suite_runners/run_framework_coverage_tests.dart) [dev/bots/test.dart#L127](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L127)

## Risk map

The biggest risk surface is the bootstrap supply chain: every fresh clone downloads and executes a Dart SDK and prebuilt engine artifacts over HTTPS, with host-overridable base URLs. Crash reporting and analytics exfiltrate command lines and stack traces (gated but present). Cross-platform shell logic is duplicated between .sh/.bat pairs that must be manually kept in sync. The locking scheme degrades to mkdir on NFS, and cache invalidation leans on file mtimes. The merged monorepo concentrates blast radius: .ci.yaml is ~7800 lines, DEPS pins a dozen external revisions, and 'isolated' files must not leak into google3 builds.
- Supply-chain: bin/internal/update_dart_sdk.sh downloads the Dart SDK from ${FLUTTER_STORAGE_BASE_URL:-https://storage.googleapis.com} at first run; cache.dart similarly downloads engine artifacts and CIPD packages from Google endpoints — a hostile mirror or MITM upstream would execute code on dev machines. — [bin/internal/update_dart_sdk.sh#L133-178](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/update_dart_sdk.sh#L133-L178) [packages/flutter_tools/lib/src/cache.dart#L537-590](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/cache.dart#L537-L590)
- Telemetry exfiltration: runner.dart sends analytics events and, on crashes, sends a report containing the full command line, exception type, stack trace, and flutter doctor output via CrashReportSender — suppressed on bots and for --local-engine runs but on by default. — [packages/flutter_tools/lib/runner.dart#L290-340](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L290-L340) [packages/flutter_tools/lib/src/reporting/crash_reporting.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/reporting/crash_reporting.dart)
- dev/bots/serviceaccount.enc is an encrypted service-account blob committed to the repo — a secrets-adjacent file whose decryption path lives in CI infrastructure. — [dev/bots/serviceaccount.enc](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/serviceaccount.enc)
- Duplicated bootstrap logic: bin/flutter, flutter.bat, shared.sh, and shared.bat carry mirrored logic and header comments explicitly warn to keep them consistent — drift between them is a recurring hazard. — [bin/flutter#L6-12](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/flutter#L6-L12) [bin/internal/shared.sh#L6-12](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L6-L12) [bin/internal/shared.bat](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.bat)
- Upgrade locking degrades gracefully but unevenly: flock -> shlock -> mkdir fallback; flock errors are swallowed (NFS needs write fds), and the mkdir lock relies on atomic directory creation, so concurrent first-runs on exotic filesystems can race. — [bin/internal/shared.sh#L46-113](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L46-L113)
- Cache invalidation relies on pubspec.yaml-vs-pubspec.lock mtime comparison plus a hand-maintained compilekey (revision:FLUTTER_TOOL_ARGS); a NOP pub upgrade touches pubspec.lock (issue 171024 workaround) — subtle staleness bugs have occurred here. — [bin/internal/shared.sh#L34-36](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L34-L36) [bin/internal/shared.sh#L124-146](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L124-L146)
- Hot restart correctness depends on a filename-swapping hack (.swap dill) because Windows embedders memory-map the previous dill — fragile coupling between tool behavior and embedder file semantics. — [packages/flutter_tools/lib/src/run_hot.dart#L109-120](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L109-L120)
- google3 divergence: executable.main notes WebRunner/DevTools/mustache deps differ in google3 and files under lib/src/isolated are 'intentionally excluded from google3 tooling' — edits crossing that boundary break internal builds invisibly to OSS CI. (inferred) — [packages/flutter_tools/lib/executable.dart#L61-73](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L61-L73) [packages/flutter_tools/lib/executable.dart#L140-155](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L140-L155) [packages/flutter_tools/lib/src/isolated/build_targets.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/isolated/build_targets.dart)
- DEPS pins dart_revision, skia_revision, clang_version, reclient_version and more; comments warn that dart rolls must also update transitive deps via //tools/dart/create_updated_flutter_deps.py — manual edits produce skewed toolchains. — [DEPS#L30-60](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/DEPS#L30-L60)
- .ci.yaml is ~7847 lines declaring hundreds of LUCI targets with pinned dependency versions (android_sdk 37v2, open_jdk 21, multiple gradle dists) — a single malformed property breaks scheduling across the fleet. — [.ci.yaml#L31-80](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.ci.yaml#L31-L80)
- The tool writes to shared mutable state in $FLUTTER_ROOT/bin/cache and only warns (with a paperclip) when run as root outside containers/CI — careless sudo usage corrupts the cache for the owning user. — [bin/internal/shared.sh#L221-227](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L221-L227) [bin/internal/shared.sh#L118-120](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L118-L120)
- Error-handling depth: _handleToolErrorImpl nests a catch-all inside the crash-report path and deliberately throws ProcessExit(immediate) to break potential infinite error loops — complex error semantics easy to regress. — [packages/flutter_tools/lib/runner.dart#L340-352](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L340-L352)

## Extension points

The repo is built for extension at several layers. CLI: add a FlutterCommand subclass and register it in generateCommands(). DI: almost every service resolves through AppContext/globals, and runner.run accepts a per-type overrides map used for google3 and tests. Build: the BuildSystem runs Target subclasses registered via BuildTargets. Platform support: Feature flags + DevelopmentArtifacts + Device/DeviceDiscovery implementations (incl. custom-devices JSON config). Tool-side: an experimental ExtensionManager/ExtensionEntryPoint mechanism loads tool extensions (linux prototype wired in already). IDE surface: daemon Domains. Engine side: the embedder.h C API plus platform channels/MethodChannel for plugins, and dart_plugin_registrant for Dart-side plugin init.
- New CLI commands: subclass FlutterCommand (runner/flutter_command.dart), register an instance in the generateCommands() list in executable.dart — this is the single command table for the whole tool. — [packages/flutter_tools/lib/executable.dart#L231-373](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L231-L373) [packages/flutter_tools/lib/src/runner/flutter_command.dart#L1-52](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/runner/flutter_command.dart#L1-L52)
- Feature flags: add a Feature constant and a getter on FeatureFlags; flags get a configSetting consumed by `flutter config` and gate artifacts/commands — documented in docs/contributing/Feature-flags.md. — [packages/flutter_tools/lib/src/features.dart#L15-135](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/features.dart#L15-L135) [docs/contributing/Feature-flags.md](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/docs/contributing/Feature-flags.md)
- Build steps: implement a Target subclass (inputs/outputs via Source patterns + a build action) and register it through the BuildTargets abstraction (BuildTargetsImpl in isolated/build_targets.dart overrides the interface). — [packages/flutter_tools/lib/src/build_system/build_system.dart#L55-100](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/build_system/build_system.dart#L55-L100) [packages/flutter_tools/lib/src/isolated/build_targets.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/isolated/build_targets.dart)
- Dependency injection: services are fetched with context.get<T>()/globals.* (base/context.dart, globals.dart) and runner.run takes an overrides map <Type, Generator> — executable.main already uses it for Logger, AnsiTerminal, WebRunnerFactory, DevtoolsLauncher, TemplateRenderer, PreRunValidator, BuildTargets. — [packages/flutter_tools/lib/executable.dart#L140-186](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L140-L186) [packages/flutter_tools/lib/src/base/context.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/base/context.dart) [packages/flutter_tools/lib/src/globals.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/globals.dart)
- Tool extensions: ExtensionManager + ExtensionEntryPoint (experimental/extension_manager.dart, extension_discovery.dart) load external tool extensions; the linux prototype entry point is already wired into executable.main behind isToolExtensionsEnabled. — [packages/flutter_tools/lib/executable.dart#L114-135](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L114-L135) [packages/flutter_tools/lib/src/experimental/extension_manager.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/experimental/extension_manager.dart) [packages/flutter_tools/lib/src/experimental/extension_discovery.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/experimental/extension_discovery.dart)
- New device types: implement Device + DeviceDiscovery under the device manager (flutter_device_manager.dart), or declare SSH-based custom devices consumed by CustomDevicesCommand and custom_devices config. — [packages/flutter_tools/lib/src/flutter_device_manager.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/flutter_device_manager.dart) [packages/flutter_tools/lib/src/commands/custom_devices.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/custom_devices.dart) [packages/flutter_tools/lib/src/device.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/device.dart)
- Doctor/validators: DoctorValidator implementations are aggregated in doctor.dart workflows (android_workflow, iosWorkflow); AnalyzeCommand additionally accepts a list of ProjectValidator plugins (GeneralInfoProjectValidator, VariableDumpMachineProjectValidator). — [packages/flutter_tools/lib/src/doctor.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/doctor.dart) [packages/flutter_tools/lib/src/doctor_validator.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/doctor_validator.dart) [packages/flutter_tools/lib/executable.dart#L238-251](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L238-L251)
- IDE daemon protocol: new RPC surfaces are added as Domain subclasses registered via registerDomain() in DaemonCommand (existing domains cover app, device, emulator, daemon, devtools). — [packages/flutter_tools/lib/src/commands/daemon.dart#L307-422](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/commands/daemon.dart#L307-L422)
- Hot-runner hooks: HotRunnerConfig exposes setupHotRestart/setupHotReload/updateDevFSComplete/runPreShutdownOperations overridable via context.get<HotRunnerConfig>() — used by embedders like google3 to customize reload behavior. — [packages/flutter_tools/lib/src/run_hot.dart#L37-68](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/run_hot.dart#L37-L68)
- Engine platform ports: implement the embedder.h C API (or a platform embedder under shell/platform/) and bridge platform channels; Dart-side plugins register through dart_plugin_registrant.dart. — [engine/src/flutter/shell/platform/embedder/embedder.h](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/platform/embedder/embedder.h) [packages/flutter/lib/src/dart_plugin_registrant.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src/dart_plugin_registrant.dart) [packages/flutter/lib/src/services/platform_channel.dart#L291-418](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src/services/platform_channel.dart#L291-L418)
- Project scaffolding: `flutter create` templates live in packages/flutter_tools/templates (app, module, plugin, package_ffi...) rendered through TemplateRenderer; ExtensionTemplateManager can add extension-provided templates. — [packages/flutter_tools/templates](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/templates) [packages/flutter_tools/lib/executable.dart#L123-135](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L123-L135)
- Test infrastructure plugins: dev/bots suite runners follow the ShardRunner typedef — adding a shard means writing a run_*.dart under dev/bots/suite_runners and registering it in the selectShard map plus a matching .ci.yaml target. — [dev/bots/test.dart#L71-140](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L71-L140) [dev/bots/suite_runners](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/suite_runners) [.ci.yaml](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.ci.yaml)

## Contributor handoff

This repo punishes agents that skip the bootstrap layer: the CLI only works from a real git clone with git on PATH, and editing flutter_tools' pubspec triggers a full snapshot rebuild on next run. Shell logic is duplicated between .sh and .bat files and must be kept in sync. The DI layer (context.get/globals + overrides) is the sanctioned way to reach services — do not construct singletons directly. Most engine-facing changes need a local engine build via --local-engine flags. Tests run through dev/bots/test.dart with SHARD/SUBSHARD, and the authoritative CI config is .ci.yaml, not .github/workflows.
- Read first (tool work): bin/internal/shared.sh (bootstrap+locking), packages/flutter_tools/lib/executable.dart (command table + overrides), lib/runner.dart (error/exit semantics), lib/src/runner/flutter_command.dart + flutter_command_runner.dart (arg plumbing), lib/src/base/context.dart + globals.dart (DI). — [bin/internal/shared.sh](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh) [packages/flutter_tools/lib/executable.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart) [packages/flutter_tools/lib/runner.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart) [packages/flutter_tools/lib/src/runner/flutter_command_runner.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src/runner/flutter_command_runner.dart)
- The tool hard-fails if $FLUTTER_ROOT/.git is missing or git is not on PATH — packaged archives rely on a different code path, so test changes against a real clone. — [bin/internal/shared.sh#L229-242](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L229-L242)
- Editing packages/flutter_tools/pubspec.yaml invalidates the tool snapshot (mtime check) — the next `flutter` invocation rebuilds it; commit pubspec.lock consistently or users hit unexpected rebuilds. — [bin/internal/shared.sh#L124-146](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L124-L146)
- Keep paired scripts in sync by convention: bin/flutter <-> flutter.bat, shared.sh <-> shared.bat, update_dart_sdk.sh <-> .ps1, update_engine_version.sh <-> .ps1 — headers explicitly demand parity. — [bin/flutter#L6-12](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/flutter#L6-L12) [bin/internal/shared.sh#L6-12](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/bin/internal/shared.sh#L6-L12)
- Files under packages/flutter_tools/lib/src/isolated are excluded from google3; anything depending on dwds/devtools sources must stay there or be injected via the overrides map — moving imports out silently breaks internal builds. — [packages/flutter_tools/lib/executable.dart#L61-73](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L61-L73) [packages/flutter_tools/lib/executable.dart#L140-155](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/executable.dart#L140-L155)
- Run tests the repo's way: `dart dev/bots/test.dart` with SHARD=/SUBSHARD= (e.g. SHARD=tool_tests SUBSHARD=general), or `flutter test` inside a package dir; pass --local-engine=host_debug_unopt when validating against a locally built engine. — [dev/bots/test.dart#L25-40](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L25-L40) [dev/bots/test.dart#L84-103](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L84-L103)
- Framework edits: source in packages/flutter/lib/src/<area> mirrors tests in packages/flutter/test/<area>; golden-image changes flow through packages/flutter_goldens and Skia Gold — expect golden tests to fail until images are triaged. — [packages/flutter/lib/src](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/lib/src) [packages/flutter/test](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter/test) [packages/flutter_goldens](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_goldens)
- Engine edits live in engine/src/flutter (GN/Ninja, not pub): unit tests are *_unittests.cc beside sources; DEPS holds pinned dep revisions that should be rolled with the documented tooling rather than hand-edited. — [engine/src/flutter/shell/common/engine_unittests.cc](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/shell/common/engine_unittests.cc) [DEPS#L30-60](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/DEPS#L30-L60) [engine/src/flutter/BUILD.gn](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter/BUILD.gn)
- Lint/style: every Dart file starts with the BSD license header; root analysis_options.yaml/analysis_options_common.yaml enforce strict lints; dev/bots/analyze.dart plus cross-import checkers run in CI — run them before pushing. — [analysis_options.yaml](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/analysis_options.yaml) [analysis_options_common.yaml](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/analysis_options_common.yaml) [dev/bots/analyze.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/analyze.dart) [dev/bots/check_tests_cross_imports.dart](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/check_tests_cross_imports.dart)
- CI truth source is .ci.yaml + dev/bots/test.dart shards; .github/workflows only runs auxiliary PR checks — adding a CI target means editing .ci.yaml (and likely registering a suite runner), not a GitHub workflow. — [.ci.yaml#L1-14](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.ci.yaml#L1-L14) [dev/bots/test.dart#L124-140](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/dev/bots/test.dart#L124-L140) [.github/workflows/tool-test-general.yml#L1-35](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/.github/workflows/tool-test-general.yml#L1-L35)
- Error paths are contractual: throw ToolExit/throwToolExit for user-facing failures (maps to exit codes), UsageException gives exit 64 — never call exit() directly from command code because shutdown hooks and crash reporting are bypassed. — [packages/flutter_tools/lib/runner.dart#L243-265](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/runner.dart#L243-L265)
- Common trap: 'files scanned' inventories miss most of this repo — the file walk capped at 4000 of a much larger tree; rely on grep/glob inside packages/flutter_tools/lib/src and engine/src/flutter rather than assuming a small codebase. (inferred) — [packages/flutter_tools/lib/src](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/packages/flutter_tools/lib/src) [engine/src/flutter](https://github.com/flutter/flutter/blob/acb8fd51143a49384799557cb1df6ecead61a55a/engine/src/flutter)

Source repository: https://github.com/flutter/flutter
Full evidence corpus: https://github.com/Codevetter/codevetter/tree/main/benchmarks/repo-unpacks/flutter.json

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)