The anatomy of a Flutter project

and an honest warning about this chapter

What it is

Flutter is a way to write an application once and build it for Android, iOS, the web and the desktop. The language is Dart.

Before we start, one warning that applies to the whole chapter.

That is unpleasant, but more honest than pretending. It is also exactly the situation this whole book is about: confident text is not the same as checked text (article 1.6). Treat this chapter the way you would treat an AI's answer about a rare library — read it, but verify.

What it looks like in code

weather_app/
├── lib/                    ← your code, and only it
│   ├── main.dart           entry point
│   ├── screens/            screens
│   ├── widgets/            reusable pieces of interface
│   ├── models/             data descriptions
│   └── services/           network, database, API work
├── test/                   tests
├── android/                Android platform files
├── ios/                    iOS platform files
├── web/                    files for the web build
├── pubspec.yaml            dependencies and assets
├── pubspec.lock            exact versions — commit this
└── .dart_tool/             housekeeping, don't touch

The structure is familiar: lib/ is what you read, everything else is scaffolding. Exactly the same rule as src/ in a React project (article 10.1).

The android/ and ios/ folders are real native projects. You look into them rarely: when you need permissions, icons, app signing. That is chapter 12's subject.

pubspec.yaml

The counterpart of package.json, but also a list of assets:

name: weather_app
environment:
  sdk: ^3.5.0

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/icons/

Two differences from other ecosystems worth knowing about:

Assets are declared explicitly. Putting an image in a folder isn't enough — it has to be written into assets. Forget, and the application won't find the file at run time, and the error comes when the screen opens rather than at build time. An AI forgets this regularly.

Indentation is significant. YAML, like Python, is sensitive to spaces, and a wrong indent breaks the whole file.

The commands

flutter pub get          # install dependencies
flutter run              # run on a device or an emulator
flutter analyze          # static analysis — the counterpart of tsc and mypy
flutter test             # tests
flutter build apk        # a build (chapter 12)

flutter analyze is the most important of these for working with an AI. It is the same line of defence as mypy --strict in Python (article 6.3) and tsc --noEmit in TypeScript (9.3): a check before the run. In Dart types are mandatory, so the analyzer catches a lot.

What to tell the AI

Show this project's lib/ structure: what's in each folder,
one line each. Don't show android/, ios/ or .dart_tool.

I've added an image to assets/icons/. What needs to go into
pubspec.yaml for it to work? Show the exact indentation.

My Flutter version is 3.38, Dart 3.10. Write code only for
those, and tell me if anything you propose appeared in a
later version.

That last request is especially apt here: Flutter changes its API between major versions more often than most frameworks, and there is more training data for the old versions (article 3.1, reason 3).

What to look for

Code for old versions. The commonest sign is outdated widget and parameter names. If flutter analyze complains about unfamiliar arguments, the version is probably the reason.

An asset not declared in pubspec.yaml. The error appears when the screen opens, not at build time.

No pubspec.lock in the repository. The versions will drift apart (article 5.6).

Everything in main.dart. A thousand-line file instead of screens and widgets.

Edits in android/ and ios/ with no explanation. Those folders are partly generated; changes there are easily lost when the tooling is updated.

Cheat sheet