How does the official Flutter architecture guide's Compass app organize lib/, and why does it mix feature-first and layer-first folders?

## Two ways to fold a Flutter codebase A Flutter app's `lib/` directory can be organized in two broad ways: - **Feature-first** (by feature): everything one feature needs lives together, e.g. an `auth/` folder with its screen, view model and use cases. - **Layer-first** (by type): every class of one architectural role lives together, e.g. `repositories/`, `services/`, `view_models/` folders spanning all features. The official Flutter app-architecture guide does not pick one. Its worked example, the **Compass app** in the case study, uses a deliberate **combination**, and the reason for the split is the part interviewers want to hear. ## The Compass layout ```text lib/ ui/ core/ ui/ # shared widgets, e.g. brand-styled buttons themes/ <feature_name>/ view_models/ <view_model_class>.dart widgets/ <feature_name>_screen.dart <other_widgets> domain/ models/ # app data types used by data and ui data/ repositories/ services/ model/ # API models config/ utils/ routing/ main.dart main_development.dart main_staging.dart test/ # unit and widget tests, mirrors lib/ testing/ # fakes and models other packages' tests reuse ``` ## Why the UI layer is feature-first In the guide's MVVM layering, a **view** (the widgets of one screen) and its **view model** (the object holding that screen's UI state and commands) are paired: each feature has exactly one view and one view model. Nothing else reuses them. Keeping them under `ui/<feature_name>/` means: - a change to one screen touches one folder; - deleting a feature means deleting one folder; - a new team member finds a screen by its product name, not by guessing which role folder it hides in. ## Why the data layer is layer-first **Repositories** (the source of truth for one kind of data, e.g. bookings) and **services** (thin wrappers around one external source, e.g. an HTTP API or local storage) are not owned by one feature. A booking repository can serve the booking screen, the home screen and the activities screen. If you put it inside one feature's folder, every other feature has to reach into that folder, which hides a shared dependency behind one feature's name. So the data layer is grouped by role instead. The **domain** folder holds the app's own data types, because both the data layer (which produces them) and the UI layer (which renders them) depend on them. ## The supporting folders 1. `ui/core/` collects widgets and theme logic shared by several views, such as buttons with brand styling, so the feature folders don't import each other. 2. `config/`, `utils/` and `routing/` hold app-wide wiring rather than feature code. 3. Three entry points (`main.dart`, `main_development.dart`, `main_staging.dart`) start the same app against different environments. 4. `test/` mirrors `lib/`, so the test for a class is easy to find. 5. `testing/` is a subpackage of **fakes** and test models. The guide describes it as a version of the app you don't ship; other packages' tests can import it. ## How to use this in an interview | Code | Owned by | Grouped | |---|---|---| | Screen widgets, view model | one feature | by feature, under `ui/` | | Repositories, services, API models | many features | by type, under `data/` | | Domain models | data and ui layers | `domain/models/` | | Shared widgets and themes | many views | `ui/core/` | The principle to state is **"group by ownership"**: code owned by one feature lives with that feature; code shared across features lives by role in a neutral place. The Compass layout is one application of it, not a mandate; the guide itself notes the same rules could be written with streams, Riverpod, flutter_bloc or signals instead of `ChangeNotifier` view models, and the folder shape would barely change. Two follow-on points strong candidates add. First, this is still one Dart package: folders are a convention, and nothing stops a view model in one feature from importing another feature's widgets. Second, when an app outgrows that, the same ownership lines become the boundaries of **local packages** (one per feature plus shared core packages), where the Dart package system and lints enforce what folders only suggest. ## Common mistakes - **Pure layer-first at scale**: a global `view_models/` folder with forty files, where every screen change means hunting through several role folders. - **Pure feature-first for shared data**: a `BookingRepository` stuck inside the `booking/` folder, which the home and activities screens then import from a sibling feature. - **A `core` or `common` folder that absorbs everything**: shared UI belongs there, feature logic does not, or the folder becomes the coupling point the layout was meant to avoid. - **Treating the Compass tree as mandatory**: `flutter create` with its default app template puts only `main.dart` in `lib/`; the layout is a recommendation, and a team that follows the ownership rule with different folder names is doing the same thing.