# starwindv/wind-kvstore architecture

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

- Interactive diagram: https://gitdiagram.com/starwindv/wind-kvstore
- Repository: https://github.com/starwindv/wind-kvstore

## Overview

##### Project type and purpose
- This is an open-source, embeddable persistent key-value store engine written in Rust, packaged with:
- A command-line interactive shell (binary: shell)
- A network server exposing the store over TCP (binary: server)
- A Python SDK (under sdk/python) for remote or embedded use
- It emphasizes local persistence, crash-safe writes via WAL, memory-mapped I/O, LRU caching, and paged storage.

##### File structure
- Top-level files: Cargo.toml, build.rs, LICENSE, README.md, doc/ (detailed docs in English/Chinese)
- src/ directory:
- kvstore.rs – core storage engine (pages, WAL, cache, free-list, compression)
- config.rs – server configuration loader
- server.rs + server_main.rs – network service logic + entry point
- shell.rs + shell_main.rs – interactive CLI logic + entry point
- utils.rs – shared helper functions
- sdk/python/ directory:
- wind_kvstore package wrapping either network calls or FFI
- client.py, pool.py, auto.py – connection pooling, client interface
- sdk/test/python – examples and integration tests for the Python SDK

##### README for additional insights
- Describes core API (open, get, put, delete, compact, identifier, close)
- Features: WAL, LRU cache, paged storage, free page management, compression
- Guides linking to separate docs for shell and server

##### Detail
- Every module only if it adds clarity (e.g., config.rs as “Config Loader” inside Server)
- Flow of data for both reads and writes
- Crash recovery path via WAL
- Default parameters (page size, cache size) if space allows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        subgraph "CLI Shell (Rust Binary)" 
            ShellMain["shell_main.rs"]:::binary
            ShellLogic["shell.rs"]:::binary
        end
        subgraph "Python SDK" 
            SDKPackage["wind_kvstore package"]:::sdk
        end
    end

    %% Service
    subgraph "Network Service"
        subgraph "TCP Server (Rust Binary)"
            ServerMain["server_main.rs"]:::binary
            ServerLogic["server.rs"]:::binary
            ConfigLoader["Config Loader"]:::core
        end
    end

    %% Core Engine
    subgraph "Core KVStore Engine" 
        KVCore["KVStore Core (kvstore.rs)"]:::core
        Utils["Shared Utilities (utils.rs)"]:::core
    end

    %% Storage Subsystem
    subgraph "Storage Subsystem"
        WAL["WAL Manager"]:::storage
        Pager["Paged Storage Manager"]:::storage
        Cache["LRU Cache"]:::storage
        FreeList["Free-Page Manager"]:::storage
        Compress["Compression Module"]:::storage
    end

    %% Persistence
    Disk["Disk (data.db, WAL files)"]:::disk

    %% Python SDK Packaging & Tests
    subgraph "Python SDK Files"
        PYInit["__init__.py"]:::sdk
        PYBase["_base.py"]:::sdk
        PYAuto["auto.py"]:::sdk
        PYClient["client.py"]:::sdk
        PYPool["pool.py"]:::sdk
        PYUtils["utils.py"]:::sdk
        PYPyi["wind_kvcore.pyi"]:::sdk
        PyProject["pyproject.toml"]:::sdk
        Manifest["MANIFEST.in"]:::sdk
    end

    subgraph "SDK Tests & Examples"
        Test1["test.py"]:::sdk
        Test2["test_for_readme.py"]:::sdk
    end

    %% Relationships
    ShellLogic -->|uses| KVCore
    ShellMain -->|starts| ShellLogic
    SDKPackage -->|RPC over TCP| ServerLogic
    ServerMain -->|starts| ServerLogic
    ConfigLoader -->|provides config| ServerLogic
    ServerLogic -->|uses| KVCore
    KVCore -->|calls| Utils

    KVCore -->|write| WAL
    KVCore -->|read| Cache

    WAL --> Pager
    Cache --> Pager
    Pager --> FreeList
    Pager --> Compress
    Pager --> Disk

    Test1 -->|exercises| SDKPackage
    Test2 -->|exercises| SDKPackage

    %% Click Events
    click ShellLogic "https://github.com/starwindv/wind-kvstore/blob/main/src/shell.rs"
    click ShellMain "https://github.com/starwindv/wind-kvstore/blob/main/src/shell_main.rs"
    click ServerLogic "https://github.com/starwindv/wind-kvstore/blob/main/src/server.rs"
    click ServerMain "https://github.com/starwindv/wind-kvstore/blob/main/src/server_main.rs"
    click ConfigLoader "https://github.com/starwindv/wind-kvstore/blob/main/src/config.rs"
    click Utils "https://github.com/starwindv/wind-kvstore/blob/main/src/utils.rs"
    click KVCore "https://github.com/starwindv/wind-kvstore/blob/main/src/kvstore.rs"
    click PYInit "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/src/wind_kvstore/__init__.py"
    click PYBase "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/src/wind_kvstore/_base.py"
    click PYAuto "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/src/wind_kvstore/auto.py"
    click PYClient "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/src/wind_kvstore/client.py"
    click PYPool "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/src/wind_kvstore/pool.py"
    click PYUtils "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/src/wind_kvstore/utils.py"
    click PYPyi "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/src/wind_kvstore/wind_kvcore.pyi"
    click PyProject "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/pyproject.toml"
    click Manifest "https://github.com/starwindv/wind-kvstore/blob/main/sdk/python/MANIFEST.in"
    click Test1 "https://github.com/starwindv/wind-kvstore/blob/main/sdk/test/python/test.py"
    click Test2 "https://github.com/starwindv/wind-kvstore/blob/main/sdk/test/python/test_for_readme.py"

    %% Styles
    classDef binary fill:#ADD8E6,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef storage fill:#FFA500,stroke:#000;
    classDef sdk fill:#DDA0DD,stroke:#000;
    classDef disk fill:#DDDDDD,stroke:#000,stroke-dasharray: 5 5;
```
