# cashubtc/nutshell architecture

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

- Interactive diagram: https://gitdiagram.com/cashubtc/nutshell
- Repository: https://github.com/cashubtc/nutshell

## Overview

##### Main Components Overview
The system should be divided into these major components:

a) Core Components:
- Crypto Module (cashu/core/crypto/)
- Core Models and Base Classes (cashu/core/)
- Nuts Protocol Implementation (cashu/core/nuts/)

b) Wallet Components:
- Wallet API Server
- CLI Interface
- Lightning Integration
- Storage/Database Layer

c) Mint Components:
- Mint Server
- Lightning Backend Integrations
- Database Layer
- Event System

d) Supporting Systems:
- Nostr Integration
- Tor Integration
- Lightning Network Interfaces

##### Component Relationships and Data Flow

**[Client/External] <-> [Wallet API/CLI] <-> [Core Crypto] <-> [Mint Server] <-> [Lightning Network]**

##### Detailed Component Breakdown

a) Core Layer (Bottom):
**[Crypto Operations (secp, b_dhke)] <-> [Nuts Protocol] <-> [Base Models]**

b) Mint Layer (Middle):
**[Lightning Backends] -> [Mint Server] -> [Ledger] -> [Database]**
- > [Events System]
- > [Cache]

c) Wallet Layer (Top):
**[CLI Interface] -> [Wallet API] -> [Proofs/Transactions] -> [Core]**
- > [Lightning Integration]
- > [Local Storage]

##### Important Architectural Elements to Highlight

- Separation between:
- Core crypto operations
- Wallet functionality
- Mint services
- External integrations

- Modular nature of:
- Lightning backend implementations
- Database support (PostgreSQL/SQLite)
- Protocol implementations (Nuts)

##### Technical Stack Indicators

Technology badges or labels for:
- Python
- FastAPI (for API servers)
- Lightning Network
- PostgreSQL/SQLite
- Nostr
- Tor

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef core fill:#b3e0ff,stroke:#333,stroke-width:2px
    classDef wallet fill:#98FB98,stroke:#333,stroke-width:2px
    classDef mint fill:#FFE4B5,stroke:#333,stroke-width:2px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef support fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef db cylinder

    %% External Layer
    subgraph External
        LN[Lightning Network]:::external
        Nostr[Nostr Network]:::external
        Tor[Tor Network]:::external
    end

    %% Interface Layer
    subgraph Interface
        CLI[CLI Interface]:::wallet
        WalletAPI[Wallet API Server]:::wallet
    end

    %% Service Layer
    subgraph Services
        direction TB
        WalletCore[Wallet Core]:::wallet
        ProofsTx[Proofs & Transactions]:::wallet
        MintServer[Mint Server]:::mint
        Events[Events System]:::mint
        Ledger[Ledger]:::mint
    end

    %% Lightning Integration Layer
    subgraph Lightning
        LNBase[Lightning Base]:::core
        LNDGRPC[LND gRPC]:::core
        LNBits[LNBits]:::core
        CLNRest[CLN REST]:::core
    end

    %% Core Layer
    subgraph Core
        direction TB
        CoreModels[Core Models]:::core
        BaseClasses[Base Classes]:::core
        NutsProtocol[Nuts Protocol]:::core
        CryptoOps[Crypto Operations]:::core
        HTLC[HTLC]:::core
        P2PK[P2PK]:::core
    end

    %% Database Layer
    subgraph Storage
        CoreDB[(Core DB)]:::db
        MintDB[(Mint DB)]:::db
    end

    %% Relationships
    CLI --> WalletAPI
    WalletAPI --> WalletCore
    WalletCore --> ProofsTx
    ProofsTx --> CoreModels
    MintServer --> Ledger
    MintServer --> Events
    Ledger --> MintDB
    WalletCore --> CoreDB
    
    LNBase --> |Integration| LNDGRPC & LNBits & CLNRest
    LNDGRPC & LNBits & CLNRest --> LN
    
    CoreModels --> NutsProtocol
    NutsProtocol --> CryptoOps
    CryptoOps --> HTLC & P2PK
    
    MintServer --> LNBase
    WalletCore --> LNBase
    
    WalletCore --> Nostr
    WalletCore --> Tor

    %% Click Events
    click CLI "https://github.com/cashubtc/nutshell/blob/main/cashu/wallet/cli/cli.py"
    click WalletAPI "https://github.com/cashubtc/nutshell/blob/main/cashu/wallet/api/api_server.py"
    click WalletCore "https://github.com/cashubtc/nutshell/blob/main/cashu/wallet/wallet.py"
    click ProofsTx "https://github.com/cashubtc/nutshell/blob/main/cashu/wallet/proofs.py"
    click MintServer "https://github.com/cashubtc/nutshell/blob/main/cashu/mint/main.py"
    click Events "https://github.com/cashubtc/nutshell/tree/main/cashu/mint/events/"
    click Ledger "https://github.com/cashubtc/nutshell/blob/main/cashu/mint/ledger.py"
    click LNBase "https://github.com/cashubtc/nutshell/blob/main/cashu/lightning/base.py"
    click LNDGRPC "https://github.com/cashubtc/nutshell/tree/main/cashu/lightning/lnd_grpc/"
    click LNBits "https://github.com/cashubtc/nutshell/blob/main/cashu/lightning/lnbits.py"
    click CLNRest "https://github.com/cashubtc/nutshell/blob/main/cashu/lightning/clnrest.py"
    click CoreModels "https://github.com/cashubtc/nutshell/blob/main/cashu/core/models.py"
    click BaseClasses "https://github.com/cashubtc/nutshell/blob/main/cashu/core/base.py"
    click NutsProtocol "https://github.com/cashubtc/nutshell/tree/main/cashu/core/nuts/"
    click CryptoOps "https://github.com/cashubtc/nutshell/tree/main/cashu/core/crypto/"
    click HTLC "https://github.com/cashubtc/nutshell/blob/main/cashu/core/htlc.py"
    click P2PK "https://github.com/cashubtc/nutshell/blob/main/cashu/core/p2pk.py"
    click CoreDB "https://github.com/cashubtc/nutshell/blob/main/cashu/core/db.py"
    click MintDB "https://github.com/cashubtc/nutshell/tree/main/cashu/mint/db/"
```
