# za-warka/zawarka_db architecture

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

- Interactive diagram: https://gitdiagram.com/za-warka/zawarka_db
- Repository: https://github.com/za-warka/zawarka_db

## Overview

#### Purpose and Entry Points
ZaWarka-DB is a C++20 embeddable, in-memory key-value database implementing a Valkey/Redis-like command subset. The reusable database library is assembled under `src/CMakeLists.txt`; the interactive CLI executable starts at `bin/main.cpp` and is built via `bin/CMakeLists.txt`.

#### Request Execution Pipeline
The CLI reads user input, tokenizes/parses commands and typed values, then sends them to the processor. `src/parser/cli_parser/cli_parser.cpp` handles interactive input; `src/parser/command_parser/command_parser.cpp` identifies command syntax; `src/parser/value_parser/value_parser.cpp` parses arguments. `src/processor/processor.cpp` coordinates dispatch and returns formatted results through `src/response/response.cpp`.

#### Command Dispatch Boundary
Commands implement a common command abstraction at `src/command/icommand.hpp`. `src/command/command_factory_.cpp` maps parsed command names to concrete implementations, making command registration and syntax/behavior expansion localized to the command layer. The processor/factory boundary separates protocol-level parsing from storage mutation and query behavior.

#### Engine, Storage, and Key Lifecycle
`src/engine/engine.cpp` is the primary database-facing orchestration layer. It owns or mediates operations against `src/storage/storage.cpp`, which maintains the in-memory keyspace. Key metadata, including expiration and memory-relevant bookkeeping, is represented by `src/cell/cell.cpp`; common commands such as expiry, deletion, lookup, database flush, and key enumeration reside in `src/command/common/expire.cpp`, `src/command/common/del.cpp`, and `src/command/common/keys.cpp`.

#### Typed Value Model
A single heterogeneous value interface is defined in `src/value/value.hpp`, with concrete string, list, set, and geo representations in `src/value/string_value.cpp`, `src/value/list_value.cpp`, and `src/value/geo_value.cpp`. The design described by the README uses C++ variants/visitation to operate safely across these types. Commands must preserve type boundaries: string operations are in `src/command/string`, list operations in `src/command/list`, set operations in `src/command/set_type`, and geospatial operations in `src/command/geo`.

#### Resource Controls and Semantics
Storage is memory-resident only; no persistence, network server, or external database service is represented. Memory limits are configured through `src/command/common/config.cpp`, inspected by `src/command/common/mem_usage.cpp`, and intended to reject growth that would exceed `maxmemory`. TTL behavior is exposed by `src/command/common/expire.cpp` and `src/command/common/ttl.cpp`; expiration is therefore a storage/cell lifecycle concern, not merely command parsing.

#### Build and Delivery
CMake is the build/runtime integration mechanism (`CMakeLists.txt`, `src/CMakeLists.txt`). The material runtime is a local C++ CLI or embedded C++ library, using the standard library and in-process memory. CI/CD is defined in `.github/workflows/cicd.yml`.

