# mpwsh/smol-kv architecture

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

- Interactive diagram: https://gitdiagram.com/mpwsh/smol-kv
- Repository: https://github.com/mpwsh/smol-kv

## Overview

##### Main Components
- HTTP Server Component: Represent the actix-web server that listens on a configurable port (default port 5050) and provides the REST API interfaces. This is driven by the main.rs and supported by various route handlers (e.g., auth.rs, collection.rs, middleware.rs).
▸ Collection management (collection.rs)
▸ Key-value operations (key.rs, sub.rs)
▸ Middleware (middleware.rs) for handling authentication (the “X-SECRET-KEY” header) and possibly logging or error handling (error.rs)
- Storage Layer: Denote RocksDB as the underlying storage engine. Indicate that this component is connected to the API endpoint for actual persistence. You might also note that an sst.rs module is likely involved in reading/writing SST files for backups.
- Auxiliary/Utility Components: Include supporting modules such as:
▸ Benchmark support (benchmark folder) for performance testing.
▸ Scripts and Dockerfiles for deployment and binary size stripping (e.g., scripts/strip-bins.sh).
▸ CI configuration (GitHub workflows) to show continuous integration and build configuration.

##### Relationships and Interactions
- Auth/Middleware Layer: Inside the server, requests pass through middleware (e.g., authentication and logging) before hitting the route handlers.
- API Routing: Break out the main route handlers for:
▸ Collection CRUD operations (create collections, add a key, update or delete key, list keys/values).
▸ Batch operations and JSONPath querying.
▸ Backup and restore operations.
- Event/Subscription Mechanism: Show a connection path for real-time event notifications (subscribe endpoint) that feeds back to clients.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Emphasize that the project separates HTTP request handling, business logic, and data storage.
- Modularity: Represent each module (for example, separate files in the src directory such as auth.rs, collection.rs, etc.) as distinct pieces loosely coupled by well-defined interfaces.
- Containerization and CI/CD: Include elements that denote deployment readiness (Dockerfile, GitHub workflows) and environment configuration via environment variables.

##### Relevant Technologies and Frameworks
- Rust as the primary programming language.
- actix-web for the HTTP server.
- RocksDB for persistent storage (with additional interfaces available via a RocksDB client).
- Docker for containerizing the application, with environment configuration influencing the server’s behavior.
- CI setup using GitHub Actions (as seen in .github/workflows) for automated testing and dockerization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Client("Client (HTTP Request)"):::client
    end

    subgraph "Server Layer"
        HT_Server("HTTP Server (actix-web)"):::server
        Auth("Auth Module"):::middleware
        Middleware("Middleware"):::middleware
        ErrorHandler("Error Handler"):::middleware
        ColMgmt("Collection Management"):::api
        KeyOps("Key Operations"):::api
        SubOps("Sub Operations"):::api
        Batch("Batch Operations & JSONPath"):::api
        EventSub("Event Subscription"):::api
        Backup("Backup/Restore"):::api
    end

    subgraph "Storage Layer"
        Storage("RocksDB Storage"):::storage
    end

    subgraph "Auxiliary Components"
        subgraph "Benchmark & Testing"
            BenchDir("Benchmark Directory"):::aux
            BenchModule("Benchmark Module"):::aux
        end
        subgraph "Containerization & Deployment"
            Docker("Dockerfile"):::deploy
            DockerRel("fromRel.Dockerfile"):::deploy
            DockerMusl("musl.Dockerfile"):::deploy
            StripBins("Strip Binaries Script"):::deploy
        end
        CI("CI/CD Pipelines"):::ci
    end

    %% Relationships
    Client -->|"HTTP_Request"| HT_Server

    HT_Server -->|"auth:X-SECRET-KEY"| Auth
    HT_Server --> Middleware
    HT_Server --> ErrorHandler
    HT_Server --> ColMgmt
    HT_Server --> KeyOps
    HT_Server --> SubOps
    HT_Server --> Batch
    HT_Server --> EventSub
    HT_Server --> Backup

    ColMgmt -->|"CRUD"| Storage
    KeyOps -->|"Read/Write"| Storage
    SubOps -->|"Read/Write"| Storage
    Batch -->|"BatchOps"| Storage
    Backup -->|"Backup/Restore"| Storage

    EventSub -->|"Event_Streaming"| Client

    %% Auxiliary connections (dashed for non-runtime dependencies)
    HT_Server ---|"Performance_Test"| BenchDir
    HT_Server ---|"Performance_Test"| BenchModule

    CI ---|"Pipeline"| Docker
    CI --- DockerRel
    CI --- DockerMusl
    CI --- StripBins

    Docker ---|"Deploys"| HT_Server
    DockerRel --- HT_Server
    DockerMusl --- HT_Server
    StripBins --- HT_Server

    %% Click Events
    click HT_Server "https://github.com/mpwsh/smol-kv/blob/main/src/main.rs"
    click ColMgmt "https://github.com/mpwsh/smol-kv/blob/main/src/collection.rs"
    click KeyOps "https://github.com/mpwsh/smol-kv/blob/main/src/key.rs"
    click SubOps "https://github.com/mpwsh/smol-kv/blob/main/src/sub.rs"
    click Auth "https://github.com/mpwsh/smol-kv/blob/main/src/auth.rs"
    click Middleware "https://github.com/mpwsh/smol-kv/blob/main/src/middleware.rs"
    click ErrorHandler "https://github.com/mpwsh/smol-kv/blob/main/src/error.rs"
    click Backup "https://github.com/mpwsh/smol-kv/blob/main/src/sst.rs"
    click BenchDir "https://github.com/mpwsh/smol-kv/tree/main/benchmark"
    click BenchModule "https://github.com/mpwsh/smol-kv/blob/main/src/benchmark.rs"
    click Docker "https://github.com/mpwsh/smol-kv/tree/main/Dockerfile"
    click DockerRel "https://github.com/mpwsh/smol-kv/blob/main/fromRel.Dockerfile"
    click DockerMusl "https://github.com/mpwsh/smol-kv/blob/main/musl.Dockerfile"
    click StripBins "https://github.com/mpwsh/smol-kv/blob/main/scripts/strip-bins.sh"
    click CI "https://github.com/mpwsh/smol-kv/tree/main/.github/workflows"

    %% Styles
    classDef server fill:#fceabb,stroke:#333,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef storage fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef middleware fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef aux fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef deploy fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef ci fill:#ffeeba,stroke:#333,stroke-width:2px;
    classDef client fill:#d0e6f6,stroke:#333,stroke-width:2px;
```
