Flow package anatomy

A @features/flow-<name> package holds one user-facing flow that both apps compose. Where the package sits among the layers is structure-flow; how its barrels work is package-public-api. This skill covers what goes inside src/. Every rule names a package on develop to copy from; the full trees are in references/examples.md.

MVVM is the convention

Every flow package is MVVM, with no exception: each screen, and each component with its own state, is a useXViewModel.ts plus XView.web.tsx / XView.native.tsx. The View renders its props only: no store, navigation or query hook. The ViewModel and View rules are the mvvm-architecture ones; this skill does not restate them.

What is specific to a flow package:

• The View is split per platform, XView.web.tsx and XView.native.tsx, on one props type. Suffix the ViewModel too (useXViewModel.web.ts) only when the two platforms really differ.
• A component exported from a universal entry keeps one props contract on both platforms: see the universal components ADR.

Example: useCardViewModel.ts, CardView.web.tsx and CardView.native.tsx in @features/flow-pay-card; useCardAssetsViewModel.ts and CardAssetsView.*.tsx in @features/flow-pay-card-assets. view.web.tsx in @features/flow-fear-and-greed predates the naming rule: rename it when you touch it.

One screen: flat src/

A flow with one screen keeps its files at the root of src/, with no screens/ folder.

src/
├── Card.tsx              # entry: wires the ViewModel to the View
├── Card.types.ts         # props of the entry and of the view
├── useCardViewModel.ts   # state, data and callbacks, no JSX
├── CardView.web.tsx      # web rendering
├── CardView.native.tsx   # native rendering
├── index.ts
└── index.native.ts

Example: @features/flow-pay-card. The entry is one line, <CardView {...useCardViewModel(props)} />, and ./CardView resolves to the .web or .native file per platform.

Several screens: screens/<Screen>/

A flow with several screens gives each one a folder under screens/, named after the screen in PascalCase. A screen folder holds its entry, its ViewModel, its two Views and types.ts at its root, plus a components/ folder for what only that screen uses.

src/screens/
├── Entry/
├── Review/
│   ├── Review.tsx              # <ReviewView {...useReviewViewModel(props)} />
│   ├── useReviewViewModel.ts
│   ├── ReviewView.web.tsx
│   ├── ReviewView.native.tsx
│   ├── types.ts
│   └── components/             # used by this screen only
└── Flow/                       # switches between the screens above

No package on develop follows this on both platforms yet. The closest is @features/flow-contacts-add-address: copy its screens/ and screens/Flow/ layout, and its web Review screen (ContactsAddAddressReview.web.tsx, useContactsAddAddressReviewViewModel.web.ts, ContactsAddAddressReviewView.web.tsx). Known deviations, do not copy:

• screens/Review/ and screens/AddressName/ have no native MVVM split: the native screen is one file (ContactsAddAddressReview.native.tsx, ContactsAddAddressName.native.tsx) that calls its hooks and renders.
• screens/AddressEntry/ keeps its ViewModel in a viewModel/ subfolder and its entry and View in components/, instead of at the root of the screen folder.

@features/flow-contacts-introduction has no ViewModel at all; do not use it as an example.

Do not add steps/. Some older packages still have one (@features/flow-app-unlock, @features/flow-app-password-setup): rename it to screens/ when you touch the package.

Flow state versus entity state

• A flow slice holds what the flow alone decides, never a copy of entity data. Read entities through their selectors.
• Selectors live beside the slice and type their root as { <sliceName>: State }, as in @features/flow-pay-balance state/selectors.ts.
• The app registers the reducer: apps/ledger-live-desktop/src/renderer/reducers/index.ts imports payCardBalanceSlice from @features/flow-pay-balance/state.

Local routing

The flow owns moving between its own screens; the app owns navigation to and from the flow.

• Keep the current screen in flow state and switch on it in one component, as screens/Flow/ContactsAddAddressFlowContent.native.tsx does on the step from state/addAddressFlowReducer.ts in @features/flow-contacts-add-address.
• Take app navigation as callbacks or ports (onClose, onSuccess), never as a router import. External links the flow opens go in urls.ts, one value per platform (@features/flow-contacts-add-address).

Where the other files go

• logic/ and model/ import no React, so their tests run without rendering.
• The lifecycle model is not a ViewModel. The ViewModel is the useXViewModel hook every screen has; the lifecycle model is optional and framework-free. Add one when a screen runs an async action through an injected port and moves through states (idle, open, success, error): the controller calls the port and returns the next state, and the screen's useXViewModel hook holds that state in React and hands it to the View. A screen without such an action needs only its hook. In @features/flow-contacts-delete-address, useDeleteAddressFlowViewModel.ts wraps model/addressDeleteController.ts; model/addressDeleteViewModel.ts predates the term and holds the lifecycle constructors.
• Add a folder only when it groups several files; a single helper stays at the root of src/ or of its screen.
• exports.ts and the index.* files are pure barrels: see package-public-api.
• Wording keys follow i18n-keys.

Review

• One screen: flat src/. Several: screens/<Screen>/. No steps/.
• MVVM everywhere: each screen is a useXViewModel.ts plus XView.web.tsx / XView.native.tsx, and the View renders props only, per mvvm-architecture.
• Flow state holds only what the flow decides; entity data stays in domain/entity.
• Screen changes live in flow state; app navigation comes in as callbacks.
• copy/, logic/, model/, types.ts and exports.ts hold what the table says, no more.