# sabledb-io/sabledb architecture

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

- Interactive diagram: https://gitdiagram.com/sabledb-io/sabledb
- Repository: https://github.com/sabledb-io/sabledb

## Overview

##### Main Components
- Core Library (libsabledb): This is the backbone of SableDB, encapsulating modules such as:
- Commands: Handling various command sets (base, client, server, locking, transactions, etc.)
- I/O & Network: Managing file output, RESP protocol writing, TLS connectivity, and transport.
- Metadata: Managing key metadata, expiration, and encoding.
- Replication: Modules for client/server replication, transaction log tailing, cluster management and storage updates.
- Storage: Abstractions for RocksDB integration with specialized databases for strings, hashes, lists, etc.
- Utility Modules: Supporting file operations, pattern matching, request parsing, and monitoring (ticker, stopwatch).
- Server Binary (sabledb): The entry point for starting the database server (main.rs) that integrates the core functionalities.
- Client & Admin Tools (sdb-cli and sdb-admin): These command line binaries provide interfaces for interacting with and administrating the database.
- Docker & Deployment: Dockerfile, docker-compose.yaml, and related scripts facilitate containerization and deployment.

##### Relationships & Interactions
- The Server (sabledb) uses libsabledb to handle incoming requests (via its net module) and routes commands to appropriate handlers in the commands module.
- The I/O/Network layer processes client connections (supporting TLS from ssl files) and communicates using the RESP protocol.
- The Storage layer, which wraps around RocksDB, interacts with command handlers to persist and retrieve data.
- The Metadata and Replication modules work alongside the storage engine to ensure data consistency, transactional support, and replication across nodes.
- CLI tools (sdb-cli) and admin utilities (sdb-admin) interface with the server using the defined protocol to issue commands and manage the cluster.
- Docker configuration and CI/CD workflows (in .github/workflows) coordinate builds, tests, and deployment, ensuring consistency across environments.

##### Architectural Patterns & Principles
- Modularity: The project is well separated into many modules (commands, storage, replication, etc.), enabling high cohesion within components.
- Layered Design: There’s a clear separation between networking, command processing, storage, and replication.
- Extensibility: With support for multiple command types and a wide array of protocols, the design embraces extension points (e.g., additional commands or storage backends).
- Asynchronous & Concurrent Programming: Integration of asynchronous operations, especially in networking and replication layers (inspired by Tokio), suggests clear concurrency management.

##### Relevant Technologies & Frameworks
- Rust as the programming language.
- Cargo for package management and project building.
- RocksDB as the storage engine.
- TLS support (evidenced by the ssl directory and net/tls module).
- Docker for containerization.
- CI/CD workflows shown via GitHub Actions.
- Benchmarking tools (sb) to test performance.

- Since SableDB is primarily a backend database service, emphasize critical boundaries:
- Separate the “Client Layer” (sdb-cli, sdb-admin, and external connections) from the “Server Core” (sabledb binary).
- Data flow: from client request to network layer, command parsing, metadata/replication handling and storage interaction.

##### Detailing Additional Architectural Elements
- Error handling and concurrency aspects in server modules.
- Possibly include a separate layer or note for testing (integration tests in libsabledb/src/integtests) to show how the system is validated.
- Configuration elements (server.ini, build scripts) that allow flexible deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    sdbcli["sdb-cli"]:::client
    sdbadmin["sdb-admin"]:::client

    %% Server Layer
    sabledb["SableDB Server"]:::server

    %% Deployment and CI/CD
    deploy["Docker & Deployment"]:::deployment
    cicd["CI/CD Workflows"]:::deployment
    tlsCerts["TLS Certificates"]:::deployment

    %% Core Library Subgraph
    subgraph "Core Library (libsabledb)"
        libCore["Core Library"]:::core
        cmd["Commands"]:::core
        io["I/O"]:::networking
        nettls["Network & TLS"]:::networking
        metadata["Metadata"]:::core
        replication["Replication"]:::core
        storage["Storage"]:::core
        utils["Utility Modules"]:::core
        rocksdb["RocksDB Storage Engine"]:::core
    end

    %% Connections from Clients to Server
    sdbcli -->|"sends_request"| sabledb
    sdbadmin -->|"issues_commands"| sabledb

    %% Server uses Core Library
    sabledb -->|"uses"| libCore

    %% Core Library internal connections
    libCore --> cmd
    libCore --> io
    libCore --> nettls
    libCore --> metadata
    libCore --> replication
    libCore --> storage
    libCore --> utils

    %% TLS Integration
    nettls -->|"handles_TLS"| tlsCerts

    %% Command module interactions
    cmd -->|"persistes_data"| storage
    cmd -->|"initiates_replication"| replication
    cmd -->|"updates_metadata"| metadata
    utils -->|"supports"| cmd

    %% Storage integration
    storage -->|"integrates"| rocksdb

    %% Deployment and CI/CD connections
    deploy -->|"deploys_to"| sabledb
    cicd -->|"triggers_deployment"| deploy

    %% Styles
    classDef core fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef networking fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef client fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef server fill:#F5CBA7,stroke:#BA4A00,stroke-width:2px;
    classDef deployment fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click libCore "https://github.com/sabledb-io/sabledb/tree/main/libsabledb/"
    click cmd "https://github.com/sabledb-io/sabledb/tree/main/libsabledb/src/commands/"
    click io "https://github.com/sabledb-io/sabledb/tree/main/libsabledb/src/io/"
    click nettls "https://github.com/sabledb-io/sabledb/blob/main/libsabledb/src/net/tls.rs"
    click metadata "https://github.com/sabledb-io/sabledb/tree/main/libsabledb/src/metadata/"
    click replication "https://github.com/sabledb-io/sabledb/tree/main/libsabledb/src/replication/"
    click storage "https://github.com/sabledb-io/sabledb/tree/main/libsabledb/src/storage/"
    click utils "https://github.com/sabledb-io/sabledb/tree/main/libsabledb/src/utils/"
    click sabledb "https://github.com/sabledb-io/sabledb/blob/main/sabledb/src/main.rs"
    click sdbcli "https://github.com/sabledb-io/sabledb/blob/main/sdb-cli/src/main.rs"
    click sdbadmin "https://github.com/sabledb-io/sabledb/blob/main/sdb-admin/src/main.rs"
    click deploy "https://github.com/sabledb-io/sabledb/tree/main/scripts/"
    click cicd "https://github.com/sabledb-io/sabledb/tree/main/.github/workflows/"
    click tlsCerts "https://github.com/sabledb-io/sabledb/tree/main/ssl/"
```