Main entry points: [`src/processor/processor.cpp`](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/processor/processor.cpp) (Request processor), [`src/engine/engine.cpp`](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/engine/engine.cpp) (Database engine), [`src/value/value.hpp`](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/value.hpp) (Heterogeneous value), [`src/storage/storage.cpp`](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/storage/storage.cpp) (Keyspace storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI Runtime"]
  node_cli["Interactive CLI<br/>C++ executable<br/>[main.cpp]"]
  node_cli_parser["CLI parser<br/>input parser<br/>[cli_parser.cpp]"]
  node_command_parser["Command parser<br/>syntax parser<br/>[command_parser.cpp]"]
  node_value_parser["Value parser<br/>argument parser<br/>[value_parser.cpp]"]
  node_processor["Request processor<br/>dispatcher<br/>[processor.cpp]"]
  node_response["Response formatter<br/>response layer<br/>[response.cpp]"]
end

subgraph group_commands["Command Layer"]
  node_command_interface["Command abstraction<br/>command interface<br/>[icommand.hpp]"]
  node_command_factory{{"Command factory<br/>command registry"}}
  node_typed_commands["Typed command families<br/>string/list/set/geo commands"]
  node_key_lifecycle_commands["Key lifecycle commands<br/>expiry and key commands<br/>[expire.cpp]"]
end

subgraph group_data["In-Memory Database"]
  node_engine["Database engine<br/>orchestration layer<br/>[engine.cpp]"]
  node_storage[("Keyspace storage<br/>in-memory store<br/>[storage.cpp]")]
  node_cell["Key cell metadata<br/>key lifecycle metadata<br/>[cell.cpp]"]
  node_value_interface["Heterogeneous value<br/>value interface<br/>[value.hpp]"]
  node_string_value["String value<br/>concrete value<br/>[string_value.cpp]"]
  node_list_value["List value<br/>concrete value<br/>[list_value.cpp]"]
  node_geo_value["Geo value<br/>concrete value<br/>[geo_value.cpp]"]
end

subgraph group_delivery["Build &amp; Delivery"]
  node_cmake["CMake build<br/>build integration<br/>[CMakeLists.txt]"]
  node_ci["CI/CD workflow<br/>automation<br/>[cicd.yml]"]
end

node_cli -->|"reads input"| node_cli_parser
node_cli_parser -->|"tokenized command"| node_command_parser
node_command_parser -->|"argument syntax"| node_value_parser
node_value_parser -->|"typed request"| node_processor
node_processor -->|"resolves command"| node_command_factory
node_command_factory -->|"creates implementations"| node_command_interface
node_typed_commands -->|"implements"| node_command_interface
node_key_lifecycle_commands -->|"implements"| node_command_interface
node_processor -->|"executes request"| node_engine
node_engine -->|"reads and mutates"| node_storage
node_typed_commands -->|"type operations"| node_engine
node_key_lifecycle_commands -->|"lifecycle operations"| node_engine
node_storage -->|"key metadata"| node_cell
node_storage -->|"stores values"| node_value_interface
node_string_value -->|"concrete type"| node_value_interface
node_list_value -->|"concrete type"| node_value_interface
node_geo_value -->|"concrete type"| node_value_interface
node_processor -->|"formats result"| node_response
node_response -->|"prints result"| node_cli
node_cmake -->|"builds"| node_cli
node_ci -->|"runs build"| node_cmake

click node_cli "https://github.com/za-warka/zawarka_db/blob/deadline_0/bin/main.cpp"
click node_cli_parser "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/parser/cli_parser/cli_parser.cpp"
click node_command_parser "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/parser/command_parser/command_parser.cpp"
click node_value_parser "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/parser/value_parser/value_parser.cpp"
click node_processor "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/processor/processor.cpp"
click node_response "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/response/response.cpp"
click node_command_interface "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/command/icommand.hpp"
click node_command_factory "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/command/command_factory_.cpp"
click node_typed_commands "https://github.com/za-warka/zawarka_db/tree/deadline_0/src/command/string"
click node_key_lifecycle_commands "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/command/common/expire.cpp"
click node_engine "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/engine/engine.cpp"
click node_storage "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/storage/storage.cpp"
click node_cell "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/cell/cell.cpp"
click node_value_interface "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/value.hpp"
click node_string_value "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/string_value.cpp"
click node_list_value "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/list_value.cpp"
click node_geo_value "https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/geo_value.cpp"
click node_cmake "https://github.com/za-warka/zawarka_db/blob/deadline_0/CMakeLists.txt"
click node_ci "https://github.com/za-warka/zawarka_db/blob/deadline_0/.github/workflows/cicd.yml"

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_cli_parser,node_command_parser,node_value_parser,node_processor,node_response toneBlue
class node_command_interface,node_command_factory,node_typed_commands,node_key_lifecycle_commands toneAmber
class node_engine,node_storage,node_cell,node_value_interface,node_string_value,node_list_value,node_geo_value toneMint
class node_cmake,node_ci toneRose
```

## Components

### CLI Runtime

- [Interactive CLI](https://github.com/za-warka/zawarka_db/blob/deadline_0/bin/main.cpp): C++ executable · Reads commands from the local terminal. · `bin/main.cpp`
- [CLI parser](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/parser/cli_parser/cli_parser.cpp): input parser · `src/parser/cli_parser/cli_parser.cpp`
- [Command parser](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/parser/command_parser/command_parser.cpp): syntax parser · `src/parser/command_parser/command_parser.cpp`
- [Value parser](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/parser/value_parser/value_parser.cpp): argument parser · `src/parser/value_parser/value_parser.cpp`
- [Request processor](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/processor/processor.cpp): dispatcher · Coordinates parsed requests and formatted results. · `src/processor/processor.cpp`
- [Response formatter](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/response/response.cpp): response layer · `src/response/response.cpp`

### Command Layer

- [Command abstraction](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/command/icommand.hpp): command interface · `src/command/icommand.hpp`
- [Command factory](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/command/command_factory_.cpp): command registry · Maps parsed names to concrete command implementations. · `src/command/command_factory_.cpp`
- [Typed command families](https://github.com/za-warka/zawarka_db/tree/deadline_0/src/command/string): string/list/set/geo commands · Operations preserve value-type boundaries. · `src/command/string`
- [Key lifecycle commands](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/command/common/expire.cpp): expiry and key commands · Deletion, enumeration, expiry, TTL, and memory controls. · `src/command/common/expire.cpp`

### In-Memory Database

- [Database engine](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/engine/engine.cpp): orchestration layer · Primary database-facing command backend. · `src/engine/engine.cpp`
- [Keyspace storage](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/storage/storage.cpp): in-memory store · Maintains the process-local keyspace. · `src/storage/storage.cpp`
- [Key cell metadata](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/cell/cell.cpp): key lifecycle metadata · Tracks expiration and memory-relevant bookkeeping. · `src/cell/cell.cpp`
- [Heterogeneous value](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/value.hpp): value interface · `src/value/value.hpp`
- [String value](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/string_value.cpp): concrete value · `src/value/string_value.cpp`
- [List value](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/list_value.cpp): concrete value · `src/value/list_value.cpp`
- [Geo value](https://github.com/za-warka/zawarka_db/blob/deadline_0/src/value/geo_value.cpp): concrete value · `src/value/geo_value.cpp`

### Build & Delivery

- [CMake build](https://github.com/za-warka/zawarka_db/blob/deadline_0/CMakeLists.txt): build integration · Builds the reusable library and CLI executable. · `CMakeLists.txt`
- [CI/CD workflow](https://github.com/za-warka/zawarka_db/blob/deadline_0/.github/workflows/cicd.yml): automation · `.github/workflows/cicd.yml`

## Connections

- Interactive CLI → CLI parser: reads input
- CLI parser → Command parser: tokenized command
- Command parser → Value parser: argument syntax
- Value parser → Request processor: typed request
- Request processor → Command factory: resolves command
- Command factory → Command abstraction: creates implementations
- Typed command families → Command abstraction: implements
- Key lifecycle commands → Command abstraction: implements
- Request processor → Database engine: executes request
- Database engine → Keyspace storage: reads and mutates
- Typed command families → Database engine: type operations
- Key lifecycle commands → Database engine: lifecycle operations
- Keyspace storage → Key cell metadata: key metadata
- Keyspace storage → Heterogeneous value: stores values
- String value → Heterogeneous value: concrete type
- List value → Heterogeneous value: concrete type
- Geo value → Heterogeneous value: concrete type
- Request processor → Response formatter: formats result
- Response formatter → Interactive CLI: prints result
- CMake build → Interactive CLI: builds
- CI/CD workflow → CMake build: runs build