# flutter/samples architecture

> Architecture diagram of the GitHub repository flutter/samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flutter/samples
- Repository: https://github.com/flutter/samples

## Overview

1. This repository is a monorepo of independent Flutter samples, not a single product app. Each sample is usually self-contained and can be run from its own directory, with the repository root acting as the catalog, docs, and CI entry point.

2. The top level is organized by sample category: quickstarts and demo apps (`animations`, `form_app`, `navigation_and_routing`, `testing_app`, etc.), native platform samples (`add_to_app`, `platform_channels`, `platform_view_swift`, `ios_app_clip`), and web embedding samples (`web_embedding`). The root README is the main index that explains which pattern each subproject demonstrates.

3. Most Flutter samples follow the standard cross-platform Flutter layout: `lib/` for app logic, `test/` for widget/unit tests, and platform folders like `android/`, `ios/`, `linux/`, `macos/`, `windows/`, and `web/` where needed. These platform folders are mostly bootstrap shells; the real sample logic typically lives in Dart under `lib/`.

4. A recurring boundary in the repo is “Flutter UI vs native host.” This is most explicit in `add_to_app`, where Android and iOS host apps embed a Flutter module either as a full-screen view, a prebuilt module, a plugin-using module, or a multi-engine setup. The architecture here is about integration seams between host lifecycle/code and Flutter engine/module code.

5. Another major boundary is platform communication. `platform_channels` demonstrates the Flutter-side consumption of MethodChannel, EventChannel, BasicMessageChannel, and custom codecs, with native handlers on Android and iOS providing sensor/data streams and commands. `pedometer` goes further with direct native interop via FFI/JNI-style generated bindings, showing a lower-level Dart-to-native path than platform channels.

6. Several samples are structured around explicit layers or clean boundaries. `compass_app` is the clearest example: it splits into `data/` (repositories, services, API clients, local storage), `domain/` (models and use cases), `ui/` (screens, view models, widgets), `routing/`, `config/`, `utils/`, and `testing/`. It also includes a companion `server/` package, so the architecture diagram should show a Flutter client talking to a separate Dart backend.

7. Generated code is an important repo-wide mechanism. Many samples use codegen for immutable models and JSON serialization (`*.freezed.dart`, `*.g.dart`), and some examples include Pigeon-generated or FFI-generated bindings. This means part of the “source of truth” is in handwritten schema/model files plus generated outputs that bridge typed data across layers or platforms.

8. Several samples are UI galleries rather than business apps. `animations`, `cupertino_gallery`, and `material_3_demo` are primarily presentation and interaction showcases, with their main flow being navigation from a home/catalog screen into feature demos. Their architecture is dominated by reusable widget pages, themed screens, and test coverage around each showcased interaction or component.

9. Navigation-focused samples isolate route structure as a first-class concern. `navigation_and_routing` has app/scaffold/auth/data/screens/widgets layers and demonstrates screen transitions and nested routes. The important boundary is between shared app shell state and route-specific screens like authors, books, details, settings, and sign-in.

10. Testing is a core theme in `testing_app`, which is split into app screens, model/state logic, and layered tests including integration tests. Its architecture is meant to show how UI state, model state, and automated tests fit together, rather than introducing external services.

11. Web embedding is another distinct subsystem. In `web_embedding/element_embedding_demo`, Flutter is embedded into a custom DOM host element, while `web_embedding/ng-flutter` combines an Angular host app with a Flutter sub-app. The boundary here is not native mobile code but browser DOM/JS integration versus Flutter-rendered content.

12. A small number of samples center on specialized platform features: `simple_shader` and `simple_sdf` focus on fragment shaders; `google_maps` focuses on plugin-backed map rendering and local asset data; `android_splash_screen` and `dynamic_theme` demonstrate platform-specific UX/system integration. In these, the architecture is mostly “Flutter app plus one specialized platform capability.”

13. Tooling and automation are repo-wide support systems rather than sample features. GitHub Actions workflows build Android/iOS and run maintenance/review automation, and the `tool/` directory contains scripts for CI, cleanup, and release tasks. These do not affect sample runtime architecture, but they define how the samples are validated and published.

14. Overall, the repository’s architectural pattern is: many small, runnable examples sharing the Flutter/Dart ecosystem, each emphasizing a different boundary—UI composition, routing, testing, native embedding, platform channels, FFI, or web integration. An architecture diagram should therefore show a cataloged set of independent sample apps, not one shared application core.

