# jayjamieson/fixedkv architecture

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

- Interactive diagram: https://gitdiagram.com/jayjamieson/fixedkv
- Repository: https://github.com/jayjamieson/fixedkv

## Overview

##### Main Components
- FixedKV Instance: At the center is the core library (defined in fixedkv.go) which implements the key-value store.
- In-Memory B-tree: This is the in-memory data structure that is used to speed up lookups and insertions.
- Disk Persistence Module: This component handles writing the in-memory state to disk when the engine is closed and also loading the persisted state for read-only operations via fixedkv.Open().
- File Format Handling: The logic that writes (and reads) the binary file format, including the header (first 96 bytes) and the key-value records. Even if this isn’t split into separate packages, conceptually distinguish it to illustrate data layout (version info, key count, and key/value records).
- Client/Application Layer: Although not directly a part of the storage engine code (being invoked via the cmd/fixedkv entry point), include an external client (or the main function) that creates, writes to, closes, and reads from the storage engine.

##### Relationships and Interactions
- The Client Layer calls methods on the FixedKV Instance for Get and Set operations.
- The FixedKV Instance uses the In-Memory B-tree for fast operations.
- On closing the FixedKV instance, data from the in-memory structure is passed to the Disk Persistence Module which serializes it into the determined binary format.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly separate the in-memory data handling (B-tree operations) from the persistence logic.
- Single Responsibility: The disk writer focuses on file format adherence (handling the 96-byte header and key/value records) while the in-memory component focuses solely on optimizing data access.

##### Notable Technologies and Libraries
- Go’s native data types and libraries are used, so you might mention the use of Go modules (go.mod, go.sum) to manage dependencies.
- Since no external libraries are noted, highlight the custom implementation for the binary format and B-tree, which is pivotal to the system.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Application Layer
    subgraph "Application Layer"
        C1("Client/Application (cmd/fixedkv/main.go)"):::client
    end

    %% Storage Engine Layer
    subgraph "Storage Engine Layer"
        E1("FixedKV Engine (fixedkv.go)"):::engine
        B1("In-Memory B-tree"):::inMem
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        D1("Disk Persistence Module & Binary File Format Parser/Serializer (reader.go)"):::persistence
    end

    %% Relationships
    C1 -->|"calls_Get/Set"| E1
    E1 -->|"uses_B-tree"| B1
    E1 -->|"on_close:persists_data"| D1
    D1 -->|"loads_state"| E1

    %% Click Events
    click C1 "https://github.com/jayjamieson/fixedkv/blob/main/cmd/fixedkv/main.go"
    click E1 "https://github.com/jayjamieson/fixedkv/blob/main/fixedkv.go"
    click B1 "https://github.com/jayjamieson/fixedkv/blob/main/fixedkv.go"
    click D1 "https://github.com/jayjamieson/fixedkv/blob/main/reader.go"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef engine fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef inMem fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef persistence fill:#FFA07A,stroke:#333,stroke-width:2px;
```
