System Overview

Flutter gives you one Dart framework and separate platform embedders. The shared part is real, but it stops at the boundary where the app needs device APIs, platform views, packaging, signing, or store policy.

flowchart TB
    dartApp["Dart app code"] --> framework["Flutter framework"]
    framework --> widgets["Widgets, rendering, Material, Cupertino"]
    widgets --> dartUi["dart:ui"]
    dartUi --> engine["Flutter engine"]
    engine --> embedder["Platform embedder"]
    embedder --> targets["Android, iOS, desktop, web"]
    dartApp --> packages["Packages and plugins"]
    packages --> nativeBridge["Platform channels, Pigeon, FFI, JS interop"]
    nativeBridge --> targets

Layer Map

Layer	What it does	What can go wrong
Dart app	Screens, state, routing, repositories, services	Too much logic inside widgets
Framework	Widgets, rendering, gestures, animation, Material, Cupertino	Rebuilds and layout costs hide until profile mode
`dart:ui`	Low-level painting, text, semantics, input hooks	Usually not where app code should start
Engine	Rasterization, text, platform messaging, runtime integration	Renderer and target-specific behavior differ
Embedder	Android/iOS/desktop/web host integration	Permissions, manifests, signing, and native views are target-specific
Plugins/platform code	Device APIs and native libraries	Platform support may be incomplete or stale

Mental Model

Flutter rebuilds UI descriptions, not pixels directly. Your widgets describe the desired UI for the current state. The framework updates elements and render objects under the hood.

For app architecture, keep this split:

Concern	Belongs in
Layout and simple visual branching	Widgets/views
User-intent handling and UI state	View models/controllers
Persistent app data	Repositories
Network, platform, database, file, or plugin APIs	Services
Target-specific code	Plugin implementation or platform folders

Practical Boundary

The cleanest Flutter code still needs platform verification. A camera feature needs plugin support and permissions on Android/iOS. A desktop release needs package metadata and signing. A web app needs renderer and hosting checks. Treat those as first-class architecture, not post-build cleanup.