# gengruizhang/cabinet architecture

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

- Interactive diagram: https://gitdiagram.com/gengruizhang/cabinet
- Repository: https://github.com/gengruizhang/cabinet

## Overview

##### Project type and purpose
- This is a Go-based distributed consensus system called “Cabinet.”
- It implements a leader-based, weighted consensus protocol (an alternative to Raft/Paxos).
- It also includes an integrated benchmarking framework (TPC-C and YCSB workloads) and optional MongoDB storage.

##### File structure
Top-level modules:
- main.go           – entry point, parameter parsing, bootstraps leader or follower
- config/           – cluster configuration (.conf files) and parsing logic (config.go)
- consensus.go      – core consensus routines (leader election, log replication)
- primary.go        – leader logic
- conns.go          – network connection management
- smr/              – state machine replication support (state.go, priority.go, pmgr.go)
- mongodb/          – optional MongoDB client for persistence (leader & follower modes)
- tpcc/             – TPC-C benchmark implementation and driver
- ycsb/             – YCSB benchmark integration (data generation, workload scripts)
- eval/             – metrics, meters and measurement utilities
- scripts/          – shell/python scripts for deployment, latency injection, initialization

##### Key insights from README
- Weighted consensus with dynamic node weights
- Leader/follower roles: ID=0 is always the leader, others are followers
- Benchmarks (YCSB, TPC-C) plug into the same framework
- Runs locally or across machines via the config folder
- Metrics are collected under /eval and /tpcc/measurement

##### Main components
A. Client layer
- Benchmark clients: TPCC driver, YCSB loader
- Management scripts (initialization, add_latency, killall…)
B. Consensus cluster
- Leader node (primary.go, consensus.go)
- Follower nodes
- Network layer (conns.go)
C. State machine replication (smr/)
- Priority manager (selects high-weight nodes)
- State machine (applies commands)
D. Persistence layer (optional)
- MongoDB client (mongodb/)
- Local logs (if –pd)
E. Metrics & evaluation
- eval/meters.go
- tpcc/measurement/…

##### Relationships and data flow
1. Benchmark client issues workload requests → connects to leader’s API port
2. Leader receives transaction proposal → consensus.go
3. Leader sends proposals to a quorum of followers → conns.go
4. Followers respond (ACKs) → leader collects until weight quorum is reached
5. Leader commits entry → applies to state machine (smr/state.go)
6. If using MongoDB, state machine writes to MongoDB
7. Metrics emitted to eval and tpcc/measurement modules
8. Client receives confirmation

##### Architectural patterns and design principles
- Leader/follower pattern (a single leader, multiple followers)
- Weighted quorum (dynamic weights, smaller quorum for faster consensus)
- Modular benchmark framework (pluggable YCSB and TPC-C drivers)
- Clean separation: consensus core vs. storage vs. benchmarking

##### Technologies and frameworks
- Go modules (go.mod, go.sum)
- MongoDB Go driver
- Shell/Python scripts for orchestration
- TPCC & YCSB standards for benchmarking

##### Putting it all together
- On the left: “Benchmark Clients” (TPC-C, YCSB)
- Below: “Followers” (×N) with the same sub-modules
- On the right: “MongoDB Persistence” (optional)
- At the bottom: “Metrics & Evaluation” (eval/, tpcc/measurement/)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Benchmark Clients
    subgraph "Benchmark Clients"
        TPCC["TPC-C Driver"]:::benchmark
        YCSB["YCSB Loader"]:::benchmark
        Scripts["Management Scripts"]:::script
    end

    %% Consensus Cluster
    subgraph "Consensus Cluster"
        subgraph "Leader Node"
            Main["Entry Point & Bootstrap"]:::bootstrap
            Config["Cluster Configuration"]:::config
            Consensus["Consensus Core"]:::consensus
            Primary["Leader Logic"]:::consensus
            subgraph "State Machine Replication"
                SMR_State["State Machine"]:::consensus
                SMR_Priority["Priority Manager"]:::consensus
                SMR_Pmgr["Priority Manager"]:::consensus
            end
            Conns["Network Layer"]:::network
        end

        subgraph "Followers"
            Follower["Follower Node"]:::consensus
        end
    end

    %% Persistence Layer
    subgraph "Persistence (Optional)"
        MongoDB["MongoDB Client"]:::storage
        LocalLogs["Local Logs"]:::storage
    end

    %% Metrics & Evaluation
    subgraph "Metrics & Evaluation"
        Eval["Metrics Framework"]:::metrics
        TPCC_Measure["TPC-C Measurement"]:::metrics
    end

    %% Data Flow
    TPCC -->|"issues workload"| Main
    YCSB -->|"issues workload"| Main
    Scripts -->|"bootstrap cluster"| Main
    Main -->|"propose transaction"| Consensus
    Consensus -->|"send proposal"| Follower
    Follower -->|"ACK"| Consensus
    Consensus -->|"commit entry"| SMR_State
    SMR_State -->|"apply command"| MongoDB
    SMR_State -->|"append log"| LocalLogs
    SMR_State -->|"emit metrics"| Eval
    Eval -->|"report metrics"| TPCC
    Eval -->|"report metrics"| YCSB

    %% Click Events
    click TPCC "https://github.com/gengruizhang/cabinet/blob/main/tpcc/tpcc.go"
    click YCSB "https://github.com/gengruizhang/cabinet/blob/main/ycsb/scripts/genData.sh"
    click Scripts "https://github.com/gengruizhang/cabinet/blob/main/scripts/initialization.sh"
    click Main "https://github.com/gengruizhang/cabinet/blob/main/main.go"
    click Config "https://github.com/gengruizhang/cabinet/blob/main/config/config.go"
    click Consensus "https://github.com/gengruizhang/cabinet/blob/main/consensus.go"
    click Primary "https://github.com/gengruizhang/cabinet/blob/main/primary.go"
    click SMR_State "https://github.com/gengruizhang/cabinet/blob/main/smr/state.go"
    click SMR_Priority "https://github.com/gengruizhang/cabinet/blob/main/smr/priority.go"
    click SMR_Pmgr "https://github.com/gengruizhang/cabinet/blob/main/smr/pmgr.go"
    click Conns "https://github.com/gengruizhang/cabinet/blob/main/conns.go"
    click MongoDB "https://github.com/gengruizhang/cabinet/blob/main/mongodb/mgdb_main.go"
    click Eval "https://github.com/gengruizhang/cabinet/blob/main/eval/meters.go"
    click TPCC_Measure "https://github.com/gengruizhang/cabinet/blob/main/tpcc/measurement/measure.go"

    %% Styles
    classDef benchmark fill:#9f6,stroke:#393,stroke-width:1px
    classDef script fill:#bbb,stroke:#777,stroke-width:1px
    classDef bootstrap fill:#a52,stroke:#832,stroke-width:1px
    classDef config fill:#4aa,stroke:#277,stroke-width:1px
    classDef consensus fill:#6ac,stroke:#159,stroke-width:1px
    classDef network fill:#6cf,stroke:#39a,stroke-width:1px
    classDef storage fill:#f96,stroke:#d63,stroke-width:1px
    classDef metrics fill:#c6f,stroke:#93a,stroke-width:1px
```
