mvvm-architecture
Skill627 starsChanged 10 days agoMITView on GitHub
The Container, ViewModel, View convention of app composition code under apps/*/src/mvvm/** and of every features/flow package. Read when creating, editing or reviewing files in apps/*/src/mvvm/**, or view model and view files in features/flow/** (use*ViewModel.ts, *View.web.tsx, *View.native.tsx). Decide where new code goes with structure-flow first.
In this repository70 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- analyticsSkill
- batch-feature-devSkill
- ci-runnersSkill
- ci-workflow-refsSkill
- cleanupSkill
- client-idsSkill
- cloud-sync-moduleSkill
- codeownershipSkill
- coin-families-contractSkill
- coin-modulesSkill
- commentsSkill
- configurationSkill
- console-logSkill
- create-changesetSkill
- create-prSkill
- data-layer-advancedSkill
- debug-rn-native-crashSkill
- dependency-patchesSkill
- detect-data-leaksSkill
- device-intent-executorSkill
- devtools-import-boundarySkill
- dialogs-sliceSkill
- docs-migrateSkill
- docs-update-or-createSkill
- domain-dataSkill
- e2e-desktop-add-or-updateSkill
- e2e-desktop-onboardSkill
- e2e-earnSkill
- e2e-mobile-add-or-updateSkill
- e2e-mobile-onboardSkill
- e2e-swapSkill
- errorsSkill
- feature-devSkill
- fix-ciSkill
- flow-packageSkill
- get-pr-commentsSkill
- git-conventionsSkill
- i18n-keysSkill
- impacting-prsSkill
- knip-migrationSkill
- ldls-nativeSkill
- ldls-webSkill
- ledger-wallet-cliSkill
- legacy-migrationSkill
- new-packageSkill
- package-public-apiSkill
- pnpm-resolutionSkill
- prefer-set-hasSkill
- pre-reviewSkill
- react-generalSkill
- rebuild-to-fix-lib-import-errorsSkill
- remove-feature-flagSkill
- run-buildsSkill
- run-e2e-ciSkill
- runner-imagesSkill
- run-testsSkill
- slack-pr-messageSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 47
Place each element in the closest folder matching its reuse scope: screen-specific building blocks stay in the screen folder, feature-level …
- Distinctive: line 58
Use List / Detail naming for multi-view workflows.
- Distinctive: line 109
Keep relative imports shallow (within one directory level).
- Distinctive: line 110
Use TypeScript path aliases for broader access.
- Very specific: line 111
Never import index.tsx explicitly.
- Very specific: line 112
Import packages through their public entry (@features/flow-contacts), never a relative path into them.
- Very specific: line 130
Every feature folder under src/mvvm/features/ must have an integration test in __integrations__/.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
MVVM Architecture
Scope
apps/<app>/src/mvvm/ holds two kinds of code:
- App screens composing
@features/*: the screen, its routing, store and analytics wiring, and the adapters that connect a feature package to app internals. - App-only features: code that depends on app internals and that no other app or flow reuses.
src/mvvm is not the default home of new code. Decide placement with
structure-flow first: business-aware UI and journeys go to
features/, data access to domain/, generic code to shared/. The app folder keeps only what
composes them.
Example: desktop src/mvvm/features/Contacts/ renders @features/flow-contacts and passes it
app-side adapters (useContactsCurrencySelectionAdapter, useContactsAddressValidationAdapter).
The contacts journey itself lives in the flow package.
The ViewModel pattern is not apps-only: it is also mandatory in every
features/flow package. The folder structure below is apps-only; the anatomy of a flow package
belongs to the flow-package skill.
Folder Structure
Applies to apps/*/src/mvvm/ only.
src/mvvm/
├── features/
│ └── FeatureName/
│ ├── __integrations__/ ← mandatory integration tests
│ ├── components/ ← UI reused across this feature's screens
│ ├── screens/ ← individual screen folders
│ ├── hooks/ ← feature-scoped hooks, adapters to app internals
│ └── utils/ ← feature-scoped utilities
├── components/ ← UI shared by several app features
├── hooks/
└── utils/Place each element in the closest folder matching its reuse scope: screen-specific building blocks
stay in the screen folder, feature-level ones in FeatureName/components/, app-wide ones in
src/mvvm/components/. An element several apps need belongs in a package, not here.
Component & File Patterns
In src/mvvm/:
- Each component in its own folder with
index.tsxas entry. - ViewModel hooks always named
use<ComponentName>ViewModel.ts. - Support files alongside:
types.ts,styles.ts. - Use List / Detail naming for multi-view workflows.
- Utilities stay in
utils/, separate from component folders.
ViewModel Pattern
Components needing external logic use Container → ViewModel → View:
- The ViewModel produces data and handlers.
- The View receives everything via props, with no direct hook calls to external systems.
This applies to apps/*/src/mvvm/** and to features/flow/**.
In a features/flow package
One use<Screen>ViewModel.ts per screen produces data and handlers; <Screen>View.web.tsx and
<Screen>View.native.tsx render its props only, with no store, navigation or query hooks. The
container passes one to the other.
Example: @features/flow-portfolio-services-entry-points, every file of
src/components/ServicesEntryPoints/:
index.ts ← export * only
ServicesEntryPoints.tsx ← <ServicesEntryPointsView {...useServicesEntryPointsViewModel(props)} />
ServicesEntryPoints.types.ts ← the container's props
useServicesEntryPointsViewModel.ts ← feature flag, analytics, handlers
ServicesEntryPointsView.types.ts ← the props contract both views share
ServicesEntryPointsView.web.tsx ← props only
ServicesEntryPointsView.native.tsx ← props only
ServicesEntryPoints.web.test.tsx
ServicesEntryPoints.native.test.tsxViolation checklist: flag any View (index.tsx under screens/ or components/ in src/mvvm/, or *View.web.tsx / *View.native.tsx in features/flow/) that
- Imports
useSelectororuseDispatchfromreact-redux - Imports
useNavigationoruseRoutefrom@react-navigation/* - Calls any RTK Query hook (
useGet*Query,use*Mutation) - Has no corresponding
use<Name>ViewModel.tsin the same directory
❌ screens/UserProfileScreen/
index.tsx ← imports useSelector, useNavigation directly
✅ screens/UserProfileScreen/
index.tsx ← props only
useUserProfileScreenViewModel.ts ← useSelector, useNavigation, RTK QueryImport Rules
- Keep relative imports shallow (within one directory level).
- Use TypeScript path aliases for broader access.
- Never import
index.tsxexplicitly; use folder alias exports. - Import packages through their public entry (
@features/flow-contacts), never a relative path into them.
Data Fetching
API calls and RTK Query endpoints live in a domain/api package such as @domain/api-push-devices.
A ViewModel in src/mvvm calls their hooks; it does not define endpoints. See
domain-data.
Design System
New UI in src/mvvm/ must use Lumen:
- Desktop:
ldls-webskill - Mobile:
ldls-nativeskill
Testing
Every feature folder under src/mvvm/features/ must have an integration test in
__integrations__/; create a minimal test when the folder is first added. See
testing skill.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

