Flutter is a cross-platform UI framework that enables building natively compiled applications for mobile, web, and desktop from a single codebase. The Flutter repository (https://github.com/flutter/flutter) is a monorepo containing three major subsystems:
This page provides an entry point for understanding how these subsystems are organized and interact within the repository.
Purpose: Introduce the Flutter repository's three-layer architecture (Engine, Framework, Tools), monorepo organization, and how the major systems interact.
Scope:
Not covered: Detailed subsystem documentation (see Repository Structure and Build System, Framework Architecture, Engine Architecture, Developer Tools, CI/CD and Automation).
Flutter's architecture consists of three distinct layers that work together to enable cross-platform application development:
| Layer | Language | Location | Primary Responsibilities |
|---|---|---|---|
| Engine | C++, Objective-C, Java | engine/src/flutter/ | Skia/Impeller rendering, Dart VM, platform channels, compositor, platform integrations (Android, iOS, Web, Fuchsia) |
| Framework | Dart | packages/flutter/ | Widget tree, render objects, Material/Cupertino components, semantics |
| Tools | Dart | packages/flutter_tools/ | flutter CLI, hot reload, build orchestration, device management, package management |
Sources:
Sources:
The repository is structured as a monorepo with distinct directories for each major subsystem:
| Directory | Contents | Key Files/Classes |
|---|---|---|
bin/ | Flutter SDK command-line entry point | bin/flutter, bin/cache/artifacts/ |
packages/flutter/ | Core framework library | StatefulWidget, RenderObject, BuildContext |
packages/flutter_tools/ | Developer tooling | FlutterCommand, ResidentRunner, DevFS |
packages/flutter_test/ | Testing framework | WidgetTester, TestFlutterDevice |
engine/src/flutter/ | C++ engine source | Shell, Rasterizer, PlatformView |
dev/ | Development tools and CI scripts | dev/bots/, dev/integration_tests/ |
examples/ | API examples and demos | examples/api/, demo apps |
Sources:
Sources:
This table maps high-level concepts to specific code entities in the repository:
| System/Concept | Code Entity | File Path | Key Methods/Properties |
|---|---|---|---|
| Framework Layer | |||
| Widget System | StatefulWidget, StatelessWidget | packages/flutter/lib/src/widgets/framework.dart | build(), createState() |
| Widget Identity | Key, ValueKey, GlobalKey | packages/flutter/lib/src/foundation/key.dart | - |
| Rendering | RenderObject, RenderBox | packages/flutter/lib/src/rendering/object.dart | paint(), layout() |
| Text Editing | EditableText, TextEditingController | packages/flutter/lib/src/widgets/editable_text.dart | updateEditingValue() |
| Material Components | Scaffold, TextField, InputDecorator | packages/flutter/lib/src/material/ | - |
| Semantics | SemanticsNode, Semantics | packages/flutter/lib/src/semantics/ | updateWith() |
| Engine Layer | |||
| Engine Shell | Shell, Rasterizer | engine/src/flutter/shell/common/ | OnPlatformMessage(), Draw() |
| Impeller Renderer | Renderer, ContentContext | engine/src/flutter/impeller/ | Render(), GetContext() |
| Skia Graphics | SkCanvas, SkPaint | engine/src/flutter/third_party/skia/ | drawRect(), drawPath() |
| Platform Channels | PlatformView, PlatformMessageHandler | engine/src/flutter/shell/platform/ | HandlePlatformMessage() |
| Fuchsia Components | DartComponentController, ComponentV2 | engine/src/flutter/shell/platform/fuchsia/ | OnPlatformMessage(), Run() |
| Tools Layer | |||
| CLI Command System | FlutterCommand, RunCommand, TestCommand | packages/flutter_tools/lib/src/commands/ | runCommand() |
| Package Management | UpdatePackagesCommand | packages/flutter_tools/lib/src/commands/update_packages.dart | runCommand() |
| Hot Reload | HotRunner, ResidentRunner | packages/flutter_tools/lib/src/run_hot.dart | restart(), reassemble() |
| File Synchronization | DevFS, WebDevFS | packages/flutter_tools/lib/src/devfs.dart | update() |
| Build Orchestration | BuildSystem, Target | packages/flutter_tools/lib/src/build_system/ | build() |
| Build & CI | |||
| Engine Dependencies | DEPS | DEPS | Pins Skia, Dart SDK, toolchains |
| Framework CI | .ci.yaml | .ci.yaml | Defines test targets and builders |
| Engine CI | engine/.ci.yaml | engine/src/flutter/.ci.yaml | Defines engine build matrix |
| Engine Version | engine.version | bin/internal/engine.version | Engine build identifier |
| Performance Testing | PerfTest, StartupTest | dev/devicelab/lib/tasks/perf_tests.dart | run(), performance benchmarking |
| Hot Reload Testing | Hot mode tests | dev/devicelab/lib/tasks/hot_mode_tests.dart | Tests hot reload functionality |
Sources:
Sources:
Sources:
Flutter uses multiple dependency management systems for its different layers:
The DEPS1-213 file manages C++ engine dependencies using the gclient tool:
skia_revision at DEPS18dart_revision at DEPS62The root pubspec.yaml1-220 defines a Dart workspace for framework packages:
pub dependency resolution via flutter update-packagespackages/ defined by workspace directivepubspec.lock pins transitive dependencies across the workspaceSources:
| Phase | Tool | Input | Output |
|---|---|---|---|
| Engine Build | GN + Ninja | C++ sources, DEPS | libflutter.so, FlutterEngine.framework |
| Framework Compilation | dart compile | Dart sources, package_config.json | .dill kernel files |
| Application Build | flutter build | App code, assets | Platform-specific bundles (APK, IPA, etc.) |
| Hot Reload | ResidentCompiler | Changed Dart files | Incremental .dill.incremental |
Sources:
Flutter uses .ci.yaml and engine/src/flutter/.ci.yaml to define continuous integration tasks, orchestrated by Cocoon and executed on LUCI infrastructure.
| Mode | Tool | Test Location | Execution Environment |
|---|---|---|---|
| Unit/Widget Tests | flutter test via TestCommand | test/**/*_test.dart | flutter_tester (headless) |
| Integration Tests | flutter test integration_test/ via device | integration_test/**/*_test.dart | Real device or emulator |
| Web Tests | flutter test --platform=chrome | test/**/*_test.dart | Chrome via WebDriver |
| Engine Tests | C++ test harness | engine/src/flutter/testing/ | Platform-native test runner |
| Performance Tests | PerfTest, StartupTest | dev/devicelab/bin/tasks/ | Physical devices (defined in .ci.yaml) |
| Memory Tests | Memory benchmarks | dev/benchmarks/*/test_memory/ | Physical devices tracking memory usage |
Sources:
Sources:
The Flutter repository is a monorepo that integrates the Dart-based framework, the C++ engine, developer tooling, and a comprehensive build and CI/CD system. Its architecture is layered, with clear separation of concerns between the application, framework, engine, and platform integration layers. The build and CI systems ensure reproducibility and cross-platform support, while the developer tooling provides a unified interface for building, running, and testing Flutter applications.
For more detailed information on specific subsystems, see the following pages:
Sources:
Refresh this wiki