Day 10: Screen Architecture and the Feature Folder Pattern
Lesson 10 — Screen Architecture and the Feature Folder Pattern
NomadAir Masterclass · Module 2 · Beginner
The Naive Flutter Approach — And Why It Breaks
The default Flutter project structure places everything in lib/:
This is the "flat folder" approach. At 10 files it feels fine. At 30 files the directory listing is a scroll. At 60 files — the size NomadAir will reach by Lesson 60 — finding any file requires reading every name in the list. Refactoring a feature requires identifying which files belong to it by memory rather than by location. Code review becomes harder because a PR touching five unrelated features looks identical to a PR touching one feature in five files.
The more subtle problem is coupling. When booking_screen.dart imports flight_model.dart and search_provider.dart and passenger_form.dart and payment_screen.dart, those imports encode a dependency graph that is invisible from the file names alone. There is no structural enforcement of the rule "booking concerns stay in booking." The rule exists only in someone's head.
Three Concepts That Must Not Be Conflated
The Lesson 10 architecture depends on understanding three distinct concepts that most Flutter tutorials treat as interchangeable:
A page is the target of a navigation route. It is the unit that the Navigator knows about. A page's job is: receive route parameters, create the screen widget, optionally wrap it in a transition. A page has no layout of its own. In GoRouter (Lesson 11), every GoRoute.builder creates a page.
A screen is the root layout widget for a full-screen experience. It receives data (from its constructor, a provider, or a bloc), manages local UI state, and composes sub-widgets into a complete user-facing layout with a Scaffold. The distinction from a widget: a screen is never reused inside another screen. It owns the scaffold. If you find yourself passing a screen to another screen's child slot, you have made a widget, not a screen.
A widget is a reusable composition unit. It receives all its data through its constructor. It has no knowledge of routes, navigation, or providers. The NomadButton, DestinationCard, and NomadFlightCard from Part 1 are widgets. FlightCard in the search results list is a widget. A widget must be usable in any context — a screen, a dialog, a test harness — without modification.
The naming convention enforces this: files ending in _page.dart are route targets, files ending in _screen.dart are full-layout root widgets, and files ending in _widget.dart or carrying a component name are reusable composition units.
The Feature Folder Pattern
Every NomadAir feature lives in its own folder under lib/features/. The four root features are:
Keep going with the full lesson
The rest of this lesson — plus its implementation guide, runnable scripts and source code — is included with the course or an All Access plan. Create a free account to start the free lessons in every course.
Already a member? Sign in