# shihuili1218/klein architecture

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

- Interactive diagram: https://gitdiagram.com/shihuili1218/klein
- Repository: https://github.com/shihuili1218/klein

## Overview

##### Project type and purpose
- Klein is not a web or mobile app but a modular, Java-based, distributed tool library implementing consistent data structures (Cache, Lock, Map, List, Queue) on top of Paxos consensus. It provides pluggable subsystems (RPC, Serialization, Consensus, Storage) to replace middleware like Redis or messaging queues.
- The README confirms Klein’s goal: “a distributed collection tool library based on Paxos... keep data consistent across members without relying on any middleware.”

##### File structure
- Top-level pom.xml, plus Maven modules under the root:
- klein-common: shared utilities (Disruptor, timers, threading, exceptions).
- klein-spi: extension-point loader (Java SPI).
- klein-core: public API (Klein.startup(), createCache(), createLock(), KleinProp) and runtime orchestration.
- klein-rpc-facade & klein-rpc-grpc: RPC interface and gRPC implementation.
- klein-consensus-facade & klein-consensus-paxos: consensus interface and Paxos implementation.
- klein-serializer-facade & bindings (hessian2, protobuf): serialization interface and implementations.
- klein-storage-facade & implementations (file, H2): storage interface (log, snapshot) and back ends.
- klein-example: sample applications illustrating usage.
- klein-jepsen: Jepsen test harness with Docker configurations.
- Configuration files: checkstyle.xml, .github/workflows, Docker templates, Maven POMs.

##### README for additional insights
- Quick Start shows how client code interacts with Klein API, how to set properties via System.setProperty or KleinProp.

##### Elements
- Clear labels for each Maven module or runtime component
- From Client → Core → SPI → each Facade
- From Consensus → RPC → Network
- From Consensus → Storage
- From RPC → Serializer
- Facade interfaces in another
- Implementations (gRPC, Paxos, Hessian2, File/H2) in a third
- External network/peers in a different style

– “RPC Facade”
– “Consensus Facade”
– “Serializer Facade”
– “Storage Facade”
– RPC Facade → “gRPC Impl”
– Consensus Facade → “Paxos Impl”
– Serializer Facade → “Hessian2 / Protobuf Impl”
– Storage Facade → “File / H2 Storage Impl”
8) Optionally, include a bottom area for “Jepsen Test Harness” interacting with multiple Dockerized Klein nodes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Application"]:::external
    click Client "https://github.com/shihuili1218/klein/tree/main/klein-example/src/main/java/com/ofcoder/klein/example"

    subgraph "Core API Module"
        KleinCore["Klein.java"]:::api
        click KleinCore "https://github.com/shihuili1218/klein/blob/main/klein-core/src/main/java/com/ofcoder/klein/Klein.java"
        KleinProp["KleinProp.java"]:::api
        click KleinProp "https://github.com/shihuili1218/klein/blob/main/klein-core/src/main/java/com/ofcoder/klein/KleinProp.java"
        Runtime["Runtime & Collections"]:::api
        click Runtime "https://github.com/shihuili1218/klein/tree/main/klein-core/src/main/java/com/ofcoder/klein/core"
    end

    SPI["SPI Loader"]:::spi
    click SPI "https://github.com/shihuili1218/klein/tree/main/klein-spi/src/main/java/com/ofcoder/klein/spi"

    Common["Common Utilities"]:::util
    click Common "https://github.com/shihuili1218/klein/tree/main/klein-common/src/main/java/com/ofcoder/klein/common"

    subgraph "Facades"
        RPCF["RPC Facade"]:::facade
        click RPCF "https://github.com/shihuili1218/klein/tree/main/klein-rpc/klein-rpc-facade/src/main/java/com/ofcoder/klein/rpc/facade"
        ConsF["Consensus Facade"]:::facade
        click ConsF "https://github.com/shihuili1218/klein/tree/main/klein-consensus/klein-consensus-facade/src/main/java/com/ofcoder/klein/consensus/facade"
        SerF["Serializer Facade"]:::facade
        click SerF "https://github.com/shihuili1218/klein/tree/main/klein-serializer/klein-serializer-facade/src/main/java/com/ofcoder/klein/serializer"
        StorF["Storage Facade"]:::facade
        click StorF "https://github.com/shihuili1218/klein/tree/main/klein-storage/klein-storage-facade/src/main/java/com/ofcoder/klein/storage/facade"
    end

    subgraph "Implementations"
        gRPC["gRPC Implementation"]:::impl
        click gRPC "https://github.com/shihuili1218/klein/tree/main/klein-rpc/klein-rpc-grpc/src/main/java/com/ofcoder/klein/rpc/grpc"
        Paxos["Paxos Implementation"]:::impl
        click Paxos "https://github.com/shihuili1218/klein/tree/main/klein-consensus/klein-consensus-paxos/src/main/java/com/ofcoder/klein/consensus/paxos"
        Hessian2["Hessian2 Serializer"]:::impl
        click Hessian2 "https://github.com/shihuili1218/klein/tree/main/klein-serializer/klein-serializer-hessian2/src/main/java/com/ofcoder/klein/serializer/hessian2"
        Protobuf["Protobuf Serializer"]:::impl
        click Protobuf "https://github.com/shihuili1218/klein/tree/main/klein-serializer/klein-serializer-protobuf/src/main/java/com/ofcoder/klein/serializer/protobuf"
        FileStore["File Storage"]:::impl
        click FileStore "https://github.com/shihuili1218/klein/tree/main/klein-storage/klein-storage-file/src/main/java/com/ofcoder/klein/storage/file"
        H2Store["H2 Storage"]:::impl
        click H2Store "https://github.com/shihuili1218/klein/tree/main/klein-storage/klein-storage-h2/src/main/java/com/ofcoder/klein/storage/h2"
    end

    Client --> KleinCore
    KleinCore --> KleinProp
    KleinCore --> Runtime
    KleinCore --> SPI
    Common --> KleinCore
    Common --> SPI

    SPI --> RPCF
    SPI --> ConsF
    SPI --> SerF
    SPI --> StorF

    RPCF --> gRPC
    ConsF --> Paxos
    SerF --> Hessian2
    SerF --> Protobuf
    StorF --> FileStore
    StorF --> H2Store

    subgraph "Klein Cluster"
        subgraph "Node1"
            gRPC1["gRPC Implementation"]:::impl
        end
        subgraph "Node2"
            gRPC2["gRPC Implementation"]:::impl
        end
    end

    gRPC --> gRPC1
    gRPC --> gRPC2
    gRPC1 -->|"Network"| gRPC2

    Jepsen["Jepsen Test Harness"]:::external
    click Jepsen "https://github.com/shihuili1218/klein/tree/main/klein-jepsen/docker"
    Jepsen --> gRPC1
    Jepsen --> gRPC2

    classDef api fill:#D6EAF8,stroke:#3498DB,color:#154360;
    classDef spi fill:#EBDEF0,stroke:#9B59B6,color:#4A235A;
    classDef facade fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
    classDef impl fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef util fill:#FADBD8,stroke:#E74C3C,color:#641E16;
    classDef external fill:#F2F3F4,stroke:#95A5A6,color:#566573;
```