Main entry points: [`README.md`](https://github.com/flutter/samples/blob/main/README.md) (Root README), [`animations`](https://github.com/flutter/samples/tree/main/animations) (Animations), [`tool`](https://github.com/flutter/samples/tree/main/tool) (CI tools), [`add_to_app/fullscreen`](https://github.com/flutter/samples/tree/main/add_to_app/fullscreen) (Fullscreen embed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog & tooling"]
  node_root_readme["Root README<br/>index/docs<br/>[README.md]"]
  node_ci_tools["CI tools<br/>build/automation"]
end

subgraph group_add_to_app["Add-to-app samples"]
  node_add_to_app_fullscreen["Fullscreen embed<br/>host/embed sample"]
  node_add_to_app_books["Books embed<br/>host/embed sample"]
  node_add_to_app_plugin["Plugin embed<br/>host/embed sample"]
  node_add_to_app_multiple["Multiple flutters<br/>multi-engine sample"]
  node_add_to_app_android_view["Android view embed<br/>host/embed sample"]
end

subgraph group_interop["Platform interop"]
  node_platform_channels_app["Platform channels<br/>interop sample"]
  node_pedometer_pkg["Pedometer<br/>ffi plugin"]
  node_google_maps_app["Google Maps<br/>plugin sample"]
  node_simple_shader_app["Simple shader<br/>shader sample"]
  node_simple_sdf_app["Simple SDF<br/>shader sample"]
  node_ios_app_clip_sample["App Clip<br/>ios platform sample"]
end

subgraph group_ui_samples["UI samples"]
  node_animations_app["Animations<br/>gallery sample"]
  node_cupertino_gallery_app["Cupertino gallery<br/>gallery sample"]
  node_material_3_demo_app["Material 3 demo<br/>gallery sample"]
  node_navigation_app["Navigation sample<br/>routing sample"]
  node_testing_app["Testing app<br/>testing sample"]
  node_form_app["Form app<br/>form sample"]
  node_compass_client["Compass app<br/>layered client"]
  node_compass_server["Compass server<br/>dart backend"]
  node_dynamic_theme_app["Dynamic theme<br/>platform UX sample"]
end

subgraph group_web["Web embedding"]
  node_web_element_demo["Element embed<br/>web embed sample"]
  node_ng_flutter["NG Flutter<br/>web host/embed"]
end

node_root_readme -->|"indexes"| node_animations_app
node_root_readme -->|"indexes"| node_form_app
node_root_readme -->|"indexes"| node_navigation_app
node_root_readme -->|"indexes"| node_platform_channels_app
node_root_readme -->|"indexes"| node_add_to_app_fullscreen
node_root_readme -->|"indexes"| node_web_element_demo
node_root_readme -->|"indexes"| node_compass_client
node_ci_tools -->|"validates"| node_animations_app
node_ci_tools -->|"validates"| node_compass_client
node_ci_tools -->|"validates"| node_platform_channels_app
node_add_to_app_fullscreen -->|"module+host"| node_add_to_app_fullscreen
node_add_to_app_books -->|"module+host"| node_add_to_app_books
node_add_to_app_plugin -->|"module+host"| node_add_to_app_plugin
node_add_to_app_multiple -->|"engines"| node_add_to_app_multiple
node_add_to_app_android_view -->|"embed"| node_add_to_app_android_view
node_platform_channels_app -.->|"alternative path"| node_pedometer_pkg
node_compass_client -->|"calls"| node_compass_server
node_navigation_app -->|"routes"| node_navigation_app
node_testing_app -->|"layers"| node_testing_app
node_form_app -->|"validation"| node_form_app
node_animations_app -->|"demos"| node_animations_app
node_cupertino_gallery_app -->|"pages"| node_cupertino_gallery_app
node_material_3_demo_app -->|"screens"| node_material_3_demo_app
node_web_element_demo -.->|"web boundary"| node_ng_flutter

click node_root_readme "https://github.com/flutter/samples/blob/main/README.md"
click node_ci_tools "https://github.com/flutter/samples/tree/main/tool"
click node_animations_app "https://github.com/flutter/samples/tree/main/animations"
click node_cupertino_gallery_app "https://github.com/flutter/samples/tree/main/cupertino_gallery"
click node_material_3_demo_app "https://github.com/flutter/samples/tree/main/material_3_demo"
click node_navigation_app "https://github.com/flutter/samples/tree/main/navigation_and_routing"
click node_testing_app "https://github.com/flutter/samples/tree/main/testing_app"
click node_form_app "https://github.com/flutter/samples/tree/main/form_app"
click node_compass_client "https://github.com/flutter/samples/tree/main/compass_app/app"
click node_compass_server "https://github.com/flutter/samples/tree/main/compass_app/server"
click node_platform_channels_app "https://github.com/flutter/samples/tree/main/platform_channels"
click node_pedometer_pkg "https://github.com/flutter/samples/tree/main/pedometer"
click node_google_maps_app "https://github.com/flutter/samples/tree/main/google_maps"
click node_simple_shader_app "https://github.com/flutter/samples/tree/main/simple_shader"
click node_simple_sdf_app "https://github.com/flutter/samples/tree/main/simple_sdf"
click node_add_to_app_fullscreen "https://github.com/flutter/samples/tree/main/add_to_app/fullscreen"
click node_add_to_app_books "https://github.com/flutter/samples/tree/main/add_to_app/books"
click node_add_to_app_plugin "https://github.com/flutter/samples/tree/main/add_to_app/plugin"
click node_add_to_app_multiple "https://github.com/flutter/samples/tree/main/add_to_app/multiple_flutters"
click node_add_to_app_android_view "https://github.com/flutter/samples/tree/main/add_to_app/android_view"
click node_web_element_demo "https://github.com/flutter/samples/tree/main/web_embedding/element_embedding_demo"
click node_ng_flutter "https://github.com/flutter/samples/tree/main/web_embedding/ng-flutter"
click node_ios_app_clip_sample "https://github.com/flutter/samples/tree/main/ios_app_clip"
click node_dynamic_theme_app "https://github.com/flutter/samples/tree/main/dynamic_theme"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_readme,node_ci_tools toneBlue
class node_add_to_app_fullscreen,node_add_to_app_books,node_add_to_app_plugin,node_add_to_app_multiple,node_add_to_app_android_view toneAmber
class node_platform_channels_app,node_pedometer_pkg,node_google_maps_app,node_simple_shader_app,node_simple_sdf_app,node_ios_app_clip_sample toneMint
class node_animations_app,node_cupertino_gallery_app,node_material_3_demo_app,node_navigation_app,node_testing_app,node_form_app,node_compass_client,node_compass_server,node_dynamic_theme_app toneRose
class node_web_element_demo,node_ng_flutter toneIndigo
```

## Components

### Catalog & tooling

Repository root, docs, CI, and shared scripts

- [Root README](https://github.com/flutter/samples/blob/main/README.md): index/docs · Repository entry point and sample catalog · `README.md`
- [CI tools](https://github.com/flutter/samples/tree/main/tool): build/automation · GitHub Actions and repo scripts for validation and release · `tool`

### Add-to-app samples

Flutter embedded into Android and iOS host apps

- [Fullscreen embed](https://github.com/flutter/samples/tree/main/add_to_app/fullscreen): host/embed sample · Android and iOS host apps embedding a Flutter module full-screen · `add_to_app/fullscreen`
- [Books embed](https://github.com/flutter/samples/tree/main/add_to_app/books): host/embed sample · Host apps and module using generated interface bindings · `add_to_app/books`
- [Plugin embed](https://github.com/flutter/samples/tree/main/add_to_app/plugin): host/embed sample · Flutter module integrated with native plugin usage · `add_to_app/plugin`
- [Multiple flutters](https://github.com/flutter/samples/tree/main/add_to_app/multiple_flutters): multi-engine sample · Single and dual Flutter engine host setups · `add_to_app/multiple_flutters`
- [Android view embed](https://github.com/flutter/samples/tree/main/add_to_app/android_view): host/embed sample · Android host embedding Flutter views and content sizing examples · `add_to_app/android_view`

### Platform interop

Channels, FFI/JNI, and native integration seams

- [Platform channels](https://github.com/flutter/samples/tree/main/platform_channels): interop sample · MethodChannel, EventChannel, and BasicMessageChannel demos · `platform_channels`
- [Pedometer](https://github.com/flutter/samples/tree/main/pedometer): ffi plugin · Direct Dart-to-native bindings for health/step data · `pedometer`
- [Google Maps](https://github.com/flutter/samples/tree/main/google_maps): plugin sample · Map rendering with bundled location data · `google_maps`
- [Simple shader](https://github.com/flutter/samples/tree/main/simple_shader): shader sample · Fragment shader rendering in Flutter · `simple_shader`
- [Simple SDF](https://github.com/flutter/samples/tree/main/simple_sdf): shader sample · Signed-distance-field shader demo · `simple_sdf`
- [App Clip](https://github.com/flutter/samples/tree/main/ios_app_clip): ios platform sample · iOS app clip and Flutter app integration · `ios_app_clip`

### UI samples

Gallery-style and app-structure Flutter samples

- [Animations](https://github.com/flutter/samples/tree/main/animations): gallery sample · Reusable animation demos and interactions · `animations`
- [Cupertino gallery](https://github.com/flutter/samples/tree/main/cupertino_gallery): gallery sample · iOS-styled widget showcase and navigation hub · `cupertino_gallery`
- [Material 3 demo](https://github.com/flutter/samples/tree/main/material_3_demo): gallery sample · Material component and transition showcase · `material_3_demo`
- [Navigation sample](https://github.com/flutter/samples/tree/main/navigation_and_routing): routing sample · Route structure, auth flow, and nested screens · `navigation_and_routing`
- [Testing app](https://github.com/flutter/samples/tree/main/testing_app): testing sample · App state and layered automated testing example · `testing_app`
- [Form app](https://github.com/flutter/samples/tree/main/form_app): form sample · Validation, autofill, and sign-in form patterns · `form_app`
- [Compass app](https://github.com/flutter/samples/tree/main/compass_app/app): layered client · Flutter client with data, domain, UI, and routing layers · `compass_app/app`
- [Compass server](https://github.com/flutter/samples/tree/main/compass_app/server): dart backend · Separate Dart server for shared models and API routes · `compass_app/server`
- [Dynamic theme](https://github.com/flutter/samples/tree/main/dynamic_theme): platform UX sample · System-driven theming and platform-specific UI behavior · `dynamic_theme`

### Web embedding

Flutter embedded into browser-hosted apps

- [Element embed](https://github.com/flutter/samples/tree/main/web_embedding/element_embedding_demo): web embed sample · Flutter embedded into a custom DOM element host · `web_embedding/element_embedding_demo`
- [NG Flutter](https://github.com/flutter/samples/tree/main/web_embedding/ng-flutter): web host/embed · Angular host app with an embedded Flutter sub-app · `web_embedding/ng-flutter`

## Connections

- Root README → Animations: indexes · Root catalog points to sample apps
- Root README → Form app: indexes · Root catalog points to sample apps
- Root README → Navigation sample: indexes · Root catalog points to sample apps
- Root README → Platform channels: indexes · Root catalog points to sample apps
- Root README → Fullscreen embed: indexes · Root catalog points to sample families
- Root README → Element embed: indexes · Root catalog points to sample families
- Root README → Compass app: indexes · Root catalog points to sample families
- CI tools → Animations: validates · CI and scripts exercise sample builds and checks
- CI tools → Compass app: validates · CI and scripts exercise sample builds and checks
- CI tools → Platform channels: validates · CI and scripts exercise sample builds and checks
- Fullscreen embed → Fullscreen embed: module+host · Represents the host/embed boundary across Android and iOS
- Books embed → Books embed: module+host · Represents generated binding and host integration seams
- Plugin embed → Plugin embed: module+host · Represents plugin-enabled host integration
- Multiple flutters → Multiple flutters: engines · Single-engine and dual-engine host patterns
- Android view embed → Android view embed: embed · Android view-based Flutter embedding patterns
- Platform channels → Pedometer: alternative path · Both demonstrate Dart-to-native boundaries, one via channels and one via bindings
- Compass app → Compass server: calls · Flutter client consumes data from separate Dart backend
- Navigation sample → Navigation sample: routes · Shared shell state and route-specific screens
- Testing app → Testing app: layers · App, model logic, and automated tests are organized together
- Form app → Form app: validation · Form widgets and sign-in flow are central
- Animations → Animations: demos · Home/catalog screen leads into reusable animation examples
- Cupertino gallery → Cupertino gallery: pages · Home/catalog screen leads into component demos
- Material 3 demo → Material 3 demo: screens · Home/catalog screen leads into themed component demos
- Element embed → NG Flutter: web boundary · Two browser-host integration styles within web embedding