# chenneking/cloud-database architecture

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

- Interactive diagram: https://gitdiagram.com/chenneking/cloud-database
- Repository: https://github.com/chenneking/cloud-database

## Overview

##### Project Type and Purpose
- The project is a distributed key-value storage system with three main components: a KV-Client, one or multiple KV-Servers (nodes), and an ECS-Server that orchestrates the system.
- The README highlights that the client connects to a server for data operations while the ECS-Server manages node registration, failure handling, and consistent hashing for key-range assignment.

##### Analyzing the File Structure
- You have three major modules/directories:
– ecs-server: Contains orchestration logic, key classes for server communication and message handling.
– kv-server: Contains storage logic, client request handling, communication modules, caching (FIFO, LFU, LRU), and persistent storage management.
– kv-client: Contains the client-side interface to send commands and interact with the key-value store.
- There is also a key-gen module which might provide functionality related to generating key files or assisting with the consistent hashing process.
- The presence of pom.xml files across modules indicates that each component is built as its own Maven project. Dockerfiles for each component (and a top-level run.sh) suggest containerization and deployment support.

##### Key Architectural Components
- KV-Client:
– Acts as the user-facing or command-side component.
– It connects to KV-Servers, sends commands, and may be redirected as necessary.
- KV-Server:
– Represents a node holding a subset of the key-value pairs.
– Contains sub-modules for client communication, request processing, caching strategies (FIFO, LFU, LRU), and storage (persistent and multithreaded persistence).
- ECS-Server:
– Handles orchestration of the distributed system, such as node initiation, assignment of key ranges using consistent hashing, and failure or dynamic scaling management.
- External Supporting Components:
– Key-Generation utility may play a role in setting up initial configurations or keys.
– The PDF report in the “report” directory provides in-depth explanations but is outside the code’s runtime architecture. Still, you may note that the architecture leans heavily on distributed load balancing concepts.

##### Relationships and Interactions
- The ECS-Server employs consistent hashing to determine key ranges; illustrate this by a sub-component within ECS or call out “Consistent Hashing algorithm” as a design decision linking it to both KV-Servers and KV-Client.
- Optionally, indicate that KV-Servers may interact with a local storage mechanism (including caching layers and persistent storage threads).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        KV_CLIENT["KV-Client"]:::client
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        E_CORE["ECS-Server Core"]:::orchestration
        E_COMM["ECS Communication"]:::orchestration
        E_MSG["ECS Message Handler"]:::orchestration
        E_HASH["Consistent Hashing"]:::orchestration
    end

    %% Data Nodes Layer
    subgraph "Data Nodes"
        subgraph "KV-Server Node"
            KS_CORE["KV-Server Core"]:::server
            KS_COMM["Communication Module"]:::server
            KS_STORE["Storage Module"]:::server
            KS_CACHE["Caching Strategy"]:::server
            KS_PERSIST["Persistent Storage"]:::server
        end
    end

    %% Utility Components
    subgraph "Utilities"
        KEYGEN["Key-Generation Utility"]:::utility
        DOC["Documentation/Report"]:::document
    end

    %% Relationships
    KV_CLIENT -->|"sendsCommands"| KS_COMM
    KS_COMM -->|"respondsTo"| KV_CLIENT

    E_CORE -->|"manages"| KS_CORE
    E_HASH -->|"assignsKeyRanges"| KS_CORE

    KEYGEN -->|"providesKeysTo"| E_HASH
    KEYGEN -->|"assists"| KS_CORE

    %% Click Events
    click KV_CLIENT "https://github.com/chenneking/cloud-database/blob/main/kv-client/src/main/java/org/praktikum/Client.java"
    click KS_CORE "https://github.com/chenneking/cloud-database/blob/main/kv-server/src/main/java/org/praktikum/KVServer.java"
    click KS_COMM "https://github.com/chenneking/cloud-database/tree/main/kv-server/src/main/java/org/praktikum/communication"
    click KS_STORE "https://github.com/chenneking/cloud-database/tree/main/kv-server/src/main/java/org/praktikum/storage"
    click KS_CACHE "https://github.com/chenneking/cloud-database/tree/main/kv-server/src/main/java/org/praktikum/storage/cache"
    click E_CORE "https://github.com/chenneking/cloud-database/blob/main/ecs-server/src/main/java/org/praktikum/ECSServer.java"
    click E_COMM "https://github.com/chenneking/cloud-database/blob/main/ecs-server/src/main/java/org/praktikum/ECSCommunication.java"
    click E_MSG "https://github.com/chenneking/cloud-database/blob/main/ecs-server/src/main/java/org/praktikum/ECSMessageHandler.java"
    click E_HASH "https://github.com/chenneking/cloud-database/blob/main/key-gen/src/main/java/ConsistentHashing.java"
    click KEYGEN "https://github.com/chenneking/cloud-database/blob/main/key-gen/src/main/java/Generator.java"
    click DOC "https://github.com/chenneking/cloud-database/tree/main/report"

    %% Styles
    classDef client fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef orchestration fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef server fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef utility fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef document fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
```
