| name | monorepo-navigation |
| description | Navigate and understand the Leather monorepo structure. Use when adding new code, finding existing implementations, or understanding package relationships. Helps locate the right package for new features and understand cross-package dependencies. |
Leather Monorepo Navigation
This is a Turborepo monorepo with 3 apps and packages organized in a CLEAN architecture.
Architecture Layers
Presentation → apps/, @leather.io/ui, @leather.io/features, @leather.io/provider
Application → @leather.io/queries, @leather.io/services, @leather.io/rpc, @leather.io/sdk, @leather.io/cms
Domain → @leather.io/models, @leather.io/bitcoin, @leather.io/stacks
State → @leather.io/state (Redux Toolkit)
Foundation → @leather.io/utils, @leather.io/constants, @leather.io/tokens, @leather.io/crypto, @leather.io/analytics
Apps
| App | Path | Purpose |
|---|
| extension | apps/extension/ | Chrome/Firefox browser extension |
| mobile | apps/mobile/ | React Native iOS/Android app (Expo) |
| web | apps/web/ | React Router web app at app.leather.io |
Domain Layer Packages
| Package | Path | Scope |
|---|
@leather.io/models | packages/models/ | Domain types and interfaces |
@leather.io/bitcoin | packages/bitcoin/ | Bitcoin protocol utilities, address handling, PSBTs |
@leather.io/stacks | packages/stacks/ | Stacks protocol utilities, transactions |
Import rules for domain peers:
- All three can import types from each other
bitcoin/stacks should NOT import logic from models (only types)
Application Layer Packages
| Package | Path | Scope |
|---|
@leather.io/services | packages/services/ | Orchestration only — API calls, DI, caching, multi-service coordination |
@leather.io/queries | packages/queries/ | React Query configurations |
@leather.io/query | packages/query/ | Legacy query package (migrate to @leather.io/queries) |
@leather.io/rpc | packages/rpc/ | RPC client abstraction |
@leather.io/sdk | packages/sdk/ | SDK utilities |
@leather.io/cms | packages/cms/ | CMS integration |
Services should NOT contain:
- Pure domain logic (move to
models, bitcoin, or stacks)
- Utility functions (move to
utils)
State Management
| Package | Path | Scope |
|---|
@leather.io/state | packages/state/ | Shared Redux Toolkit slices (wallet, keychains) |
App-specific state:
- Extension:
apps/extension/src/app/store/ — {feature}.slice.ts convention
- Mobile:
apps/mobile/src/store/ — {feature}.write.ts (slice + actions) and {feature}.read.ts (selectors + hooks)
Foundation Packages
| Package | Path | Scope |
|---|
@leather.io/utils | packages/utils/ | Generic utilities (money, formatting, guards) |
@leather.io/constants | packages/constants/ | Shared constants, currency decimals |
@leather.io/crypto | packages/crypto/ | Cryptographic primitives, key derivation |
@leather.io/tokens | packages/tokens/ | Token metadata |
@leather.io/analytics | packages/analytics/ | Mixpanel analytics |
Presentation Layer Packages
| Package | Path | Scope |
|---|
@leather.io/ui | packages/ui/ | Shared UI components (React) |
@leather.io/features | packages/features/ | View models, UI transforms |
@leather.io/provider | packages/provider/ | App provider utilities |
Decision Tree: Where Does New Code Go?
Is it PURE business logic (no I/O, no async, no side effects)?
├─ Yes → Is it chain-specific protocol code?
│ ├─ Bitcoin protocol → packages/bitcoin/src/
│ ├─ Stacks protocol → packages/stacks/src/
│ └─ No → packages/models/src/
│
Is it orchestration (API calls, DI, caching, coordination)?
├─ Yes → packages/services/src/{domain}/
│
Is it a domain type/interface?
├─ Yes → packages/models/src/
│
Is it a generic utility (not domain-specific)?
├─ Yes → packages/utils/src/
│
Is it a UI component?
├─ Yes → packages/ui/src/components/
│
Is it React Query configuration?
├─ Yes → packages/queries/src/
│
Is it app-specific?
└─ Yes → apps/{app}/src/
Key Conventions
- Barrel exports: Each package has
src/index.ts exporting public API
- Internal imports: Use
@leather.io/{package} not relative paths across packages
- Co-located tests:
{file}.spec.ts next to source file
- Kebab-case filenames:
bitcoin-address.ts not bitcoinAddress.ts
- Platform suffixes:
.web.tsx, .native.tsx, .shared.ts for cross-platform code
Common Tasks
Adding a Bitcoin protocol utility
packages/bitcoin/src/utils/{feature-name}.ts
packages/bitcoin/src/utils/{feature-name}.spec.ts
Export from packages/bitcoin/src/utils/index.ts
Adding a domain type
packages/models/src/{area}.model.ts
Adding orchestration logic
packages/services/src/{domain}/{domain}.service.ts
Should only contain: API calls, DI, caching, multi-service coordination
Adding a UI component
packages/ui/src/components/{component-name}/
├─ {component-name}.tsx
├─ {component-name}.web.tsx (if platform-specific)
└─ index.ts
