# dgarage/nbxplorer architecture

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

- Interactive diagram: https://gitdiagram.com/dgarage/nbxplorer
- Repository: https://github.com/dgarage/nbxplorer

## Overview

##### Project type and purpose
- NBXplorer is a .NET Core service (ASP .NET Web API) that tracks UTXOs for HD wallets.
- It exposes a REST/WS API, schedules background “hosted services,” persists data to Postgres, and talks to Bitcoin (and altcoin) full nodes via RPC.
- It includes a client library (`NBXplorer.Client`), examples, and a large test suite.

##### File structure
- Top-level “NBXplorer” folder: server code (Controllers, Backend, HostedServices, Configuration, MessageBrokers, etc.).
- “NBXplorer.Client”: reusable .NET client library.
- “NBXplorer.Tests”: integration/unit tests with Docker setups.
- “Examples”: sample apps using the client library.
- Docker, CI (CircleCI), build scripts, docs.

##### README insights
- Core components: REST API, WebSockets, long-polling, Postgres persistence, RPC to Bitcoin node, message brokers (RabbitMQ/Azure).
- Architectural notes: MVC-style Controllers, DI, hosted background tasks, repository/data-access layers, DB migrations, pluggable altcoin support.

##### Main components & interactions
a. API Layer
- ASP .NET Core Web API (Controllers folder)
- Routes: Derivations, Transactions, Groups, Events
b. Business / Core Logic
- Services, HostedServices (UTXOFetcher, RefreshWalletHistory, DatabaseSetup, etc.)
- Analytics, EventAggregator, Broadcaster
- DerivationStrategy modules (P2PKH, P2WPKH, Taproot, multisig)
c. Data Access Layer
- RepositoryProvider → Repository → DbConnectionFactory
- DB scripts (DBScripts folder) handle schema/migrations
- Postgres
d. External Dependencies
- Bitcoin Core / Altcoin node(s) (RPC interface)
- Optional Message Brokers: RabbitMQ or Azure Service Bus
e. Client Library
- `NBXplorer.Client` (ExplorerClient, Models, JsonConverters, WebsocketNotificationSession)
- Used by external apps (Examples)
f. Tests
- CustomHttpServer, Docker compose setups, data fixtures

##### Architectural patterns & design principles
- MVC for API (Controllers → Services → Repositories)
- Repository pattern for DB access
- Dependency Injection (ASP .NET Core DI container)
- HostedServices for background, periodic tasks
- Pub/Sub abstraction for events (long-polling, WebSockets, message brokers)
- Strategy pattern for derivation schemes (IStrategy, Direct, Multisig, Taproot)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        BitcoinCore["Bitcoin/Altcoin RPC"]:::external
        MessageBrokers["Message Brokers (RabbitMQ/Azure)"]:::external
        Clients["Client Apps (NBXplorer.Client & Examples)"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        Controllers["Controllers"]:::internal
        Filters["Filters & Middleware"]:::internal
    end

    %% Core Services
    subgraph "Core Services"
        EventAggregator["EventAggregator"]:::internal
        Broadcaster["Broadcaster"]:::internal
    end

    %% Hosted Services
    subgraph "Hosted Services"
        UTXOFetcher["UTXOFetcherService"]:::hosted
        RefreshWallet["RefreshWalletHistoryPeriodicTask"]:::hosted
        DatabaseSetup["DatabaseSetupHostedService"]:::hosted
    end

    %% Data Access & Persistence
    subgraph "Data Access & Persistence"
        RepositoryProvider["RepositoryProvider"]:::internal
        Repository["Repository"]:::internal
        DbConnectionFactory["DbConnectionFactory"]:::internal
        DBScripts["DB Scripts & Migrations"]:::internal
        Postgres["Postgres"]:::external
    end

    %% Client Library
    subgraph "Client Library"
        ExplorerClient["ExplorerClient & Models"]:::client
        WebsocketSession["WebsocketNotificationSession"]:::client
        LongPollingSession["LongPollingNotificationSession"]:::client
        DerivationStrategies["DerivationStrategy Plugins"]:::client
    end

    %% Configuration & Startup
    subgraph "Configuration & Startup"
        Configuration["Configuration"]:::internal
        Startup["Program & Startup"]:::internal
    end

    %% Connections
    Clients -->|"HTTP/WS"| Controllers
    Controllers -->|"applies"| Filters
    Controllers -->|"calls"| EventAggregator
    Controllers -->|"uses"| Repository
    EventAggregator -->|"publishes"| Broadcaster
    Broadcaster -->|"publishes events"| MessageBrokers
    UTXOFetcher -->|"fetches UTXO via RPC"| BitcoinCore
    UTXOFetcher -->|"updates"| Repository
    RefreshWallet -->|"updates"| Repository
    DatabaseSetup -->|"runs migrations"| DBScripts
    DatabaseSetup -->|"initializes"| Repository
    RepositoryProvider -->|"creates"| Repository
    Repository -->|"opens"| DbConnectionFactory
    DbConnectionFactory -->|"connects"| Postgres
    Configuration -->|"loaded by"| Startup
    Startup -->|"configures DI"| Controllers
    Startup -->|"registers"| UTXOFetcher
    Startup -->|"registers"| RefreshWallet
    Startup -->|"registers"| DatabaseSetup
    ExplorerClient -->|"calls API"| Controllers
    WebsocketSession -->|"connects WS"| Controllers
    LongPollingSession -->|"connects LP"| Controllers
    DerivationStrategies -.->|"plug into"| EventAggregator

    %% Click Events
    click Controllers "https://github.com/dgarage/nbxplorer/tree/master/NBXplorer/Controllers"
    click UTXOFetcher "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/HostedServices/UTXOFetcherService.cs"
    click RefreshWallet "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/HostedServices/RefreshWalletHistoryPeriodicTask.cs"
    click DatabaseSetup "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/HostedServices/DatabaseSetupHostedService.cs"
    click EventAggregator "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/EventAggregator.cs"
    click Broadcaster "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/Broadcaster.cs"
    click DerivationStrategies "https://github.com/dgarage/nbxplorer/tree/master/NBXplorer.Client/DerivationStrategy"
    click RepositoryProvider "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/Backend/RepositoryProvider.cs"
    click Repository "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/Backend/Repository.cs"
    click DbConnectionFactory "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/Backend/DbConnectionFactory.cs"
    click DBScripts "https://github.com/dgarage/nbxplorer/tree/master/NBXplorer/DBScripts"
    click BitcoinCore "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/RPCClientProvider.cs"
    click MessageBrokers "https://github.com/dgarage/nbxplorer/tree/master/NBXplorer/MessageBrokers"
    click Configuration "https://github.com/dgarage/nbxplorer/tree/master/NBXplorer/Configuration"
    click Startup "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer/Program.cs"
    click ExplorerClient "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer.Client/ExplorerClient.cs"
    click WebsocketSession "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer.Client/WebsocketNotificationSession.cs"
    click LongPollingSession "https://github.com/dgarage/nbxplorer/blob/master/NBXplorer.Client/LongPollingNotificationSession.cs"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0000AA
    classDef external fill:#C6F6D5,stroke:#38A169
    classDef hosted fill:#FAF089,stroke:#D69E2E
    classDef client fill:#FEEBC8,stroke:#DD6B20
```
