# syndtr/goleveldb architecture

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

- Interactive diagram: https://gitdiagram.com/syndtr/goleveldb
- Repository: https://github.com/syndtr/goleveldb

## Overview

##### Project type and purpose
- This is an open-source, embeddable key/value database library (`goleveldb`) written in Go. It implements Google’s LevelDB architecture, providing persistence, indexing, iteration, batch writes, snapshots, and compaction. Developers import it into their Go programs to persist and query arbitrary byte‐slice keys and values.

##### File structure
Top-level directories and files:
- leveldb/ – core implementation broken down into packages:
– batch.go           (write batches)
– db.go*, db_*.go    (DB interface, open/close, Get/Put/Delete, snapshots)
– iterator/         (Iterator implementations and merging logic)
– memdb/            (in-memory memtable)
– table/            (SSTable reader/writer, block format)
– journal/          (Write Ahead Log)
– storage/          (pluggable storage backends: file, in-memory)
– cache/            (LRU block cache)
– filter/           (Bloom filter implementation)
– opt/              (Options, filter/compaction parameters)
– util/             (buffer pools, CRC32, ranges)
– comparer/ errors/ testutil/ (pluggable comparators, error types, testing helpers)
- manualtest/ – stress tests and file-lock examples
- go.mod, README.md, CI config, license

##### README for additional insights
- Confirms it’s a drop-in LevelDB clone in Go.
- Highlights core APIs (OpenFile, Get, Put, Delete, NewIterator, Batch writes, Filters).

##### Essential details to capture
- All data-flow paths: Get vs. Put vs. Compaction vs. Iterator
- Background vs. synchronous operations
- Extension points (interfaces in opt, comparer, storage)
- Concurrency boundaries (thread-safe DB vs. background goroutine)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/API Layer
    subgraph "Client API Layer"
        direction TB
        DB["leveldb.DB Interface"]:::api
    end

    %% Write-Ahead Log
    WAL["WAL (journal)"]:::disk
    %% In-Memory Components
    subgraph "In-Memory Layer"
        direction TB
        Mem["Memtable"]:::memory
        ImmMem["Immutable Memtable"]:::memory
        Cache["Block Cache"]:::memory
    end

    %% On-Disk Table Components
    subgraph "SSTable Module"
        direction TB
        SSTW["SSTable Writer"]:::disk
        SSTR["SSTable Reader"]:::disk
    end

    %% Storage Backends
    subgraph "Storage Backends"
        direction TB
        FileStore["File Storage"]:::disk
        MemStore["Memory Storage"]:::memory
    end

    %% Compaction Engine
    Compaction["Compaction Engine"]:::disk

    %% Iterator Layer
    Iterator["Merged Iterator"]:::memory

    %% Extension Points
    subgraph "Configuration & Extensibility"
        direction TB
        Opt["Options"]:::config
        Comparer["Comparer"]:::config
        FilterMod["Filter"]:::memory
    end

    %% Utilities
    Util["Utilities"]:::util

    %% Data Flows
    DB -->|"Put/Delete/Write"| WAL
    WAL -->|"Append Write"| Mem
    Mem -->|"Flush"| ImmMem
    ImmMem -->|"Write SSTable"| SSTW
    SSTW --> FileStore
    FileStore --> SSTR
    SSTR --> Iterator
    Mem --> Iterator
    ImmMem --> Iterator
    Iterator -->|"Get/Iterator"| DB

    SSTW -->|"New SSTables"| Compaction
    Compaction -->|"Merge/Rewrite SSTables"| SSTW
    FileStore -.-> Compaction
    SSTR -.-> Cache
    SSTR -.-> FilterMod
    Cache --> Iterator
    FilterMod --> Iterator

    DB --> Opt
    DB --> Comparer
    SSTR --> FilterMod
    DB --> Iterator
    DB --> Compaction
    Compaction --> FileStore
    DB --> Util

    %% Click Events
    click DB "https://github.com/syndtr/goleveldb/blob/master/leveldb/db.go"
    click WAL "https://github.com/syndtr/goleveldb/blob/master/leveldb/journal/journal.go"
    click Mem "https://github.com/syndtr/goleveldb/blob/master/leveldb/memdb/memdb.go"
    click SSTW "https://github.com/syndtr/goleveldb/blob/master/leveldb/table/writer.go"
    click SSTR "https://github.com/syndtr/goleveldb/blob/master/leveldb/table/reader.go"
    click FileStore "https://github.com/syndtr/goleveldb/blob/master/leveldb/storage/file_storage.go"
    click MemStore "https://github.com/syndtr/goleveldb/blob/master/leveldb/storage/mem_storage.go"
    click Compaction "https://github.com/syndtr/goleveldb/blob/master/leveldb/db_compaction.go"
    click Iterator "https://github.com/syndtr/goleveldb/blob/master/leveldb/iterator/merged_iter.go"
    click Cache "https://github.com/syndtr/goleveldb/blob/master/leveldb/cache/cache.go"
    click FilterMod "https://github.com/syndtr/goleveldb/blob/master/leveldb/filter/bloom.go"
    click Opt "https://github.com/syndtr/goleveldb/blob/master/leveldb/opt/options.go"
    click Comparer "https://github.com/syndtr/goleveldb/blob/master/leveldb/comparer/comparer.go"
    click Util "https://github.com/syndtr/goleveldb/blob/master/leveldb/util/buffer.go"

    %% Styles
    classDef memory fill:#B3D7FF,stroke:#1E90FF,color:#000
    classDef disk fill:#C6E2FF,stroke:#4682B4,color:#000
    classDef api fill:#FFD580,stroke:#FFA500,color:#000
    classDef config fill:#F7E7CE,stroke:#DEB887,color:#000
    classDef util fill:#D3D3D3,stroke:#A9A9A9,color:#000
```
