# typicode/lowdb architecture

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

- Interactive diagram: https://gitdiagram.com/typicode/lowdb
- Repository: https://github.com/typicode/lowdb

## Overview

lowdb is a type-safe embedded JSON database for Node.js and browsers. A caller creates a database through a preset or pairs a Low/LowSync instance with an adapter, reads data, mutates the plain JavaScript value, then writes or calls update. Storage options include memory, browser storage, and Node files; Node’s DataFile layer supports custom serialization through TextFile. The graph follows documented behavior and sampled source; unsampled capabilities are represented only where the README supports them.

Main entry points: [`src/core/Low.ts`](https://github.com/typicode/lowdb/blob/main/src/core/Low.ts) (Low / LowSync), [`src/presets/node.ts`](https://github.com/typicode/lowdb/blob/main/src/presets/node.ts) (Node Presets), [`src/presets/browser.ts`](https://github.com/typicode/lowdb/blob/main/src/presets/browser.ts) (Browser Presets), [`src/adapters/browser/WebStorage.ts`](https://github.com/typicode/lowdb/blob/main/src/adapters/browser/WebStorage.ts) (WebStorage Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Database API"]
  node_low["Low / LowSync<br/>[Low.ts]"]
end

subgraph group_presets["Convenience Presets"]
  node_nodepreset["Node Presets<br/>[node.ts]"]
  node_browserpreset["Browser Presets<br/>[browser.ts]"]
end

subgraph group_adapters["Storage Adapters"]
  node_memory[("Memory Adapter<br/>[Memory.ts]")]
  node_webstorage[("WebStorage Adapter<br/>[WebStorage.ts]")]
  node_localstorage["LocalStorage Adapter<br/>[LocalStorage.ts]"]
  node_sessionstorage["SessionStorage Adapter<br/>[SessionStorage.ts]"]
end

subgraph group_nodefiles["Node File Layers"]
  node_jsonfile["JSON File Adapter<br/>[JSONFile.ts]"]
  node_datafile["DataFile Adapter<br/>[DataFile.ts]"]
  node_textfile["TextFile Adapter<br/>[TextFile.ts]"]
end

node_caller(("Application"))
node_browserstore[("Browser Storage")]
node_filesystem[("Local Filesystem")]
node_steno["Atomic Writer"]
node_customformats["Custom Formats"]

node_caller -->|"creates via"| node_nodepreset
node_caller -->|"creates via"| node_browserpreset
node_caller -->|"reads and updates"| node_low
node_nodepreset -->|"constructs and reads"| node_low
node_browserpreset -->|"constructs and reads"| node_low
node_nodepreset -->|"selects in tests"| node_memory
node_nodepreset -->|"selects otherwise"| node_jsonfile
node_browserpreset -->|"constructs"| node_localstorage
node_browserpreset -->|"constructs"| node_sessionstorage
node_low -->|"reads and writes"| node_memory
node_low -->|"reads and writes"| node_webstorage
node_low -->|"reads and writes"| node_jsonfile
node_localstorage -->|"extends"| node_webstorage
node_sessionstorage -->|"extends"| node_webstorage
node_webstorage -->|"gets and sets values"| node_browserstore
node_jsonfile -->|"configures serialization"| node_datafile
node_datafile -->|"reads and writes text"| node_textfile
node_textfile -->|"reads and writes files"| node_filesystem
node_textfile -->|"uses async writer"| node_steno
node_caller -.->|"may provide"| node_customformats
node_customformats -.->|"supplies parse and stringify"| node_datafile

click node_low "https://github.com/typicode/lowdb/blob/main/src/core/Low.ts"
click node_nodepreset "https://github.com/typicode/lowdb/blob/main/src/presets/node.ts"
click node_browserpreset "https://github.com/typicode/lowdb/blob/main/src/presets/browser.ts"
click node_memory "https://github.com/typicode/lowdb/blob/main/src/adapters/Memory.ts"
click node_webstorage "https://github.com/typicode/lowdb/blob/main/src/adapters/browser/WebStorage.ts"
click node_localstorage "https://github.com/typicode/lowdb/blob/main/src/adapters/browser/LocalStorage.ts"
click node_sessionstorage "https://github.com/typicode/lowdb/blob/main/src/adapters/browser/SessionStorage.ts"
click node_jsonfile "https://github.com/typicode/lowdb/blob/main/src/adapters/node/JSONFile.ts"
click node_datafile "https://github.com/typicode/lowdb/blob/main/src/adapters/node/DataFile.ts"
click node_textfile "https://github.com/typicode/lowdb/blob/main/src/adapters/node/TextFile.ts"

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_low toneBlue
class node_nodepreset,node_browserpreset,node_browserstore,node_filesystem toneAmber
class node_memory,node_webstorage,node_localstorage,node_sessionstorage toneMint
class node_jsonfile,node_datafile,node_textfile toneRose
class node_caller,node_steno,node_customformats toneIndigo
```

## Components

### Database API

- [Low / LowSync](https://github.com/typicode/lowdb/blob/main/src/core/Low.ts): `src/core/Low.ts`

### Convenience Presets

- [Node Presets](https://github.com/typicode/lowdb/blob/main/src/presets/node.ts): `src/presets/node.ts`
- [Browser Presets](https://github.com/typicode/lowdb/blob/main/src/presets/browser.ts): `src/presets/browser.ts`

### Storage Adapters

- [Memory Adapter](https://github.com/typicode/lowdb/blob/main/src/adapters/Memory.ts): `src/adapters/Memory.ts`
- [WebStorage Adapter](https://github.com/typicode/lowdb/blob/main/src/adapters/browser/WebStorage.ts): `src/adapters/browser/WebStorage.ts`
- [LocalStorage Adapter](https://github.com/typicode/lowdb/blob/main/src/adapters/browser/LocalStorage.ts): `src/adapters/browser/LocalStorage.ts`
- [SessionStorage Adapter](https://github.com/typicode/lowdb/blob/main/src/adapters/browser/SessionStorage.ts): `src/adapters/browser/SessionStorage.ts`

### Node File Layers

- [JSON File Adapter](https://github.com/typicode/lowdb/blob/main/src/adapters/node/JSONFile.ts): `src/adapters/node/JSONFile.ts`
- [DataFile Adapter](https://github.com/typicode/lowdb/blob/main/src/adapters/node/DataFile.ts): `src/adapters/node/DataFile.ts`
- [TextFile Adapter](https://github.com/typicode/lowdb/blob/main/src/adapters/node/TextFile.ts): `src/adapters/node/TextFile.ts`

### Other components

- **Application**
- **Browser Storage**
- **Local Filesystem**
- **Atomic Writer**
- **Custom Formats**

## Connections

- Application → Node Presets: creates via (evidence: `README.md`)
- Application → Browser Presets: creates via (evidence: `README.md`)
- Application → Low / LowSync: reads and updates (evidence: `README.md`)
- Node Presets → Low / LowSync: constructs and reads (evidence: `src/presets/node.ts`)
- Browser Presets → Low / LowSync: constructs and reads (evidence: `src/presets/browser.ts`)
- Node Presets → Memory Adapter: selects in tests (evidence: `src/presets/node.ts`)
- Node Presets → JSON File Adapter: selects otherwise (evidence: `src/presets/node.ts`)
- Browser Presets → LocalStorage Adapter: constructs (evidence: `src/presets/browser.ts`)
- Browser Presets → SessionStorage Adapter: constructs (evidence: `src/presets/browser.ts`)
- Low / LowSync → Memory Adapter: reads and writes (evidence: `src/core/Low.ts`)
- Low / LowSync → WebStorage Adapter: reads and writes (evidence: `src/core/Low.ts`)
- Low / LowSync → JSON File Adapter: reads and writes (evidence: `src/core/Low.ts`)
- LocalStorage Adapter → WebStorage Adapter: extends (evidence: `src/adapters/browser/LocalStorage.ts`)
- SessionStorage Adapter → WebStorage Adapter: extends (evidence: `src/adapters/browser/SessionStorage.ts`)
- WebStorage Adapter → Browser Storage: gets and sets values (evidence: `src/adapters/browser/WebStorage.ts`)
- JSON File Adapter → DataFile Adapter: configures serialization (evidence: `src/adapters/node/JSONFile.ts`)
- DataFile Adapter → TextFile Adapter: reads and writes text (evidence: `src/adapters/node/DataFile.ts`)
- TextFile Adapter → Local Filesystem: reads and writes files (evidence: `src/adapters/node/TextFile.ts`)
- TextFile Adapter → Atomic Writer: uses async writer (evidence: `src/adapters/node/TextFile.ts`)
- Application → Custom Formats: may provide (evidence: `README.md`)
- Custom Formats → DataFile Adapter: supplies parse and stringify (evidence: `README.md`)
