# dgraph-io/badger architecture

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

- Interactive diagram: https://gitdiagram.com/dgraph-io/badger
- Repository: https://github.com/dgraph-io/badger

## Overview

BadgerDB is an embeddable Go key-value database. Applications open a DB, read and write through transactions, and retrieve ordered or versioned results with iterators; the documented storage design separates values into a value log and maintains keys in an LSM tree. The repository also provides streaming and offline backup/restore capabilities. The tree and README establish these product areas, but the sampled source is incomplete, so uncertain internal call wiring is omitted.

Main entry points: [`txn.go`](https://github.com/dgraph-io/badger/blob/main/txn.go) (Transactions), [`levels.go`](https://github.com/dgraph-io/badger/blob/main/levels.go) (LSM levels), [`compaction.go`](https://github.com/dgraph-io/badger/blob/main/compaction.go) (Compaction), [`badger/cmd/root.go`](https://github.com/dgraph-io/badger/blob/main/badger/cmd/root.go) (Admin CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Database API"]
  node_db["DB lifecycle<br/>[db.go]"]
  node_txn["Transactions<br/>[txn.go]"]
  node_batch["Write batches<br/>[batch.go]"]
  node_iterator["KV iterators<br/>[iterator.go]"]
  node_stream["Stream API<br/>[stream.go]"]
  node_options["DB options<br/>[options.go]"]
end

subgraph group_storage["Storage Engine"]
  node_memtable["Memtables<br/>[memtable.go]"]
  node_vlog[("Value log<br/>[value.go]")]
  node_lsm["LSM levels<br/>[levels.go]"]
  node_levelhandler["Level tables<br/>[level_handler.go]"]
  node_table[("Sorted tables<br/>[table.go]")]
  node_compaction["Compaction<br/>[compaction.go]"]
  node_manifest["Manifest<br/>[manifest.go]"]
end

subgraph group_maintenance["Maintenance and Tools"]
  node_backup["Backup and restore<br/>[backup.go]"]
  node_cli["Admin CLI<br/>[root.go]"]
  node_backupcmd["Backup command<br/>[backup.go]"]
  node_restorecmd["Restore command<br/>[restore.go]"]
end

subgraph group_internals["Internal Structures"]
  node_skiplists["Skip lists<br/>[skl.go]"]
  node_valueencoding["Value encoding<br/>[structs.go]"]
end

node_application(("Application"))

node_application -->|"opens DB"| node_db
node_application -->|"starts transactions"| node_txn
node_application -->|"iterates keys"| node_iterator
node_application -->|"uses streaming"| node_stream
node_db -->|"uses options"| node_options
node_txn -->|"writes keys"| node_memtable
node_txn -->|"stores values"| node_vlog
node_txn -->|"reads keys"| node_lsm
node_iterator -->|"scans keys"| node_lsm
node_lsm -->|"manages levels"| node_levelhandler
node_levelhandler -->|"reads tables"| node_table
node_compaction -->|"rewrites tables"| node_table
node_compaction -->|"records changes"| node_manifest
node_memtable -->|"indexes entries"| node_skiplists
node_txn -->|"encodes values"| node_valueencoding
node_cli -->|"dispatches"| node_backupcmd
node_cli -->|"dispatches"| node_restorecmd
node_backupcmd -->|"creates backup"| node_backup
node_restorecmd -->|"restores data"| node_backup

click node_db "https://github.com/dgraph-io/badger/blob/main/db.go"
click node_txn "https://github.com/dgraph-io/badger/blob/main/txn.go"
click node_batch "https://github.com/dgraph-io/badger/blob/main/batch.go"
click node_iterator "https://github.com/dgraph-io/badger/blob/main/iterator.go"
click node_stream "https://github.com/dgraph-io/badger/blob/main/stream.go"
click node_options "https://github.com/dgraph-io/badger/blob/main/options.go"
click node_memtable "https://github.com/dgraph-io/badger/blob/main/memtable.go"
click node_vlog "https://github.com/dgraph-io/badger/blob/main/value.go"
click node_lsm "https://github.com/dgraph-io/badger/blob/main/levels.go"
click node_levelhandler "https://github.com/dgraph-io/badger/blob/main/level_handler.go"
click node_table "https://github.com/dgraph-io/badger/blob/main/table/table.go"
click node_compaction "https://github.com/dgraph-io/badger/blob/main/compaction.go"
click node_manifest "https://github.com/dgraph-io/badger/blob/main/manifest.go"
click node_skiplists "https://github.com/dgraph-io/badger/blob/main/skl/skl.go"
click node_valueencoding "https://github.com/dgraph-io/badger/blob/main/structs.go"
click node_backup "https://github.com/dgraph-io/badger/blob/main/backup.go"
click node_cli "https://github.com/dgraph-io/badger/blob/main/badger/cmd/root.go"
click node_backupcmd "https://github.com/dgraph-io/badger/blob/main/badger/cmd/backup.go"
click node_restorecmd "https://github.com/dgraph-io/badger/blob/main/badger/cmd/restore.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_db,node_txn,node_batch,node_iterator,node_stream,node_options toneBlue
class node_memtable,node_vlog,node_lsm,node_levelhandler,node_table,node_compaction,node_manifest toneAmber
class node_backup,node_cli,node_backupcmd,node_restorecmd toneMint
class node_skiplists,node_valueencoding toneRose
class node_application toneIndigo
```

## Components

### Database API

- [DB lifecycle](https://github.com/dgraph-io/badger/blob/main/db.go): `db.go`
- [Transactions](https://github.com/dgraph-io/badger/blob/main/txn.go): `txn.go`
- [Write batches](https://github.com/dgraph-io/badger/blob/main/batch.go): `batch.go`
- [KV iterators](https://github.com/dgraph-io/badger/blob/main/iterator.go): `iterator.go`
- [Stream API](https://github.com/dgraph-io/badger/blob/main/stream.go): `stream.go`
- [DB options](https://github.com/dgraph-io/badger/blob/main/options.go): `options.go`

### Storage Engine

- [Memtables](https://github.com/dgraph-io/badger/blob/main/memtable.go): `memtable.go`
- [Value log](https://github.com/dgraph-io/badger/blob/main/value.go): `value.go`
- [LSM levels](https://github.com/dgraph-io/badger/blob/main/levels.go): `levels.go`
- [Level tables](https://github.com/dgraph-io/badger/blob/main/level_handler.go): `level_handler.go`
- [Sorted tables](https://github.com/dgraph-io/badger/blob/main/table/table.go): `table/table.go`
- [Compaction](https://github.com/dgraph-io/badger/blob/main/compaction.go): `compaction.go`
- [Manifest](https://github.com/dgraph-io/badger/blob/main/manifest.go): `manifest.go`

### Maintenance and Tools

- [Backup and restore](https://github.com/dgraph-io/badger/blob/main/backup.go): `backup.go`
- [Admin CLI](https://github.com/dgraph-io/badger/blob/main/badger/cmd/root.go): `badger/cmd/root.go`
- [Backup command](https://github.com/dgraph-io/badger/blob/main/badger/cmd/backup.go): `badger/cmd/backup.go`
- [Restore command](https://github.com/dgraph-io/badger/blob/main/badger/cmd/restore.go): `badger/cmd/restore.go`

### Internal Structures

- [Skip lists](https://github.com/dgraph-io/badger/blob/main/skl/skl.go): `skl/skl.go`
- [Value encoding](https://github.com/dgraph-io/badger/blob/main/structs.go): `structs.go`

### Other components

- **Application**

## Connections

- Application → DB lifecycle: opens DB
- Application → Transactions: starts transactions
- Application → KV iterators: iterates keys
- Application → Stream API: uses streaming
- DB lifecycle → DB options: uses options
- Transactions → Memtables: writes keys
- Transactions → Value log: stores values
- Transactions → LSM levels: reads keys
- KV iterators → LSM levels: scans keys
- LSM levels → Level tables: manages levels
- Level tables → Sorted tables: reads tables
- Compaction → Sorted tables: rewrites tables
- Compaction → Manifest: records changes
- Memtables → Skip lists: indexes entries
- Transactions → Value encoding: encodes values
- Admin CLI → Backup command: dispatches
- Admin CLI → Restore command: dispatches
- Backup command → Backup and restore: creates backup
- Restore command → Backup and restore: restores data