# soundvibe/lasher architecture

> Architecture diagram of the GitHub repository soundvibe/lasher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/soundvibe/lasher
- Repository: https://github.com/soundvibe/lasher

## Overview

##### Main Components

a. Core Components:
- LasherDB (Main key-value store)
- LasherMap (ConcurrentMap implementation)
- TimeLash (Time-series map implementation)

b. Storage Layer:
- Memory-mapped files (Index and Data files)
- Shard management system

c. Supporting Components:
- Serialization/Deserialization (Serde) framework
- Synchronization mechanisms
- File handling utilities

##### Component Relationships

- Client APIs → Core Implementation
- Core Implementation → Storage Layer
- All Components → Serde Framework (for data serialization)
- All Components → Synchronization Layer (for thread safety)

##### Specific Implementation Details

- Rectangles: Main components (LasherDB, LasherMap, TimeLash)
- Hexagons: Core processing components (Lasher, Shard)
- Ovals: Utility components (Serde, Synchronization)

- Blue: Client-facing APIs
- Green: Core processing
- Yellow: Storage
- Gray: Utilities

Following flows:
- Write path: Client → API → Core → Serde → Storage
- Read path: Client → API → Core → Storage → Serde → Client
- Time-series specific flow for TimeLash
- Shard management flow

##### Important Details to Highlight

- Memory-mapped file architecture (show both index and data files)
- Sharding mechanism
- Time-series partitioning for TimeLash
- Thread-safety mechanisms
- Serialization points

##### Technical Specifications

- Java version compatibility
- Memory management approach
- Thread safety guarantees
- Performance characteristics

- The lightweight nature of the system
- The memory-mapped file architecture
- The three distinct API options (DB, Map, TimeSeries)
- The efficient sharding and partitioning mechanisms

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef api fill:#2196F3,stroke:#1565C0,color:white
    classDef core fill:#4CAF50,stroke:#2E7D32,color:white
    classDef storage fill:#FFC107,stroke:#FFA000,color:black
    classDef util fill:#9E9E9E,stroke:#616161,color:white
    classDef legend fill:none,stroke:#000000

    %% Client Interface Layer
    subgraph ClientAPI
        LasherDB["LasherDB"]:::api
        LasherMap["LasherMap"]:::api
        TimeLash["TimeLash"]:::api
    end

    %% Core Implementation Layer
    subgraph CoreImpl
        BaseHash["BaseLinearHashMap"]:::core
        LasherCore["Lasher Core"]:::core
        Shard["Shard Management"]:::core
    end

    %% Storage Layer
    subgraph Storage
        MemMap["Memory Mapped Files"]:::storage
        IndexNode["Index Management"]:::storage
        DataNode["Data Management"]:::storage
        Buffer["Buffer Management"]:::storage
    end

    %% Utility Layer
    subgraph Utils
        Serde["Serialization Framework"]:::util
        RWLocker["RW Locker"]:::util
        FileUtil["File Utilities"]:::util
        BytesUtil["Bytes Utilities"]:::util
    end

    %% Relationships
    LasherDB --> BaseHash
    LasherMap --> BaseHash
    TimeLash --> BaseHash
    
    BaseHash --> LasherCore
    LasherCore --> Shard
    
    Shard --> MemMap
    MemMap --> IndexNode
    MemMap --> DataNode
    MemMap --> Buffer
    
    LasherCore --> Serde
    Shard --> RWLocker
    MemMap --> FileUtil
    MemMap --> BytesUtil

    %% Click Events
    click LasherDB "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/db/LasherDB.java"
    click LasherMap "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/map/LasherMap.java"
    click TimeLash "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/db/TimeLash.java"
    click BaseHash "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/map/core/BaseLinearHashMap.java"
    click LasherCore "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/map/core/Lasher.java"
    click Shard "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/map/core/Shard.java"
    click MemMap "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/mmap/MemoryMapped.java"
    click IndexNode "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/mmap/IndexNode.java"
    click DataNode "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/mmap/DataNode.java"
    click Buffer "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/mmap/MappedBuffer.java"
    click Serde "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/serde/Serde.java"
    click RWLocker "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/map/sync/RWLocker.java"
    click FileUtil "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/util/FileSupport.java"
    click BytesUtil "https://github.com/soundvibe/lasher/blob/master/src/main/java/net/soundvibe/lasher/util/BytesSupport.java"

    %% Legend
    subgraph Legend
        L1["Client APIs"]:::api
        L2["Core Components"]:::core
        L3["Storage Components"]:::storage
        L4["Utilities"]:::util
    end
```
