# kushall-07/forgedb architecture

> Architecture diagram of the GitHub repository kushall-07/forgedb, 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/kushall-07/forgedb
- Repository: https://github.com/kushall-07/forgedb

## Overview

ForgeDB is an early-stage, single-node key/value storage engine, not a network server. Its demonstrated workflow is a command-line run that opens the WAL-backed store, writes and reads a value, closes it, then reopens the same data directory and reads the recovered value. The storage path separates the Store API, WAL-backed orchestration, in-memory ordered state, and durable log. The README is empty; the tree and sampled source do not establish server, replication, or configuration workflows, so they are omitted.

Main entry points: [`internal/storage/memstore.go`](https://github.com/kushall-07/forgedb/blob/main/internal/storage/memstore.go) (MemStore), [`internal/storage/wal/wal.go`](https://github.com/kushall-07/forgedb/blob/main/internal/storage/wal/wal.go) (WAL), [`cmd/forgedb/main.go`](https://github.com/kushall-07/forgedb/blob/main/cmd/forgedb/main.go) (CLI entry), [`internal/storage/memtable/memtable.go`](https://github.com/kushall-07/forgedb/blob/main/internal/storage/memtable/memtable.go) (MemTable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demo["Demo entry"]
  node_cli["CLI entry<br/>[main.go]"]
  node_demo_workflow["Demo workflow<br/>[main.go]"]
  node_logging["Logging<br/>[logger.go]"]
end

subgraph group_storage["Storage engine"]
  node_store_contract["Store contract<br/>[storage.go]"]
  node_memstore["MemStore<br/>[memstore.go]"]
  node_memtable["MemTable<br/>[memtable.go]"]
  node_skiplist["Skip list<br/>[skiplist.go]"]
end

subgraph group_persistence["Persistence"]
  node_wal["WAL<br/>[wal.go]"]
  node_record_codec["Record codec<br/>[record.go]"]
  node_wal_file[("WAL file")]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_cli
node_cli -->|"calls"| node_demo_workflow
node_cli -->|"logs startup"| node_logging
node_demo_workflow -->|"opens store"| node_memstore
node_demo_workflow -->|"logs results"| node_logging
node_memstore -->|"implements"| node_store_contract
node_memstore -->|"opens and replays"| node_wal
node_memstore -->|"creates and applies"| node_memtable
node_memstore -->|"appends and syncs"| node_wal
node_memstore -->|"reads and mutates"| node_memtable
node_memtable -->|"stores entries"| node_skiplist
node_wal -->|"encodes and decodes"| node_record_codec
node_wal -->|"reads and writes"| node_wal_file

click node_cli "https://github.com/kushall-07/forgedb/blob/main/cmd/forgedb/main.go"
click node_demo_workflow "https://github.com/kushall-07/forgedb/blob/main/cmd/forgedb/main.go"
click node_logging "https://github.com/kushall-07/forgedb/blob/main/internal/metrics/logger.go"
click node_store_contract "https://github.com/kushall-07/forgedb/blob/main/internal/storage/storage.go"
click node_memstore "https://github.com/kushall-07/forgedb/blob/main/internal/storage/memstore.go"
click node_memtable "https://github.com/kushall-07/forgedb/blob/main/internal/storage/memtable/memtable.go"
click node_skiplist "https://github.com/kushall-07/forgedb/blob/main/internal/storage/memtable/skiplist.go"
click node_wal "https://github.com/kushall-07/forgedb/blob/main/internal/storage/wal/wal.go"
click node_record_codec "https://github.com/kushall-07/forgedb/blob/main/internal/storage/wal/record.go"

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_cli,node_demo_workflow,node_logging toneBlue
class node_store_contract,node_memstore,node_memtable,node_skiplist toneAmber
class node_wal,node_record_codec,node_wal_file toneMint
class node_operator toneIndigo
```

## Components

### Demo entry

- [CLI entry](https://github.com/kushall-07/forgedb/blob/main/cmd/forgedb/main.go): `cmd/forgedb/main.go`
- [Demo workflow](https://github.com/kushall-07/forgedb/blob/main/cmd/forgedb/main.go): `cmd/forgedb/main.go`
- [Logging](https://github.com/kushall-07/forgedb/blob/main/internal/metrics/logger.go): `internal/metrics/logger.go`

### Storage engine

- [Store contract](https://github.com/kushall-07/forgedb/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [MemStore](https://github.com/kushall-07/forgedb/blob/main/internal/storage/memstore.go): `internal/storage/memstore.go`
- [MemTable](https://github.com/kushall-07/forgedb/blob/main/internal/storage/memtable/memtable.go): `internal/storage/memtable/memtable.go`
- [Skip list](https://github.com/kushall-07/forgedb/blob/main/internal/storage/memtable/skiplist.go): `internal/storage/memtable/skiplist.go`

### Persistence

- [WAL](https://github.com/kushall-07/forgedb/blob/main/internal/storage/wal/wal.go): `internal/storage/wal/wal.go`
- [Record codec](https://github.com/kushall-07/forgedb/blob/main/internal/storage/wal/record.go): `internal/storage/wal/record.go`
- **WAL file**

### Other components

- **Operator**

## Connections

- Operator → CLI entry: runs
- CLI entry → Demo workflow: calls
- CLI entry → Logging: logs startup
- Demo workflow → MemStore: opens store
- Demo workflow → Logging: logs results
- MemStore → Store contract: implements
- MemStore → WAL: opens and replays
- MemStore → MemTable: creates and applies
- MemStore → WAL: appends and syncs
- MemStore → MemTable: reads and mutates
- MemTable → Skip list: stores entries
- WAL → Record codec: encodes and decodes
- WAL → WAL file: reads and writes