# mo5ul/javedb architecture

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

- Interactive diagram: https://gitdiagram.com/mo5ul/javedb
- Repository: https://github.com/mo5ul/javedb

## Overview

JaveDB is an embedded Java key-value database with an LSM-tree storage engine. The main workflow is a user operating the console, which calls the database API to write, read, or delete entries; writes are documented as going through the WAL and MemTable before SSTable flush, while reads consult in-memory and persisted data. The README also documents compaction, a runtime dashboard and health monitor, and a benchmark suite. Central engine wiring is based on README and CLI evidence; the JaveDB implementation itself was not sampled.

Main entry points: [`src/main/java/io/github/mohul/cli/ConsoleShell.java`](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/cli/ConsoleShell.java) (Console shell), [`src/main/java/io/github/mohul/db/JaveDB.java`](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/db/JaveDB.java) (JaveDB API), [`src/main/java/io/github/mohul/sstable/SSTableReader.java`](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/SSTableReader.java) (SSTable reader), [`src/main/java/io/github/mohul/sstable`](https://github.com/mo5ul/javedb/tree/main/src/main/java/io/github/mohul/sstable) (Immutable SSTables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_console["Console shell<br/>[ConsoleShell.java]"]
end

subgraph group_engine["Database engine"]
  node_api["JaveDB API<br/>[JaveDB.java]"]
end

subgraph group_storage["LSM storage"]
  node_wal[("Write-ahead log<br/>[WALManager.java]")]
  node_memtable[("MemTable<br/>[MemTable.java]")]
  node_sstwriter["SSTable writer<br/>[SSTableWriter.java]"]
  node_sstreader["SSTable reader<br/>[SSTableReader.java]"]
  node_sstables[("Immutable SSTables")]
  node_bloom["Bloom filter<br/>[BloomFilter.java]"]
  node_index["Sparse index<br/>[IndexEntry.java]"]
  node_compaction["Compaction<br/>[JaveDB.java]"]
end

subgraph group_monitoring["Observability"]
  node_summary["Database summary"]
  node_health["Health monitor"]
  node_eventlog["Engine event log"]
end

subgraph group_benchmarking["Benchmarking"]
  node_suite["Performance suite"]
  node_report["Benchmark report"]
end

node_user(("Database user"))

node_user -->|"operates"| node_console
node_console -->|"calls"| node_api
node_console -->|"runs"| node_suite
node_api -->|"appends and replays"| node_wal
node_api -->|"updates and queries"| node_memtable
node_api -->|"flushes through"| node_sstwriter
node_sstwriter -->|"writes"| node_sstables
node_api -->|"reads through"| node_sstreader
node_sstreader -->|"reads"| node_sstables
node_sstreader -->|"checks membership"| node_bloom
node_sstreader -->|"searches"| node_index
node_api -->|"coordinates"| node_compaction
node_compaction -->|"compacts"| node_sstables
node_console -->|"displays"| node_summary
node_console -->|"displays"| node_health
node_console -->|"displays"| node_eventlog
node_suite -->|"generates"| node_report

click node_console "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/cli/ConsoleShell.java"
click node_api "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/db/JaveDB.java"
click node_wal "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/wal/WALManager.java"
click node_memtable "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/memtable/MemTable.java"
click node_sstwriter "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/SSTableWriter.java"
click node_sstreader "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/SSTableReader.java"
click node_sstables "https://github.com/mo5ul/javedb/tree/main/src/main/java/io/github/mohul/sstable"
click node_bloom "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/BloomFilter.java"
click node_index "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/IndexEntry.java"
click node_compaction "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/db/JaveDB.java"
click node_summary "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/observability/info/DatabaseSummary.java"
click node_health "https://github.com/mo5ul/javedb/tree/main/src/main/java/io/github/mohul/observability/health"
click node_eventlog "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/observability/event/EngineEventLog.java"
click node_suite "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/benchmark/PerformanceSuite.java"
click node_report "https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/benchmark/ReportGenerator.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_console toneBlue
class node_api,node_user toneAmber
class node_wal,node_memtable,node_sstwriter,node_sstreader,node_sstables,node_bloom,node_index,node_compaction toneMint
class node_summary,node_health,node_eventlog toneRose
class node_suite,node_report toneIndigo
```

## Components

### User interface

- [Console shell](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/cli/ConsoleShell.java): `src/main/java/io/github/mohul/cli/ConsoleShell.java`

### Database engine

- [JaveDB API](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/db/JaveDB.java): `src/main/java/io/github/mohul/db/JaveDB.java`

### LSM storage

- [Write-ahead log](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/wal/WALManager.java): `src/main/java/io/github/mohul/wal/WALManager.java`
- [MemTable](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/memtable/MemTable.java): `src/main/java/io/github/mohul/memtable/MemTable.java`
- [SSTable writer](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/SSTableWriter.java): `src/main/java/io/github/mohul/sstable/SSTableWriter.java`
- [SSTable reader](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/SSTableReader.java): `src/main/java/io/github/mohul/sstable/SSTableReader.java`
- [Immutable SSTables](https://github.com/mo5ul/javedb/tree/main/src/main/java/io/github/mohul/sstable): `src/main/java/io/github/mohul/sstable`
- [Bloom filter](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/BloomFilter.java): `src/main/java/io/github/mohul/sstable/BloomFilter.java`
- [Sparse index](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/sstable/IndexEntry.java): `src/main/java/io/github/mohul/sstable/IndexEntry.java`
- [Compaction](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/db/JaveDB.java): `src/main/java/io/github/mohul/db/JaveDB.java`

### Observability

- [Database summary](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/observability/info/DatabaseSummary.java): `src/main/java/io/github/mohul/observability/info/DatabaseSummary.java`
- [Health monitor](https://github.com/mo5ul/javedb/tree/main/src/main/java/io/github/mohul/observability/health): `src/main/java/io/github/mohul/observability/health`
- [Engine event log](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/observability/event/EngineEventLog.java): `src/main/java/io/github/mohul/observability/event/EngineEventLog.java`

### Benchmarking

- [Performance suite](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/benchmark/PerformanceSuite.java): `src/main/java/io/github/mohul/benchmark/PerformanceSuite.java`
- [Benchmark report](https://github.com/mo5ul/javedb/blob/main/src/main/java/io/github/mohul/benchmark/ReportGenerator.java): `src/main/java/io/github/mohul/benchmark/ReportGenerator.java`

### Other components

- **Database user**

## Connections

- Database user → Console shell: operates
- Console shell → JaveDB API: calls
- Console shell → Performance suite: runs
- JaveDB API → Write-ahead log: appends and replays
- JaveDB API → MemTable: updates and queries
- JaveDB API → SSTable writer: flushes through
- SSTable writer → Immutable SSTables: writes
- JaveDB API → SSTable reader: reads through
- SSTable reader → Immutable SSTables: reads
- SSTable reader → Bloom filter: checks membership
- SSTable reader → Sparse index: searches
- JaveDB API → Compaction: coordinates
- Compaction → Immutable SSTables: compacts
- Console shell → Database summary: displays
- Console shell → Health monitor: displays
- Console shell → Engine event log: displays
- Performance suite → Benchmark report: generates