# hrs05/key-value-store-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/hrs05/key-value-store-v2
- Repository: https://github.com/hrs05/key-value-store-v2

## Overview

##### Project Type and Purpose
- This is a modular, full-stack key-value store application built with core Java, Spring Boot, gRPC, and REST.
- The “key.value” module implements the server side (in-memory store, TTL eviction, APIs), “common” holds shared Protocol Buffer definitions, and “client” provides a Java SDK (gRPC and REST) for consumers.

##### File-Structure Analysis
- Top-level pom.xml orchestrates three submodules: common, key.value, and client.
- common/src/main/proto/common.proto: shared message definitions.
- key.value/src/main/java/com/hrs/key/value: Spring Boot application, API packages (HandlerAPI, MasterAPI), data layer (KeyValueDataHandler, KeyValueDataMaster), handler layer, DTOs, TTL scheduler, configuration beans.
- client/src/main/java/com/proto/client: Spring Boot–based SDK, gRPC stubs, exception handling, service wrapper.
- asset/kv2ttl.jpg shows a TTL eviction sequence.

##### README Insights
- Version 2 adds: virtual threads (Java 21), Spring Boot integration, gRPC SDK, REST API support, pure-Java in-memory store, SAAS-style best practices.

##### Main Components
a. Client Application
- Java application using Client SDK
- Exposes high-level KeyValueApi calls
b. Client SDK (“client” module)
- gRPC stub + REST template
- KeyValueClientService
c. Network/API Layer on Server
- gRPC server endpoints (HandlerAPI, MasterAPI)
- REST controllers (mapped in Spring Boot)
d. Core Service Layer
- KeyValueService implementing business logic
e. Data Layer
- KeyValueDataHandler (per-key operations)
- KeyValueDataMaster (coordination, concurrency)
- In-memory data store (e.g., ConcurrentHashMap)
f. TTL Scheduler
- TTLScheduler (virtual threads scheduling eviction)
g. Shared Definitions
- common.proto messages and service definitions

##### Relationships & Interactions
- Client → (gRPC / HTTP) → Server API Layer → Service Layer → Data Layer → In-Memory Store
- TTL Scheduler → In-Memory Store (trigger expire/delete)
- common.proto binds client and server message formats

##### Architectural Patterns & Technologies
- Layered architecture (API → Service → Data)
- Spring Boot for auto-configuration, dependency injection
- Virtual threads (JDK 21) for high-concurrency scheduling
- gRPC for binary RPC, REST for HTTP compatibility
- Maven multi-module for code reuse (common, client, server)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        CA["Client Application\n(Spring Boot)"]:::client
        subgraph "Client SDK"
            KVApi["KeyValueApi"]:::client
            KVClientService["KeyValueClientService"]:::client
            KVSdkStub["gRPC stub"]:::client
            RESTSdk["REST template"]:::client
            KVModel["KeyValue (model)"]:::client
            KVException["KeyValueException"]:::client
        end
    end

    %% Shared Definitions
    common["common.proto"]:::common

    %% Server Side
    subgraph "Server Side"
        App["Application"]:::server
        subgraph "API Layer"
            Handler["HandlerAPI (gRPC/REST)"]:::api
            Master["MasterAPI (gRPC/REST)"]:::api
        end
        subgraph "Service Layer"
            KVService["KeyValueService"]:::service
        end
        subgraph "Data Layer"
            DataHandler["KeyValueDataHandler"]:::data
            DataMaster["KeyValueDataMaster"]:::data
            Store["In-Memory Store\n(ConcurrentHashMap)"]:::db
        end
        TTL["TTLSchedular\n(Virtual Threads)"]:::ttl
        ConfigBean["KeyValueMasterBean"]:::config
    end

    %% Relationships
    CA -->|uses| KVClientService
    KVClientService -->|calls| KVSdkStub
    KVClientService -->|calls| RESTSdk
    KVSdkStub -->|gRPC| Handler
    RESTSdk -->|HTTP/REST| Handler

    common -->|shared definitions| KVSdkStub
    common -->|shared definitions| Handler

    App -->|initializes| Handler
    App -->|initializes| Master

    Handler -->|calls| KVService
    Master -->|calls| KVService
    ConfigBean -->|injects| DataMaster

    KVService -->|per-key ops| DataHandler
    KVService -->|coordination| DataMaster

    DataHandler -->|reads/writes| Store
    DataMaster -->|coordinates| Store

    TTL -.->|evicts entries| Store

    %% Click Events
    click CA "https://github.com/hrs05/key-value-store-v2/blob/main/client/src/main/java/com/proto/client/ClientApplication.java"
    click KVClientService "https://github.com/hrs05/key-value-store-v2/blob/main/client/src/main/java/com/proto/client/service/KeyValueClientService.java"
    click KVApi "https://github.com/hrs05/key-value-store-v2/blob/main/client/src/main/java/com/proto/client/api/KeyValueApi.java"
    click KVModel "https://github.com/hrs05/key-value-store-v2/blob/main/client/src/main/java/com/proto/client/sdk/KeyValue.java"
    click KVException "https://github.com/hrs05/key-value-store-v2/blob/main/client/src/main/java/com/proto/client/exception/KeyValueException.java"
    click common "https://github.com/hrs05/key-value-store-v2/blob/main/common/src/main/proto/common.proto"
    click App "https://github.com/hrs05/key-value-store-v2/blob/main/key.value/src/main/java/com/hrs/key/value/Application.java"
    click Handler "https://github.com/hrs05/key-value-store-v2/blob/main/key.value/src/main/java/com/hrs/key/value/api/HandlerAPI.java"
    click Master "https://github.com/hrs05/key-value-store-v2/blob/main/key.value/src/main/java/com/hrs/key/value/api/MasterAPI.java"
    click KVService "https://github.com/hrs05/key-value-store-v2/blob/main/key.value/src/main/java/com/hrs/key/value/service/KeyValueService.java"
    click DataHandler "https://github.com/hrs05/key-value-store-v2/blob/main/key.value/src/main/java/com/hrs/key/value/data/KeyValueDataHandler.java"
    click DataMaster "https://github.com/hrs05/key-value-store-v2/blob/main/key.value/src/main/java/com/hrs/key/value/data/KeyValueDataMaster.java"
    click TTL "https://github.com/hrs05/key-value-store-v2/blob/main/key.value/src/main/java/com/hrs/key/value/ttl/TTLSchedular.java"
    click ConfigBean "https://github.com/hrs05/key-value-store-v2/blob/main/key.value/src/main/java/com/hrs/key/value/configuration/KeyValueMasterBean.java"

    %% Styles
    classDef client fill:#cfe2f3,stroke:#0b5394,color:#0b5394;
    classDef common fill:#d9d9d9,stroke:#8c8c8c,color:#333333;
    classDef server fill:#e2efda,stroke:#6aa84f,color:#38761d;
    classDef api fill:#d0e0e3,stroke:#134f5c,color:#0c343d;
    classDef service fill:#fce5cd,stroke:#e69138,color:#7f6000;
    classDef data fill:#f9cb9c,stroke:#b45f06,color:#53350a;
    classDef db fill:#d5e8d4,stroke:#82b366,color:#274e13;
    classDef ttl fill:#f4cccc,stroke:#cc0000,color:#660000;
    classDef config fill:#ececec,stroke:#888888,color:#333333;
```
