Create a feature module

Governed by ADR-0001 (layers), ADR-0005 (flat tree), ADR-0006 (feature-owned stores).

Concepts behind this playbook: architecture, project-structure.

Decide the location first

Features are peers under a domain grouping. A feature must never contain a features/ subdirectory.

❌ lib/features/meetings/meeting_details/features/ai_chat/
✅ lib/features/meetings/ai_chat/
✅ lib/features/meetings/meeting_details/

A pure view-layer sub-page with no store of its own may stay under the parent's view/, even with its own page state (e.g. meeting_details/view/share_meeting/; in this repo, challenges/view/challenge_joined/). The moment it gains its own store, promote it to a sibling (ADR-0005).

Never create anything under lib/shared/ — it is deprecated.

Directory shape

Create only the directories the feature actually needs. A feature with no modals does not get a modals/ folder.

lib/features/{feature}/
  view/
    {feature}_page.dart          @RoutePage widget — Provider root
    {feature}_page_state.dart    @injectable, MobX, no API access
    {feature}_keys.dart          widget keys used by Maestro flows
    widgets/                     private widgets for this page
    use_cases/                   UCs consumed only by view/state
  mobx/
    {feature}_store.dart         @injectable or @singleton, owns DioService
    use_cases/                   UCs consumed only by the store
  core/use_cases/                UCs consumed by 2+ layers of THIS feature
  models/                        feature-local models (not DTOs): {name}_model.dart, enums
  constants/                     feature-local constants: {feature}_constants.dart
  modals/{modal}/                view/ + mobx/ + use_cases/ per modal
  overlays/{overlay}/            overlay entries, tooltips, coach marks; same inner shape as modals/
  components/                    widgets reused across this feature's pages

Every folder below view/ and mobx/ is optional. There is no per-feature shared/: the name collides with the deprecated lib/shared/ and invites the same dumping ground. Code reused inside the feature goes in components/, models/, constants/ or core/use_cases/; code reused across features goes in lib/core/.

Mirror it in tests and flows:

test/features/{feature}/...      each test at its source file's path: a store test in mobx/,
                                 a page state's unit test next to the page's widget test in view/
.maestro/flows/{feature}/        {feature}_happy.yaml | _failure.yaml | _edge.yaml

What belongs in lib/core/ instead

lib/core/ holds what more than one feature uses: configs/, constants/, extensions/, guards/, navigation/, services/ (with interceptors/), state/, ui/, use_cases/, utils/. These are added when the app first needs them:

• exceptions/ — typed domain exceptions shared across features ({name}_exception.dart), thrown by use cases and interceptors and caught by type (ADR-0020 pattern 3). An exception only one feature throws and catches can stay in that feature's models/.
• platform_channels/ — one Dart wrapper per native capability ({capability}_channel.dart). See add-platform-channel.
• hooks/ — custom hooks used by widgets in more than one feature (use_{name}.dart). See ADR-0019.

Naming

The page, state, store, use case, DTO and keys suffixes are in AGENTS.md. Directories and file names are snake_case, always: todo_details/, never todoDetails/ or TodoDetails/.

Build order

Bottom-up, so each layer compiles against something real:

1. DTOs + API provider — only if the endpoint is new. create-dto, create-api-provider.
2. Store — create-store. Owns DioService, exposes @readonly observables.
3. Use cases — create-use-case. Place next to the consumer layer.
4. Page state — @injectable, injects the store, AppNavigator, use cases. No DioService.
5. Page + widgets — create-page. Provider at the root, context.read<T>() below.
6. Localization — add-localization. Every visible string.
7. Route — register the @RoutePage in lib/core/navigation/, then melos run build.
8. Codegen — melos run build regenerates *.g.dart and injectable.config.dart.
9. Tests + flows — write-tests, write-maestro-flow.

Route registration

The page carries @RoutePage(). After adding it, run melos run build so *.gr.dart picks it up, then add the route to the router config in lib/core/navigation/. Guards go in lib/core/guards/.

Never navigate from the page. The state class injects AppNavigator and the page calls a state method (ADR-0008).

Definition of done

• Feature is a peer, not nested; nothing added to lib/shared/, no per-feature shared/
• Only the folders the feature needs; files and folders snake_case with the documented suffixes
• Store lives under {feature}/mobx/ even if @singleton
• State has no DioService; page has no store and no context.router
• Every string via LocaleKeys; every colour/style via design-system tokens
• Interactive widgets carry keys from {feature}_keys.dart + Semantics labels
• melos run build run after annotation changes; no generated file edited by hand
• Unit + widget tests exist; Maestro happy / failure / edge flows exist
• melos run verify passes