# kashirapp/kashir architecture

> Architecture diagram of the GitHub repository kashirapp/kashir, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kashirapp/kashir
- Repository: https://github.com/kashirapp/kashir

## Overview

##### Project Type and Purpose
- Kashir is a full-stack mobile application (React Native) functioning as an ecash (Cashu) wallet.
- It combines a TypeScript/JavaScript UI layer, business logic services, native modules (Android/iOS), and Rust-based SDKs (nostr-sdk-ffi, cdk-ffi) exposed via FFI.

##### File-Structure Analysis
- Top-level:
- deps/nostr-sdk-ffi and deps/cdk-ffi: Rust crates compiled to native libraries for FFI.
- scripts/: build and binding-fix scripts.
- Yarn PnP config files (.yarn/, .yarnrc.yml, turbo.json).
- tsconfig*.json, babel.config.js, eslint.config.mjs for TS/JS tooling.
- example/: The React Native application:
- example/src/: TSX components (UI), hooks, services (business logic), utils, types.
- example/android/ and example/ios/: Native code wrappers, Gradle and Xcode project files, native modules (IntentLauncher).
- Metro, Jest, and React Native config files.
- Config: ubrn.nostr.config.yaml, zapstore.yaml, ubrn.cdk.config.yaml define the Cashu and Nostr environments.

##### README Insights
- Briefly states core technologies: React Native, rust-nostr SDK, and Cashu Development Kit.

##### Main Components
a. Frontend (React Native JS/TS)
– UI Components (screens, modals, navigation)
– Hooks and State Management
– Business-logic Services (NostrClient, AmberService, WalletManager, etc.)
b. Native Modules
– Android (IntentLauncherModule, etc.)
– iOS (bridged Swift modules)
c. FFI Layer
– Rust Native Libraries from deps/nostr-sdk-ffi and deps/cdk-ffi
– React Native NativeModules bridging to Rust
d. Persistence
– SecureStorageService (on-device secure key/value)
– CacheService (local cache)
e. External Services
– Nostr Relays (via NostrClient over WebSocket)
– Cashu Mint Servers (LNURL, DVMService, MintRecommendationService)
– Location APIs (via LocationService)
f. Build & Tooling
– Yarn PnP, Turbo repo orchestration
– Metro bundler, Babel transpilation
– Gradle (Android), Xcode (iOS), scripts/build-android.sh

##### Relationships and Data Flows
- User taps UI → React Native JS
- JS invokes Services → may call NativeModules (IntentLauncher) or FFI methods (Rust SDKs)
- Rust modules handle cryptographic operations, networking (to Nostr relays, Cashu servers)
- Responses flow back through FFI → JS Services → UI updates
- Persist transaction data via SecureStorageService/CacheService

##### Architectural Patterns and Principles
- Layered architecture:
1. Presentation (React Native components)
2. Application (Services, Hooks)
3. Infrastructure (FFI + NativeModules, Secure Storage)
4. External (Relays, Mint Servers)
- Single source of truth for wallet state managed via Services and Hooks.
- Clear separation of concerns: UI vs. business logic vs. cryptography/networking.

