How za-warka/zawarka_db works
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: processor.cpp Request processor · engine.cpp Database engine · value.hpp Heterogeneous value · storage.cpp Keyspace storage
Components 19
CLI Runtime
- Interactive CLI · Reads commands from the local terminal.
bin/main.cpp - CLI parser
src/parser/cli_parser/cli_parser.cpp - Command parser
src/parser/command_parser/command_parser.cpp - Value parser
src/parser/value_parser/value_parser.cpp - Request processor · Coordinates parsed requests and formatted results.
src/processor/processor.cpp - Response formatter
src/response/response.cpp
Command Layer
- Command abstraction
src/command/icommand.hpp - Command factory · Maps parsed names to concrete command implementations.
src/command/command_factory_.cpp - Typed command families · Operations preserve value-type boundaries.
src/command/string - Key lifecycle commands · Deletion, enumeration, expiry, TTL, and memory controls.
src/command/common/expire.cpp
In-Memory Database
- Database engine · Primary database-facing command backend.
src/engine/engine.cpp - Keyspace storage · Maintains the process-local keyspace.
src/storage/storage.cpp - Key cell metadata · Tracks expiration and memory-relevant bookkeeping.
src/cell/cell.cpp - Heterogeneous value
src/value/value.hpp - String value
src/value/string_value.cpp - List value
src/value/list_value.cpp - Geo value
src/value/geo_value.cpp
Build & Delivery
- CMake build · Builds the reusable library and CLI executable.
CMakeLists.txt - CI/CD workflow
.github/workflows/cicd.yml
Connections 21
- 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