# hasnainrabbani/moniepoint-kv-springboot architecture

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

- Interactive diagram: https://gitdiagram.com/hasnainrabbani/moniepoint-kv-springboot
- Repository: https://github.com/hasnainrabbani/moniepoint-kv-springboot

## Overview

##### Project type and purpose
- This is a stand-alone, HTTP-based key–value store service implemented in Java Spring Boot.
- It exposes CRUD endpoints, persists data on disk in a Bitcask-style append-only log plus in-memory index, and runs embedded in Tomcat (packaged as JAR or Docker image).

##### Main components
- Client / External Tools
– REST client (curl, Postman), or Swagger UI
- API Layer
– Embedded Tomcat (Spring Web)
– KvController (handles HTTP GET/PUT/DELETE/POST)
- Service Layer
– KvService interface + KvServiceImpl (business logic: validation, batch operations)
- Store Layer (Bitcask implementation)
– BitcaskStore class (append log files + in-memory index)
– SegmentFile (manages individual data files on disk)
– Utils & CRC check (data integrity)
- Background Compaction
– Scheduled or trigger-based compaction process within BitcaskStore
- Configuration
– KvConfig / KvProperties (application.yml, env vars, CLI args)
- Persistence
– Local file system directory (kv.dataDir) containing segment files
- Deployment
– Docker container or direct JAR on JVM

##### Relationships and data flows
1. Client → HTTP request → Embedded Tomcat
2. Tomcat → DispatcherServlet → KvController
3. KvController → calls KvServiceImpl
4. KvServiceImpl → invokes BitcaskStore methods (put, get, delete, range)
5. BitcaskStore
- Appends new records to segment files on disk
- Updates in-memory index (key → file offset)
- Reads data by looking up index, then fetching from segment file
6. Compaction thread monitors thresholds → rewrites active segment files → updates index
7. Service returns to Controller → Controller returns HTTP response → Client
8. Configuration flows at startup: application.yml/env vars/CLI → KvConfig

##### Architectural patterns & design principles
- Layered architecture (Controller → Service → Store)
- Dependency Injection (Spring) for config, services
- Single responsibility: separate controller, business logic, storage util
- Append-only log + in-memory index (Bitcask design)
- Background compaction / eventual consistency of on-disk files

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients" 
        direction TB
        Client["REST Client (curl/Postman)"]:::external
        SwaggerUI["Swagger UI"]:::external
    end

    %% Configuration
    subgraph "Configuration" 
        direction TB
        AppProps["application.yml"]:::config
        KvConfig["KvConfig"]:::config
        KvProperties["KvProperties"]:::config
        SwaggerConfig["SwaggerConfig"]:::config
    end

    %% Application Entry
    KvApp["KvSpringBootApplication"]:::app

    %% API Layer
    subgraph "API Layer" 
        direction TB
        Tomcat["Embedded Tomcat"]:::controller
        KvController["KvController"]:::controller
    end

    %% Service Layer
    subgraph "Service Layer" 
        direction TB
        KvService["KvService"]:::service
        KvServiceImpl["KvServiceImpl"]:::service
    end

    %% Store Layer
    subgraph "Store Layer (Bitcask)" 
        direction TB
        BitcaskStore["BitcaskStore"]:::storage
        SegmentFile["SegmentFile"]:::storage
        InMemoryIndex["In-Memory Index"]:::storage
        Utils["Utils"]:::storage
        CRC32["Crc32s"]:::storage
    end

    %% Persistence
    FileSystem["File System (dataDir)"]:::storage

    %% Background Compaction
    Compaction["Compaction Thread"]:::storage

    %% Deployment
    subgraph "Deployment Envelope"
        direction TB
        DockerfileNode["Dockerfile"]:::deployment
        DockerCompose["docker-compose.yml"]:::deployment
        Pom["pom.xml"]:::deployment
    end

    %% Testing
    Test["KvApiIntegrationTests"]:::test

    %% Flows
    Client -->|"HTTP Request"| Tomcat
    SwaggerUI -->|"HTTP Request"| Tomcat
    Tomcat -->|"DispatcherServlet"| KvController
    KvController -->|"calls"| KvServiceImpl
    KvServiceImpl -->|"delegates"| BitcaskStore
    BitcaskStore -->|"append log"| SegmentFile
    BitcaskStore -->|"update index"| InMemoryIndex
    BitcaskStore -->|"use Utils/CRC32"| Utils
    BitcaskStore -->|"use Utils/CRC32"| CRC32
    SegmentFile -->|"writes/reads"| FileSystem
    Compaction -->|"rewrites segments"| SegmentFile
    Compaction -->|"updates index"| InMemoryIndex
    AppProps -->|"configures"| KvConfig
    KvConfig -->|"injected into"| KvApp
    KvProperties -->|"binds props"| KvConfig
    SwaggerConfig -->|"configures Swagger"| KvApp
    KvApp -->|"runs on"| Tomcat
    DockerfileNode -->|"packages"| KvApp
    Pom -->|"builds JAR"| KvApp
    DockerCompose -->|"orchestrates"| DockerfileNode
    Test -->|"tests REST API on"| KvApp

    %% Click Events
    click KvApp "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/KvSpringBootApplication.java"
    click AppProps "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/application.yml"
    click KvConfig "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/config/KvConfig.java"
    click KvProperties "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/config/KvProperties.java"
    click SwaggerConfig "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/config/SwaggerConfig.java"
    click KvController "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/controller/KvController.java"
    click KvService "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/service/KvService.java"
    click KvServiceImpl "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/service/impl/KvServiceImpl.java"
    click BitcaskStore "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/util/BitcaskStore.java"
    click SegmentFile "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/util/SegmentFile.java"
    click Utils "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/util/Utils.java"
    click CRC32 "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/main/java/com/moniepoint/kv/model/Crc32s.java"
    click Pom "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/pom.xml"
    click DockerfileNode "https://github.com/hasnainrabbani/moniepoint-kv-springboot/tree/main/Dockerfile"
    click DockerCompose "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/docker-compose.yml"
    click Test "https://github.com/hasnainrabbani/moniepoint-kv-springboot/blob/main/src/test/java/com/moniepoint/kv/KvApiIntegrationTests.java"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef config fill:#d8bfff,stroke:#333,stroke-width:1px;
    classDef app fill:#a0c4ff,stroke:#333,stroke-width:1px;
    classDef controller fill:#89cff0,stroke:#333,stroke-width:1px;
    classDef service fill:#c2f970,stroke:#333,stroke-width:1px;
    classDef storage fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef deployment fill:#e0e0e0,stroke:#333,stroke-width:1px;
    classDef test fill:#ffb3c1,stroke:#333,stroke-width:1px;
```
