# mateusfreira/nun-db architecture

> Architecture diagram of the GitHub repository mateusfreira/nun-db, 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/mateusfreira/nun-db
- Repository: https://github.com/mateusfreira/nun-db

## Overview

##### Main Components
- Network Layer: Detail how incoming requests are handled. The “src/lib/network” folder includes http_ops, tcp_ops, and ws_ops modules. This layer is where incoming text-based commands from clients are received.
- Request Processing: Modules like “parse_request.rs” and “process_request.rs” indicate that raw requests are parsed and then dispatched to the appropriate commands.
- Database Core Operations: This includes core modules like db_ops, replication_ops, election_ops, command_line handling, and consensus_ops. These modules implement the actual database commands (CRUD operations, snapshots, replication, increment, etc.) and consensus/leader election.
- Storage Layer: Located in “src/lib/storage” (with submodules for disk and S3-based storage) and possibly “disk_ops” in addition to “memory repository” sections. These represent how the actual data is persisted either to disk or possibly S3.
- Monitoring and Configuration: The “monitoring.rs” and “configuration.rs” files manage the health of the system and the overall settings (like port numbers, replication addresses, timeout intervals, etc., as detailed in the README).
- External Tools and Connectors: The Docker configurations (Dockerfile, docker-compose.yml) and CI workflows indicate automated builds, testing, and deployment aspects.

##### Relationships and Data Flow
- Inside the processing pipeline, label that parsed requests are dispatched to “db_ops”, “replication_ops” or “election_ops”, depending on the command.
- Data flow from these modules to the storage layer. For example, a “set” operation should show data moving from the command processor to the memory repository and then persisting via “disk_ops” or “s3” modules.
- Also, include feedback loops indicating replication and consensus operations. For instance, the replication_ops module interacts with network modules (for joining other nodes) and storage (for maintaining consistency).

##### Architectural Patterns and Design Principles
- Modular Design: Separate concerns (network handling, request processing, core database logic, storage, and monitoring) that are clearly segregated in different folders.
- Command Pattern: The presence of a command_line directory suggests a modular design where each database command (create-db, use-db, set, snapshot, etc.) is self-contained and can be managed independently.
- Leaderless and Replication Model: Some modules like consensus_ops, election_ops, and replication_ops reveal that the architecture supports distributed consensus and leader election strategies.
- Safety and Scalability: The design details (like using Rust and providing configurable options via environment variables) indicate an emphasis on memory safety, performance, and future scalability.

