Architecture

Technical description of the Ledger Wallet monorepo folder structure, import rules, and platform-specific file conventions.

Root Folder Structure

The monorepo is organized into the following areas:

Folder	Purpose
`apps/`	Platform-specific cross-cutting concerns
`features/`	Feature modules with high cohesion and low coupling
`libs/`	Legacy shared libraries — being progressively migrated into features

├─ apps/
│  ├─ ledger-live-desktop/
│  │  ├─ state-manager/
│  │  │  └─ configureStore.ts
│  │  └─ router/
│  │     └─ router.ts
│  └─ ledger-live-mobile/
│     ├─ state-manager/
│     │  └─ configureStore.ts
│     └─ router/
│        └─ router.ts
├─ features/
│  └─ {featureName}/
└─ libs/  // Legacy - being migrated into features

Apps Folder

The apps/ folder contains platform-specific cross-cutting concerns:

Observability — Logging, monitoring, error tracking
Routing — Platform-specific navigation (imports routes from features)
Analytics — Platform-specific analytics utilities
State Manager — Store configuration

⚠️

Apps should not contain business logic. They wire together features and provide platform infrastructure.

Features Folder

Features are self-contained modules with high cohesion and low coupling.

Feature Structure

features/
└─ posts/
   ├─ components/
   │  ├─ post.web.ts
   │  ├─ post.native.ts
   │  └─ post.test.ts
   ├─ screens/
   │  └─ components/
   │     ├─ posts.web.ts
   │     ├─ posts.native.ts
   │     └─ posts.test.ts
   ├─ data-layer/
   │  └─ entities/
   │     └─ post/
   │        ├─ postSchema.ts
   │        ├─ postSchema.test.ts
   │        ├─ postSelectors.ts
   │        ├─ postSelectors.test.ts
   │        ├─ postActions.ts
   │        ├─ postActions.test.ts
   │        ├─ postSlice.ts
   │        └─ postSlice.test.ts
   ├─ routes/
   │  └─ route.ts
   ├─ hooks/
   └─ utils/

Feature Subfolders

Subfolder	Purpose
`components/`	Reusable UI components within the feature
`screens/`	Screen-level components (can have their own `components/` subfolder)
`data-layer/`	State management: entities, slices, selectors, actions, API
`routes/`	Platform-agnostic routing abstraction
`hooks/`	Feature-specific custom hooks
`utils/`	Feature-specific utilities

Platform-Specific Files

Use file extensions to target specific platforms:

Extension	Platform
`.web.ts`	Web and Desktop (Electron)
`.native.ts`	React Native (iOS + Android)
`.ios.ts`	iOS only
`.android.ts`	Android only
No extension	Shared across all platforms

Example

components/
├─ userInfo.ts           // Shared logic
├─ userInfo.web.ts       // Web/Desktop UI
├─ userInfo.native.ts    // Mobile UI
└─ userInfo.test.ts      // Tests

⚠️

Test files (*.test.ts) should always be colocated with their source files.

Import Rules

Strict import boundaries enforce the architectural layers.

Forbidden Imports

🚫

These import directions are not allowed:

features/** → apps/**

Allowed Imports

These import directions are allowed:

apps/** → features/** (apps wire features together)
features/{feature}/** → features/{feature}/** (within the same feature)

Import Flow Diagram

┌─────────────────────────────────────────────────────────┐
│                         apps/                           │
│              (can import from features)                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
               ┌─────────────────┐
               │    features/    │
               └─────────────────┘