# tejas-techstack/huus architecture

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

- Interactive diagram: https://gitdiagram.com/tejas-techstack/huus
- Repository: https://github.com/tejas-techstack/huus

## Overview

Huus is a persistent, integer-oriented B+ tree key-value store. The primary workflow starts at the CLI, reads REPL commands, parses them, dispatches CRUD operations, and persists tree pages to a database file. The engine also includes split and deletion-rebalancing logic, stack-based traversal support, and binary encoding. Several engine relationships are documented in the README, but their call sites were not sampled; those links are shown as documented rather than inferred from imports. The command-line UPDATE branch currently parses input without updating the tree.

Main entry points: [`internal/engine/storage.go`](https://github.com/tejas-techstack/huus/blob/main/internal/engine/storage.go) (Storage coordinator), [`internal/engine/crud.go`](https://github.com/tejas-techstack/huus/blob/main/internal/engine/crud.go) (CRUD API), [`internal/engine/repl.go`](https://github.com/tejas-techstack/huus/blob/main/internal/engine/repl.go) (REPL loop), [`internal/engine/delete_helpers.go`](https://github.com/tejas-techstack/huus/blob/main/internal/engine/delete_helpers.go) (Delete rebalancing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_entry["CLI entry<br/>[main.go]"]
  node_repl["REPL loop<br/>[repl.go]"]
  node_parser["Command parser<br/>[lychee.go]"]
end

subgraph group_tree["B+ tree engine"]
  node_crud["CRUD API<br/>[crud.go]"]
  node_search["Tree search<br/>[helpers.go]"]
  node_insert["Insertion logic<br/>[insert_helpers.go]"]
  node_delete["Delete rebalancing<br/>[delete_helpers.go]"]
  node_split["Node splitting<br/>[split.go]"]
  node_stack["Traversal stack<br/>[btstack.go]"]
  node_model["Tree structures<br/>[types.go]"]
  node_config["Tree initialization<br/>[config.go]"]
end

subgraph group_disk["Persistence"]
  node_storage["Storage coordinator<br/>[storage.go]"]
  node_pager["Page management<br/>[pager.go]"]
  node_encoding["Binary encoding<br/>[encoding.go]"]
  node_database[("Database file")]
end

node_user(("CLI user"))

node_user -->|"starts"| node_entry
node_entry -->|"starts loop"| node_repl
node_repl -->|"parses commands"| node_parser
node_repl -->|"dispatches operations"| node_crud
node_crud -.->|"searches tree"| node_search
node_crud -.->|"inserts values"| node_insert
node_crud -.->|"deletes keys"| node_delete
node_insert -.->|"splits nodes"| node_split
node_delete -->|"tracks ancestors"| node_stack
node_split -->|"updates nodes"| node_model
node_delete -->|"loads and updates"| node_storage
node_split -->|"loads and updates"| node_storage
node_config -.->|"opens storage"| node_storage
node_storage -->|"uses page operations"| node_pager
node_storage -->|"encodes metadata"| node_encoding
node_storage -->|"reads and writes"| node_database
node_crud -.->|"persists tree"| node_storage

click node_entry "https://github.com/tejas-techstack/huus/blob/main/cmd/main.go"
click node_repl "https://github.com/tejas-techstack/huus/blob/main/internal/engine/repl.go"
click node_parser "https://github.com/tejas-techstack/huus/blob/main/internal/parser/lychee.go"
click node_crud "https://github.com/tejas-techstack/huus/blob/main/internal/engine/crud.go"
click node_search "https://github.com/tejas-techstack/huus/blob/main/internal/engine/helpers.go"
click node_insert "https://github.com/tejas-techstack/huus/blob/main/internal/engine/insert_helpers.go"
click node_delete "https://github.com/tejas-techstack/huus/blob/main/internal/engine/delete_helpers.go"
click node_split "https://github.com/tejas-techstack/huus/blob/main/internal/engine/split.go"
click node_stack "https://github.com/tejas-techstack/huus/blob/main/internal/engine/btstack.go"
click node_model "https://github.com/tejas-techstack/huus/blob/main/internal/engine/types.go"
click node_config "https://github.com/tejas-techstack/huus/blob/main/internal/engine/config.go"
click node_storage "https://github.com/tejas-techstack/huus/blob/main/internal/engine/storage.go"
click node_pager "https://github.com/tejas-techstack/huus/blob/main/internal/engine/pager.go"
click node_encoding "https://github.com/tejas-techstack/huus/blob/main/internal/engine/encoding.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_entry,node_repl,node_parser,node_user toneBlue
class node_crud,node_search,node_insert,node_delete,node_split,node_stack,node_model,node_config toneAmber
class node_storage,node_pager,node_encoding,node_database toneMint
```

## Components

### User interface

- [CLI entry](https://github.com/tejas-techstack/huus/blob/main/cmd/main.go): `cmd/main.go`
- [REPL loop](https://github.com/tejas-techstack/huus/blob/main/internal/engine/repl.go): `internal/engine/repl.go`
- [Command parser](https://github.com/tejas-techstack/huus/blob/main/internal/parser/lychee.go): `internal/parser/lychee.go`

### B+ tree engine

- [CRUD API](https://github.com/tejas-techstack/huus/blob/main/internal/engine/crud.go): `internal/engine/crud.go`
- [Tree search](https://github.com/tejas-techstack/huus/blob/main/internal/engine/helpers.go): `internal/engine/helpers.go`
- [Insertion logic](https://github.com/tejas-techstack/huus/blob/main/internal/engine/insert_helpers.go): `internal/engine/insert_helpers.go`
- [Delete rebalancing](https://github.com/tejas-techstack/huus/blob/main/internal/engine/delete_helpers.go): `internal/engine/delete_helpers.go`
- [Node splitting](https://github.com/tejas-techstack/huus/blob/main/internal/engine/split.go): `internal/engine/split.go`
- [Traversal stack](https://github.com/tejas-techstack/huus/blob/main/internal/engine/btstack.go): `internal/engine/btstack.go`
- [Tree structures](https://github.com/tejas-techstack/huus/blob/main/internal/engine/types.go): `internal/engine/types.go`
- [Tree initialization](https://github.com/tejas-techstack/huus/blob/main/internal/engine/config.go): `internal/engine/config.go`

### Persistence

- [Storage coordinator](https://github.com/tejas-techstack/huus/blob/main/internal/engine/storage.go): `internal/engine/storage.go`
- [Page management](https://github.com/tejas-techstack/huus/blob/main/internal/engine/pager.go): `internal/engine/pager.go`
- [Binary encoding](https://github.com/tejas-techstack/huus/blob/main/internal/engine/encoding.go): `internal/engine/encoding.go`
- **Database file**

### Other components

- **CLI user**

## Connections

- CLI user → CLI entry: starts (evidence: `README.md`)
- CLI entry → REPL loop: starts loop (evidence: `cmd/main.go`)
- REPL loop → Command parser: parses commands (evidence: `internal/engine/repl.go`)
- REPL loop → CRUD API: dispatches operations (evidence: `internal/engine/repl.go`)
- CRUD API → Tree search: searches tree
- CRUD API → Insertion logic: inserts values
- CRUD API → Delete rebalancing: deletes keys
- Insertion logic → Node splitting: splits nodes
- Delete rebalancing → Traversal stack: tracks ancestors (evidence: `internal/engine/delete_helpers.go`)
- Node splitting → Tree structures: updates nodes (evidence: `internal/engine/split.go`)
- Delete rebalancing → Storage coordinator: loads and updates (evidence: `internal/engine/delete_helpers.go`)
- Node splitting → Storage coordinator: loads and updates (evidence: `internal/engine/split.go`)
- Tree initialization → Storage coordinator: opens storage
- Storage coordinator → Page management: uses page operations (evidence: `internal/engine/pager.go`)
- Storage coordinator → Binary encoding: encodes metadata (evidence: `internal/engine/storage.go`)
- Storage coordinator → Database file: reads and writes (evidence: `internal/engine/storage.go`)
- CRUD API → Storage coordinator: persists tree