##### Relevant Technologies and Frameworks
- Rust: The entire codebase is in Rust, as suggested by Cargo.toml and GitHub workflow files (e.g. rust.yml).
- Docker: The Dockerfile(s) and docker-compose are used for container deployment highlighting how the system can be packaged and run in production.
- CI/CD: GitHub workflows for testing and building suggest that the system is designed for robust deployment cycles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Clients["Frontend Clients"]:::frontend
    end

    %% Network Layer
    subgraph "Network Layer"
        HTTP["HTTP Connector (3013)"]:::network
        WS["WebSocket Connector (3012)"]:::network
        TCP["TCP Connector (3014)"]:::network
    end

    %% Request Processing Layer
    subgraph "Request Processing"
        ParseReq["Request Parser"]:::processing
        ProcReq["Request Dispatcher"]:::processing
    end

    %% Database Core Operations
    subgraph "Database Core Operations"
        CoreCmd["Core Commands"]:::database
        CLI["Command Line Interface"]:::database
        Consensus["Consensus Ops"]:::database
        Election["Election Ops"]:::database
        Replication["Replication Management"]:::database
    end

    %% Storage Layer
    subgraph "Storage Layer"
        StorageMod["Storage Modules (Disk & S3)"]:::storage
        DiskOps["Disk Operations"]:::storage
    end

    %% Monitoring & Configuration
    subgraph "Monitoring & Configuration"
        Monitoring["Monitoring"]:::monitoring
        Configuration["Configuration"]:::monitoring
    end

    %% External Tools and Connectors
    subgraph "External Tools & Connectors"
        Docker["Dockerfile"]:::external
        DockerCompose["Docker Compose"]:::external
        CICD["CI/CD Workflows"]:::external
    end

    %% Connections: Data Flow
    Clients -->|"sends request"| HTTP
    Clients -->|"sends request"| WS
    Clients -->|"sends request"| TCP

    HTTP -->|"forwards"| ParseReq
    WS -->|"forwards"| ParseReq
    TCP -->|"forwards"| ParseReq

    ParseReq -->|"parses"| ProcReq
    ProcReq -->|"dispatches"| CoreCmd
    ProcReq -->|"dispatches"| CLI
    ProcReq -->|"dispatches"| Consensus
    ProcReq -->|"dispatches"| Election
    ProcReq -->|"dispatches"| Replication

    CoreCmd -->|"executes operations"| StorageMod
    CLI -->|"executes command"| StorageMod
    Consensus -->|"triggers consensus"| Replication
    Election -->|"triggers leader election"| Replication

    Replication -->|"sync/update"| StorageMod
    Replication -->|"notifies"| HTTP
    Replication -->|"notifies"| WS
    Replication -->|"notifies"| TCP

    StorageMod -->|"persists data"| DiskOps

    %% Monitoring connections (observing database operations)
    CoreCmd ---|"monitors"| Monitoring
    CLI ---|"monitors"| Configuration

    %% External Tools orchestration (deployment and CI)
    Docker ---|"builds"| HTTP
    DockerCompose ---|"orchestrates"| TCP
    CICD ---|"tests/builds"| ProcReq

    %% Click Events for Component Mapping
    click Clients "https://github.com/mateusfreira/nun-db/tree/master/src/lib/client/"
    click HTTP "https://github.com/mateusfreira/nun-db/tree/master/src/lib/network/"
    click WS "https://github.com/mateusfreira/nun-db/tree/master/src/lib/network/"
    click TCP "https://github.com/mateusfreira/nun-db/tree/master/src/lib/network/"
    click ParseReq "https://github.com/mateusfreira/nun-db/blob/master/src/lib/parse_request.rs"
    click ProcReq "https://github.com/mateusfreira/nun-db/blob/master/src/lib/process_request.rs"
    click CoreCmd "https://github.com/mateusfreira/nun-db/blob/master/src/lib/db_ops.rs"
    click CLI "https://github.com/mateusfreira/nun-db/tree/master/src/lib/command_line/"
    click Consensus "https://github.com/mateusfreira/nun-db/blob/master/src/lib/consensus_ops.rs"
    click Election "https://github.com/mateusfreira/nun-db/blob/master/src/lib/election_ops.rs"
    click Replication "https://github.com/mateusfreira/nun-db/blob/master/src/lib/replication_ops.rs"
    click StorageMod "https://github.com/mateusfreira/nun-db/tree/master/src/lib/storage/"
    click DiskOps "https://github.com/mateusfreira/nun-db/blob/master/src/lib/disk_ops.rs"
    click Monitoring "https://github.com/mateusfreira/nun-db/blob/master/src/lib/monitoring.rs"
    click Configuration "https://github.com/mateusfreira/nun-db/blob/master/src/lib/configuration.rs"
    click Docker "https://github.com/mateusfreira/nun-db/tree/master/Dockerfile"
    click DockerCompose "https://github.com/mateusfreira/nun-db/blob/master/docker-compose.yml"
    click CICD "https://github.com/mateusfreira/nun-db/tree/master/.github/workflows/"

    %% Styles
    classDef frontend fill:#A8DADC,stroke:#1D3557,stroke-width:2px;
    classDef network fill:#457B9D,stroke:#1D3557,stroke-width:2px;
    classDef processing fill:#F4A261,stroke:#E76F51,stroke-width:2px;
    classDef database fill:#E9C46A,stroke:#264653,stroke-width:2px;
    classDef storage fill:#2A9D8F,stroke:#1B4332,stroke-width:2px;
    classDef monitoring fill:#E63946,stroke:#8D0801,stroke-width:2px;
    classDef external fill:#8ecae6,stroke:#023047,stroke-width:2px;
```
