# rh211-sys/hashi-db architecture

> Architecture diagram of the GitHub repository rh211-sys/hashi-db, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rh211-sys/hashi-db
- Repository: https://github.com/rh211-sys/hashi-db

## Overview

This is an asynchronous, file-backed memo database. Callers use Controller to add, query, modify, and delete typed values; Cache handles in-memory lookup, expiry, eviction, and dirty state, while Disk provides persistence and compaction. TaskThreads supplies the read, write, and disk execution lanes. The type registry connects user-defined values to cereal binary serialization. The graph reflects documented APIs and visible dependency wiring; several detailed disk and cache behaviors are described in excerpts but their full implementations were not sampled.

Main entry points: [`project/data_memo_level/controller/controller.cpp`](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/controller/controller.cpp) (Controller), [`project/data_memo_level/cache/cache.cpp`](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/cache/cache.cpp) (Cache Operations), [`project/data_memo_level/disk/disk.cpp`](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/disk/disk.cpp) (Disk Storage), [`project/data_memo_level/data_type.h`](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/data_type.h) (Value Types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Database API"]
  node_controller["Controller<br/>[controller.cpp]"]
end

subgraph group_cache["Cache Management"]
  node_cache_ops["Cache Operations<br/>[cache.cpp]"]
  node_cache_state[("Cache State<br/>[cache.h]")]
  node_rw_lock["Write-Pref Lock<br/>[writePrefMutex.cpp]"]
end

subgraph group_storage["Persistence"]
  node_disk[("Disk Storage<br/>[disk.cpp]")]
  node_disk_index[("Disk Index<br/>[disk.h]")]
end

subgraph group_runtime["Async Runtime"]
  node_workers["Task Threads<br/>[taskThreads.h]"]
end

subgraph group_types["Types and Serialization"]
  node_data_types["Value Types<br/>[data_type.h]"]
  node_protocol["Result Codes<br/>[protocol.h]"]
  node_cereal["Binary Archives<br/>[binary.hpp]"]
end

node_caller(("Application"))

node_caller -->|"calls API"| node_controller
node_controller -->|"delegates operations"| node_cache_ops
node_controller -->|"flushes data"| node_disk
node_controller -->|"submits flush"| node_workers
node_controller -->|"binds dependencies"| node_cache_state
node_controller -->|"sets cache link"| node_disk
node_cache_ops -->|"updates state"| node_cache_state
node_cache_ops -->|"checks disk index"| node_disk
node_cache_ops -->|"dispatches tasks"| node_workers
node_cache_ops -->|"synchronizes access"| node_rw_lock
node_disk -->|"maintains index"| node_disk_index
node_data_types -->|"uses codes"| node_protocol
node_data_types -->|"serializes values"| node_cereal

click node_controller "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/controller/controller.cpp"
click node_cache_ops "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/cache/cache.cpp"
click node_cache_state "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/cache/cache.h"
click node_rw_lock "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/common/writePrefMutex.cpp"
click node_disk "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/disk/disk.cpp"
click node_disk_index "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/disk/disk.h"
click node_workers "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/controller/taskThreads.h"
click node_data_types "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/data_type.h"
click node_protocol "https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/protocol.h"
click node_cereal "https://github.com/rh211-sys/hashi-db/blob/design_period/project/third_party_lib/cereal_lib/include/cereal/archives/binary.hpp"

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_controller toneBlue
class node_cache_ops,node_cache_state,node_rw_lock toneAmber
class node_disk,node_disk_index toneMint
class node_workers toneRose
class node_data_types,node_protocol,node_cereal,node_caller toneIndigo
```

## Components

### Database API

- [Controller](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/controller/controller.cpp): `project/data_memo_level/controller/controller.cpp`

### Cache Management

- [Cache Operations](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/cache/cache.cpp): `project/data_memo_level/cache/cache.cpp`
- [Cache State](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/cache/cache.h): `project/data_memo_level/cache/cache.h`
- [Write-Pref Lock](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/common/writePrefMutex.cpp): `project/data_memo_level/common/writePrefMutex.cpp`

### Persistence

- [Disk Storage](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/disk/disk.cpp): `project/data_memo_level/disk/disk.cpp`
- [Disk Index](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/disk/disk.h): `project/data_memo_level/disk/disk.h`

### Async Runtime

- [Task Threads](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/controller/taskThreads.h): `project/data_memo_level/controller/taskThreads.h`

### Types and Serialization

- [Value Types](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/data_type.h): `project/data_memo_level/data_type.h`
- [Result Codes](https://github.com/rh211-sys/hashi-db/blob/design_period/project/data_memo_level/protocol.h): `project/data_memo_level/protocol.h`
- [Binary Archives](https://github.com/rh211-sys/hashi-db/blob/design_period/project/third_party_lib/cereal_lib/include/cereal/archives/binary.hpp): `project/third_party_lib/cereal_lib/include/cereal/archives/binary.hpp`

### Other components

- **Application**

## Connections

- Application → Controller: calls API
- Controller → Cache Operations: delegates operations (evidence: `project/data_memo_level/controller/controller.cpp`)
- Controller → Disk Storage: flushes data (evidence: `project/data_memo_level/controller/controller.cpp`)
- Controller → Task Threads: submits flush (evidence: `project/data_memo_level/controller/controller.cpp`)
- Controller → Cache State: binds dependencies (evidence: `project/data_memo_level/controller/controller.cpp`)
- Controller → Disk Storage: sets cache link (evidence: `project/data_memo_level/controller/controller.cpp`)
- Cache Operations → Cache State: updates state (evidence: `project/data_memo_level/cache/cache.h`)
- Cache Operations → Disk Storage: checks disk index
- Cache Operations → Task Threads: dispatches tasks
- Cache Operations → Write-Pref Lock: synchronizes access
- Disk Storage → Disk Index: maintains index (evidence: `project/data_memo_level/disk/disk.h`)
- Value Types → Result Codes: uses codes (evidence: `project/data_memo_level/data_type.h`)
- Value Types → Binary Archives: serializes values (evidence: `project/data_memo_level/data_type.h`)
