# 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

> **Warning:** 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
```

> **Warning:** Test files (`*.test.ts`) should always be colocated with their source files.

---

## Import Rules

Strict import boundaries enforce the architectural layers.

### Forbidden Imports

> **Caution:** These import directions are **not allowed**:* `features/**` → `apps/**`

### Allowed Imports

> **Note:** 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/    │
               └─────────────────┘
```

---

## See also

- [How to Structure a Feature](../how-to/structure-a-feature) — Step-by-step guide for creating features
- [Component Patterns](./component-patterns) — Do's and Don'ts for naming and folder organization
- [Architecture Decisions](../explanation/architecture-decisions) — Why we adopted this folder structure