# neptune-crypto/neptune-core architecture

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

- Interactive diagram: https://gitdiagram.com/neptune-crypto/neptune-core
- Repository: https://github.com/neptune-crypto/neptune-core

## Overview

##### Main Components
- Node/Daemon: Represent the central server that runs the blockchain protocol and processes transactions. This includes key internal modules such as:
- Consensus Engine and Mining Loop: Modules in src/main_loop, src/mine_loop, and relevant parts in src/models/blockchain (blocks, transactions, and validity).
- Peer Networking: Files like src/connect_to_peers.rs, src/peer_loop.rs, and parts of src/models/peer indicate a distinct networking layer responsible for establishing connections and handling peer discovery.
- Job Queue & Asynchronous Processing: Modules in src/job_queue (including the triton_vm submodule) show that tasks like VM proving or validation are queued and processed asynchronously.
- RPC & CLI Interfaces: With src/rpc_server.rs and src/bin/neptune-cli.rs, there is a clear separation for interacting with the node via either CLI commands or through RPC (and a separate dashboard in src/bin/dashboard_src).
- Storage and Database Layer: Directories under src/database and subdirectories of storage (including both LevelDB-specific modules and custom storage schemas) need representation as the backend data persistence layer.
- Locks and Concurrency: Both “std” and “tokio” locks in src/locks highlight that synchronization and concurrency are managed using different locking implementations.
- Configuration and Models: The parsing and management (in src/config_models and src/models) for blockchain data (transactions, blocks, wallets, etc.) show that the system uses a couple of domain models and configuration patterns.

- Client Components:
- CLI Client: The neptune-cli (src/bin/neptune-cli.rs) serves as a command-line tool to interact with a running instance.
- Dashboard: The console-based dashboard in src/bin/dashboard_src is another interactive front-end for display and user actions.

- External Dependencies and Tools:
- LevelDB: Indicated in both the README and in the src/database folders, LevelDB is a key external dependency.
- Tokio (and optionally tokio-console): Used for asynchronous operations and monitoring.
- Build scripts, benchmarks, tests and CI (via GitHub Actions) are essential for the overall delivery process but can be grouped as supporting/devops infrastructure.

##### Relationships and Interactions
- The Node/Daemon acts as the core container, integrating the consensus, networking, and storage modules.
- Peer networking interacts with external nodes (peers) for transaction propagation and block consensus.
- The consensus and mining loops process new blocks and transactions; they read from and persist to the database.
- The RPC server listens for incoming commands from the CLI and dashboard client.
- The job queue handles asynchronous tasks and communicates with cryptographic proof modules (located under src/models/proof_abstractions and src/job_queue/triton_vm).
- External script directories (scripts/) indicate automation for testing, deployment, backup, and node management—but can be abstracted as utility/integration tools converging on the node.

##### Architectural Patterns and Design Principles
- Modularization: Notice the clear separation into directories for configuration, models, networking, consensus, storage, and locking. This suggests each module/component is self-contained.
- Layered Architecture: There’s a clear layering—from hardware/infrastructure (peers, networking connections) to application logic (consensus, blockchain processing) to presentation (CLI, dashboard).
- Asynchronous Processing: The use of tokio-based locks and async patterns, as well as a dedicated job queue, highlight the emphasis on handling concurrent tasks.
- Extensibility/Plugin: The separation of components such as proof abstractions means new cryptographic mechanisms or transaction validations can be introduced later.

- If possible, add brief annotations on critical interfaces (for example, “Asynchronous calls via Tokio” or “LevelDB storage for blocks & transactions”).
- A separate container for “Supporting Tools” can be added to note benchmarking, testing, and deployment scripts.

##### Essential Architectural Elements
- Supportive infrastructure like CI pipelines (GitHub workflows) and documentation (mdBook usage) either as side notes or a development tooling layer.

- Component separation between the node’s core processing (consensus, job queue, networking, database) and front-end interfaces (CLI & dashboard).
- Clear directional data flows and dependencies among modules.
- The use of external libraries/technologies like LevelDB and tokio.
- All the significant architectural decisions that are evidenced in the project file structure and documented in the README.

This level of detail will yield a clear, accurate depiction of Neptune Core’s system architecture, which is crucial for both development and maintenance going forward.

## Diagram (Mermaid)

```mermaid
flowchart TD
    NA["Node/Daemon"]:::core

    subgraph "Core Daemon Modules"
        CONS["Consensus Engine & Mining Loop"]:::core
        NET["Peer Networking"]:::core
        JQ["Job Queue & Async Processing"]:::core
        RPCS["RPC Server"]:::core
        DB["Storage & Database (LevelDB)"]:::db
        LOCK["Locks & Concurrency"]:::core
        CFG["Configuration & Domain Models"]:::core
    end

    subgraph "Front-End Clients"
        CLI["CLI Client"]:::client
        DASH["Dashboard UI"]:::client
    end

    subgraph "External/Tools"
        EXT["Peer Nodes (External)"]:::external
        LVL["LevelDB Dependency"]:::external
        TOKIO["Tokio Library"]:::external
        CI["CI/CD & Scripts"]:::external
    end

    NA --> CONS
    NA --> NET
    NA --> JQ
    NA --> RPCS
    NA --> DB
    NA --> LOCK
    NA --> CFG

    NET -->|"connects_to"| EXT
    CONS -->|"persists_to"| DB
    JQ -->|"async_tasks_for"| CONS
    CLI -->|"commands_to"| RPCS
    DASH -->|"commands_to"| RPCS

    DB -->|"uses"| LVL
    JQ -->|"uses_async"| TOKIO

    CI --- NA

    click NA "https://github.com/neptune-crypto/neptune-core/blob/master/src/main.rs"
    click CONS "https://github.com/neptune-crypto/neptune-core/tree/master/src/main_loop/"
    click CONS "https://github.com/neptune-crypto/neptune-core/tree/master/src/mine_loop/"
    click CONS "https://github.com/neptune-crypto/neptune-core/tree/master/src/models/blockchain"
    click NET "https://github.com/neptune-crypto/neptune-core/blob/master/src/connect_to_peers.rs"
    click NET "https://github.com/neptune-crypto/neptune-core/blob/master/src/peer_loop.rs"
    click NET "https://github.com/neptune-crypto/neptune-core/tree/master/src/models/peer"
    click JQ "https://github.com/neptune-crypto/neptune-core/tree/master/src/job_queue"
    click JQ "https://github.com/neptune-crypto/neptune-core/tree/master/src/job_queue/triton_vm"
    click RPCS "https://github.com/neptune-crypto/neptune-core/blob/master/src/rpc_server.rs"
    click CLI "https://github.com/neptune-crypto/neptune-core/blob/master/src/bin/neptune-cli.rs"
    click DASH "https://github.com/neptune-crypto/neptune-core/tree/master/src/bin/dashboard_src"
    click DB "https://github.com/neptune-crypto/neptune-core/tree/master/src/database"
    click LOCK "https://github.com/neptune-crypto/neptune-core/tree/master/src/locks/std"
    click LOCK "https://github.com/neptune-crypto/neptune-core/tree/master/src/locks/tokio"
    click CFG "https://github.com/neptune-crypto/neptune-core/tree/master/src/config_models"
    click CFG "https://github.com/neptune-crypto/neptune-core/tree/master/src/models"

    classDef core fill:#B0E0E6,stroke:#000,stroke-width:2px;
    classDef client fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef db fill:#FDF5E6,stroke:#000,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