##### Essential Elements to Capture
- FFI bridge between JS and Rust crates.
- NativeModules for Android/iOS.
- Core Services classes and their external dependencies (Nostr relays, LNURL).
- Secure and Cache storage components.
- Build pipeline (Yarn PnP, Metro, Gradle, Xcode) as supporting infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UIComponents["UI Components"]:::frontend
        HooksState["Hooks & State Management"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        NostrClient["NostrClient Service"]:::service
        DVMService["Cashu DVM Service"]:::service
        LNURLService["Cashu LNURL Service"]:::service
        MintRecService["Mint Recommendation Service"]:::service
        WalletManager["Wallet Manager Service"]:::service
        IntentLauncherJS["IntentLauncher JS Bridge Service"]:::service
        LocationService["Location Service"]:::service
        SecureStorage["SecureStorageService"]:::persistence
        CacheService["CacheService"]:::persistence
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        subgraph "Native Modules"
            direction TB
            AndroidNative["Android IntentLauncherModule"]:::native
            iOSNative["iOS AppDelegate Bridge"]:::native
        end
        subgraph "FFI Layer"
            direction TB
            NostrSDK["Rust SDK (nostr-sdk-ffi)"]:::rust
            CDKSDK["Rust SDK (cdk-ffi)"]:::rust
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        NostrRelays["Nostr Relays (WebSocket)"]:::external
        CashuMint["Cashu Mint Servers (HTTP/LNURL)"]:::external
        LocationAPI["Location APIs"]:::external
    end

    %% DevOps/Build
    subgraph "DevOps & Build Tools"
        direction TB
        YarnPnP["Yarn PnP & Monorepo Config"]:::devops
        MetroBabel["Metro & Babel Config"]:::devops
        BuildScripts["Build & Binding Scripts"]:::devops
    end

    %% Data Flows
    UIComponents -->|uses| HooksState
    HooksState -->|calls| WalletManager
    HooksState -->|calls| NostrClient
    HooksState -->|calls| DVMService
    HooksState -->|calls| LNURLService
    HooksState -->|calls| MintRecService
    HooksState -->|calls| IntentLauncherJS
    HooksState -->|calls| LocationService

    WalletManager -->|manages state| SecureStorage
    WalletManager -->|caches| CacheService

    NostrClient -->|FFI call| NostrSDK
    DVMService -->|FFI call| CDKSDK
    LNURLService -->|FFI call| CDKSDK
    MintRecService -->|FFI call| CDKSDK

    IntentLauncherJS -->|native bridge| AndroidNative
    IntentLauncherJS -->|native bridge| iOSNative

    NostrSDK -->|connects| NostrRelays
    CDKSDK -->|connects| CashuMint
    LocationService -->|calls| LocationAPI

    %% Click Events
    click UIComponents "https://github.com/kashirapp/kashir/tree/master/example/src/components"
    click HooksState "https://github.com/kashirapp/kashir/tree/master/example/src/hooks"
    click NostrClient "https://github.com/kashirapp/kashir/blob/master/example/src/services/NostrClient.ts"
    click DVMService "https://github.com/kashirapp/kashir/blob/master/example/src/services/DVMService.ts"
    click LNURLService "https://github.com/kashirapp/kashir/blob/master/example/src/services/LNURLService.ts"
    click MintRecService "https://github.com/kashirapp/kashir/blob/master/example/src/services/MintRecommendationService.ts"
    click WalletManager "https://github.com/kashirapp/kashir/blob/master/example/src/services/WalletManager.ts"
    click IntentLauncherJS "https://github.com/kashirapp/kashir/blob/master/example/src/services/IntentLauncher.ts"
    click LocationService "https://github.com/kashirapp/kashir/blob/master/example/src/services/LocationService.ts"
    click SecureStorage "https://github.com/kashirapp/kashir/blob/master/example/src/services/SecureStorageService.ts"
    click CacheService "https://github.com/kashirapp/kashir/blob/master/example/src/services/CacheService.ts"
    click AndroidNative "https://github.com/kashirapp/kashir/blob/master/example/android/app/src/main/java/com/kashir/android/IntentLauncherModule.kt"
    click iOSNative "https://github.com/kashirapp/kashir/blob/master/example/ios/Kashir/AppDelegate.swift"
    click NostrSDK "https://github.com/kashirapp/kashir/tree/master/deps/nostr-sdk-ffi"
    click CDKSDK "https://github.com/kashirapp/kashir/tree/master/deps/cdk-ffi"
    click BuildScripts "https://github.com/kashirapp/kashir/blob/master/scripts/build-android.sh"
    click YarnPnP "https://github.com/kashirapp/kashir/tree/master/.yarn/"
    click MetroBabel "https://github.com/kashirapp/kashir/blob/master/example/metro.config.js"

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px
    classDef service fill:#cff,stroke:#333,stroke-width:1px
    classDef persistence fill:#eef,stroke:#333,stroke-width:1px
    classDef native fill:#ddd,stroke:#333,stroke-width:1px
    classDef rust fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#fcf,stroke:#333,stroke-width:1px
    classDef devops fill:#ffe,stroke:#333,stroke-width:1px
```
