# datnguyenzzz/nogodb architecture

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

- Interactive diagram: https://gitdiagram.com/datnguyenzzz/nogodb
- Repository: https://github.com/datnguyenzzz/nogodb

## Overview

##### Project type and purpose
- nogoDB is a Go-based key–value storage engine implementing a fragmented LSM-tree. It’s a library/tool (not a UI application) that provides atomic writes, on-disk sorted string tables (SSTables), in-memory indexing, bloom-filters, and virtual file system abstraction.

##### File structure
- Top-level:
- README.md, docs/ – project overview and design notes
- lib/ – modular packages that implement subcomponents
- lib/go-wal – write-ahead log (durability)
- lib/go-adaptive-radix-tree – in-memory index (memtable)
- lib/go-blocked-bloom-filter – filter to avoid unnecessary disk I/O
- lib/go-sstable – on-disk sorted string table storage, block format, compression, iterator
- lib/go-fs – virtual file system abstraction (pluggable storage backend)
- lib/go-context-aware-lock – concurrency control
- lib/go-bytesbufferpool – reusable buffers for I/O performance

##### Additional insights from README
- The “Development Progress Tracker” shows that WAL, radix-tree, and bloom-filter are done; SSTable and VFS remain.
- The system is built in components to be composed into a full LSM pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Write Path
    subgraph "Write Path"
        direction TB
        Client["Client API"]
        WAL["WAL (Write-Ahead Log)"]:::write
        Memtable["Memtable (ART Index)"]:::write
        BufferPool["Buffer Pool"]:::write
        Client --> WAL
        WAL --> Memtable
        BufferPool --> WAL
    end

    %% Read Path
    subgraph "Read Path"
        direction TB
        MemtableR["Memtable (ART Index)"]:::read
        Bloom["Bloom Filter"]:::read
        SSTReader["SSTable Reader"]:::read
        Client --> MemtableR
        MemtableR -->|"miss"| Bloom
        Bloom -->|"maybe_present"| SSTReader
        SSTReader --> VFS
    end

    %% Storage Layer
    subgraph "Storage & Components"
        direction TB
        VFS["Virtual File System"]:::storage
        SSTWriter["SSTable Writer"]:::storage
        VFS --> SSTWriter
        SSTWriter --> VFS
    end

    %% Background Tasks
    subgraph "Background Tasks"
        direction TB
        Compaction["Compaction Coordinator"]:::background
        Lock["Context-Aware Lock"]:::background
        Compaction --> SSTWriter
        Lock --> Memtable
        Lock --> SSTWriter
    end

    %% Flush from Memtable to SSTable
    Memtable -->|"flush"| SSTWriter

    %% Click Events
    click VFS "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-fs/objstorage.go"
    click WAL "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-wal/wal.go"
    click Memtable "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-adaptive-radix-tree/art.go"
    click Bloom "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-blocked-bloom-filter/bloom.go"
    click SSTWriter "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-sstable/writer.go"
    click SSTReader "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-sstable/iterator.go"
    click Compaction "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-sstable/queue/coordinator.go"
    click Lock "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-context-aware-lock/iface.go"
    click Lock "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-context-aware-lock/local_lock/lock.go"
    click BufferPool "https://github.com/datnguyenzzz/nogodb/blob/master/lib/go-bytesbufferpool/predictable_size/bytebufferpool.go"

    %% Styles
    classDef write fill:#C3DFFF,stroke:#0366d6,stroke-width:1px
    classDef read fill:#D4F8C4,stroke:#2EA043,stroke-width:1px
    classDef storage fill:#FEEFB3,stroke:#735C0F,stroke-width:1px
    classDef background fill:#E5E5E5,stroke:#8A8A8A,stroke-width:1px
    classDef external fill:#F5C6CB,stroke:#A71D2A,stroke-width:1px
```
