# ad4rsh2701/riri architecture

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

- Interactive diagram: https://gitdiagram.com/ad4rsh2701/riri
- Repository: https://github.com/ad4rsh2701/riri

## Overview

1. **Overall shape**
   - RiRi is a **C++23 in-process, static key-value library**, not a server or distributed system.
   - The architecture is split into a **public API layer**, a **core storage engine**, **command wrappers**, a **persistence subsystem**, and a small **CLI entrypoint** used for local interaction/testing.

2. **Public API boundary**
   - The exported surface lives under `include/riri` and is aggregated by `include/riri.hpp`.
   - This is the boundary consumers link against: `Commands`, `Parser`, `Persistence`, `RapidResponse`, `RapidTypes`, and `utils`.
   - The design suggests a deliberate separation between **stable user-facing headers** and implementation details in `src/`.

3. **Data model**
   - The core payload type is `RapidDataType`, a variant-like type supporting **string, integer, double, and bool**.
   - `RapidNode` pairs a string key with a typed value, and most API calls accept either a single node/key-value or a span/array of nodes for bulk operations.
   - This model drives the response and validation system, so typed values are preserved end-to-end rather than normalized into strings.

4. **Command layer**
   - `Commands.hpp` is the main user-level API, exposing CRUD-style operations such as `SET`, `GET`, `DELETE`, `UPDATE`, and `CLEAR`.
   - The implementation is split in `src/commands/*.cpp`, which likely act as thin orchestration wrappers over the core store.
   - The commands support both **single-item “lazy” calls** and **batched bulk calls**, which is a key architectural feature of the library.

5. **Core storage engine**
   - The actual in-memory store appears to be centered on `src/core/DataManager.cpp` and `src/core/MemoryMaps.cpp`.
   - `MemoryMaps` likely owns the key-value containers, while `DataManager` coordinates mutations, reads, and store-level invariants.
   - The presence of `ankerl::unordered_dense` in `src/include/ankerl/` indicates the project uses a **high-performance hash map** implementation for the main store, consistent with the performance focus.

6. **Validation and response flow**
   - A significant part of the architecture is the **response system** in `RapidResponse` and the `status_to_string` helper.
   - Commands do not just return raw values; they return structured responses with **per-operation status codes**, especially for batched requests.
   - This means the data flow is: **input nodes/keys → validation → store operation → typed response/status aggregation**.

7. **Batched operations**
   - Bulk calls are a distinct path in the design, not just repeated single calls.
   - The README and tests show two batched styles: one that returns a capped error batch and one that returns an uncapped mixed result set.
   - This implies the architecture has an internal distinction between **single-status responses** and **collection responses** with partial success handling.

8. **Persistence subsystem**
   - Persistence is already represented structurally, even though the README marks it as future roadmap.
   - `src/core/persistence/{Persistence,Loader,Dumper}.cpp` suggests a classic split: **serialize store state**, **deserialize/recover state**, and a top-level coordinator.
   - The public headers under `include/riri/Persistence.hpp` indicate persistence is intended to be part of the library boundary, even if not yet the primary focus.

9. **CLI boundary**
   - `src/cli/Main.cpp` and `src/cli/Parser.cpp` form a separate executable-facing layer.
   - This is likely a thin adapter that translates command-line input into the same command/data-manager flow used by the library API.
   - The CLI is therefore a consumer of the core library, not a parallel implementation.

10. **Utility and support code**
   - `src/utils/RapidLogger.h` and helpers under `src/utils/helpers` provide cross-cutting support, probably for diagnostics and status formatting.
   - The `include/riri/utils` and `include/riri/utils/Accessors.hpp` headers show some utility functions are part of the public API rather than internal-only helpers.
   - `RiRiMacros.h` suggests compile-time configuration or export/annotation macros are centralized in the internal headers.

11. **Testing architecture**
   - Tests are organized by feature area: commands, response/status behavior, core behavior, and utils.
   - This mirrors the runtime architecture and is a useful signal for drawing the diagram: the project is validated at the **command boundary** and at the **response semantics boundary**, not just at low-level storage functions.
   - The presence of `doctest.h` indicates a lightweight embedded test framework.

12. **Build, packaging, and dependency boundaries**
   - The project is built with **CMake** and targets **Clang++ / C++23**.
   - It is consumed as a library via `FetchContent`, so the repo is structured as a distributable dependency rather than an application.
   - External third-party code is minimal and vendored: `ankerl::unordered_dense` for the hash map and `doctest` for tests.

13. **Practical architecture summary**
   - The main runtime path is: **public API / CLI input → command layer → data manager / memory map → response/status generation**.
   - Optional persistence sits alongside the core store and can serialize or restore state.
   - The important diagram boundary is between the **stable header-only interface** and the **compiled implementation in `src/`**, with commands acting as the main orchestration layer over the in-memory store.

Main entry points: [`include/riri.hpp`](https://github.com/ad4rsh2701/riri/blob/main/include/riri.hpp) (riri.hpp), [`src/core/DataManager.cpp`](https://github.com/ad4rsh2701/riri/blob/main/src/core/DataManager.cpp) (DataManager), [`src/commands/set.cpp`](https://github.com/ad4rsh2701/riri/blob/main/src/commands/set.cpp) (Command impls), [`src/core/MemoryMaps.cpp`](https://github.com/ad4rsh2701/riri/blob/main/src/core/MemoryMaps.cpp) (MemoryMaps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_include_riri_hpp["riri.hpp<br/>umbrella header<br/>[riri.hpp]"]
  node_include_commands["Commands<br/>public API<br/>[Commands.hpp]"]
  node_include_parser["Parser<br/>public API<br/>[Parser.hpp]"]
  node_include_persistence["Persistence<br/>public API<br/>[Persistence.hpp]"]
  node_include_response["RapidResponse<br/>response types<br/>[RapidResponse.hpp]"]
  node_include_types["RapidTypes<br/>data model<br/>[RapidTypes.hpp]"]
  node_include_utils["utils<br/>public helpers<br/>[utils.hpp]"]
  node_include_accessors["Accessors<br/>public helpers<br/>[Accessors.hpp]"]
end

subgraph group_core["Core Engine"]
  node_data_manager["DataManager<br/>store coordinator<br/>[DataManager.cpp]"]
  node_memory_maps[("MemoryMaps<br/>in-memory store<br/>[MemoryMaps.cpp]")]
  node_commands_layer["Command impls<br/>orchestration layer<br/>[set.cpp]"]
  node_persistence_core["Persistence core<br/>persistence coordinator<br/>[Persistence.cpp]"]
  node_loader["Loader<br/>state restore<br/>[Loader.cpp]"]
  node_dumper["Dumper<br/>state snapshot<br/>[Dumper.cpp]"]
end

subgraph group_cli["CLI"]
  node_cli_main["Main<br/>executable entry<br/>[Main.cpp]"]
  node_cli_parser["CLI parser<br/>input adapter<br/>[Parser.cpp]"]
end

subgraph group_support["Support"]
  node_rapid_logger["RapidLogger<br/>logging support<br/>[RapidLogger.h]"]
  node_status_string["status text<br/>status helper"]
end

subgraph group_thirdparty["Third Party"]
  node_ankerl_dense["unordered_dense<br/>hash map<br/>[unordered_dense.h]"]
  node_doctest["doctest<br/>test framework<br/>[doctest.h]"]
end

node_include_riri_hpp -->|"aggregates"| node_include_commands
node_include_riri_hpp -->|"aggregates"| node_include_parser
node_include_riri_hpp -->|"aggregates"| node_include_persistence
node_include_riri_hpp -->|"aggregates"| node_include_response
node_include_riri_hpp -->|"aggregates"| node_include_types
node_include_riri_hpp -->|"aggregates"| node_include_utils
node_include_utils -->|"includes"| node_include_accessors
node_include_commands -->|"uses"| node_include_types
node_include_commands -->|"returns"| node_include_response
node_include_parser -->|"parses"| node_include_types
node_commands_layer -->|"orchestrates"| node_data_manager
node_commands_layer -->|"builds"| node_include_response
node_data_manager -->|"stores in"| node_memory_maps
node_data_manager -->|"formats"| node_status_string
node_memory_maps -->|"backed by"| node_ankerl_dense
node_persistence_core -->|"loads via"| node_loader
node_persistence_core -->|"saves via"| node_dumper
node_loader -->|"restores"| node_memory_maps
node_dumper -->|"reads"| node_memory_maps
node_cli_main -->|"uses"| node_cli_parser
node_cli_parser -->|"invokes"| node_commands_layer
node_rapid_logger -.->|"supports"| node_data_manager
node_rapid_logger -.->|"supports"| node_commands_layer
node_doctest -.->|"tests"| node_commands_layer
node_doctest -.->|"tests"| node_data_manager
node_doctest -.->|"tests"| node_status_string

click node_include_riri_hpp "https://github.com/ad4rsh2701/riri/blob/main/include/riri.hpp"
click node_include_commands "https://github.com/ad4rsh2701/riri/blob/main/include/riri/Commands.hpp"
click node_include_parser "https://github.com/ad4rsh2701/riri/blob/main/include/riri/Parser.hpp"
click node_include_persistence "https://github.com/ad4rsh2701/riri/blob/main/include/riri/Persistence.hpp"
click node_include_response "https://github.com/ad4rsh2701/riri/blob/main/include/riri/RapidResponse.hpp"
click node_include_types "https://github.com/ad4rsh2701/riri/blob/main/include/riri/RapidTypes.hpp"
click node_include_utils "https://github.com/ad4rsh2701/riri/blob/main/include/riri/utils.hpp"
click node_include_accessors "https://github.com/ad4rsh2701/riri/blob/main/include/riri/utils/Accessors.hpp"
click node_data_manager "https://github.com/ad4rsh2701/riri/blob/main/src/core/DataManager.cpp"
click node_memory_maps "https://github.com/ad4rsh2701/riri/blob/main/src/core/MemoryMaps.cpp"
click node_commands_layer "https://github.com/ad4rsh2701/riri/blob/main/src/commands/set.cpp"
click node_persistence_core "https://github.com/ad4rsh2701/riri/blob/main/src/core/persistence/Persistence.cpp"
click node_loader "https://github.com/ad4rsh2701/riri/blob/main/src/core/persistence/Loader.cpp"
click node_dumper "https://github.com/ad4rsh2701/riri/blob/main/src/core/persistence/Dumper.cpp"
click node_cli_main "https://github.com/ad4rsh2701/riri/blob/main/src/cli/Main.cpp"
click node_cli_parser "https://github.com/ad4rsh2701/riri/blob/main/src/cli/Parser.cpp"
click node_rapid_logger "https://github.com/ad4rsh2701/riri/blob/main/src/utils/RapidLogger.h"
click node_status_string "https://github.com/ad4rsh2701/riri/blob/main/src/utils/helpers/status_to_string.hpp"
click node_ankerl_dense "https://github.com/ad4rsh2701/riri/blob/main/src/include/ankerl/unordered_dense.h"
click node_doctest "https://github.com/ad4rsh2701/riri/blob/main/tests/doctest.h"

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_include_riri_hpp,node_include_commands,node_include_parser,node_include_persistence,node_include_response,node_include_types,node_include_utils,node_include_accessors toneBlue
class node_data_manager,node_memory_maps,node_commands_layer,node_persistence_core,node_loader,node_dumper toneAmber
class node_cli_main,node_cli_parser toneMint
class node_rapid_logger,node_status_string toneRose
class node_ankerl_dense,node_doctest toneIndigo
```

## Components

### Public API

Stable headers consumed by library users

- [riri.hpp](https://github.com/ad4rsh2701/riri/blob/main/include/riri.hpp): umbrella header · Top-level public include that aggregates the API surface · `include/riri.hpp`
- [Commands](https://github.com/ad4rsh2701/riri/blob/main/include/riri/Commands.hpp): public API · User-facing CRUD and batch command interface · `include/riri/Commands.hpp`
- [Parser](https://github.com/ad4rsh2701/riri/blob/main/include/riri/Parser.hpp): public API · Public parsing boundary for command/input handling · `include/riri/Parser.hpp`
- [Persistence](https://github.com/ad4rsh2701/riri/blob/main/include/riri/Persistence.hpp): public API · Public persistence boundary for save/restore operations · `include/riri/Persistence.hpp`
- [RapidResponse](https://github.com/ad4rsh2701/riri/blob/main/include/riri/RapidResponse.hpp): response types · Structured statuses and result aggregation returned by commands · `include/riri/RapidResponse.hpp`
- [RapidTypes](https://github.com/ad4rsh2701/riri/blob/main/include/riri/RapidTypes.hpp): data model · Typed key-value model including nodes and variant-like values · `include/riri/RapidTypes.hpp`
- [utils](https://github.com/ad4rsh2701/riri/blob/main/include/riri/utils.hpp): public helpers · Public utility helpers and accessors · `include/riri/utils.hpp`
- [Accessors](https://github.com/ad4rsh2701/riri/blob/main/include/riri/utils/Accessors.hpp): public helpers · Public accessor utilities for the data model · `include/riri/utils/Accessors.hpp`

### Core Engine

In-memory storage and persistence internals

- [DataManager](https://github.com/ad4rsh2701/riri/blob/main/src/core/DataManager.cpp): store coordinator · Coordinates reads, writes, validation, and invariants · `src/core/DataManager.cpp`
- [MemoryMaps](https://github.com/ad4rsh2701/riri/blob/main/src/core/MemoryMaps.cpp): in-memory store · Owns the underlying key-value containers · `src/core/MemoryMaps.cpp`
- [Command impls](https://github.com/ad4rsh2701/riri/blob/main/src/commands/set.cpp): orchestration layer · Thin command wrappers for set, get, delete, update, and clear · `src/commands/set.cpp`
- [Persistence core](https://github.com/ad4rsh2701/riri/blob/main/src/core/persistence/Persistence.cpp): persistence coordinator · Top-level persistence orchestration · `src/core/persistence/Persistence.cpp`
- [Loader](https://github.com/ad4rsh2701/riri/blob/main/src/core/persistence/Loader.cpp): state restore · Deserializes and restores stored state · `src/core/persistence/Loader.cpp`
- [Dumper](https://github.com/ad4rsh2701/riri/blob/main/src/core/persistence/Dumper.cpp): state snapshot · Serializes store state for persistence · `src/core/persistence/Dumper.cpp`

### CLI

Command-line entrypoint and parsing

- [Main](https://github.com/ad4rsh2701/riri/blob/main/src/cli/Main.cpp): executable entry · CLI entrypoint for local interaction and testing · `src/cli/Main.cpp`
- [CLI parser](https://github.com/ad4rsh2701/riri/blob/main/src/cli/Parser.cpp): input adapter · Translates command-line input into library calls · `src/cli/Parser.cpp`

### Support

Cross-cutting utilities and helpers

- [RapidLogger](https://github.com/ad4rsh2701/riri/blob/main/src/utils/RapidLogger.h): logging support · Diagnostic logging support used across the implementation · `src/utils/RapidLogger.h`
- [status text](https://github.com/ad4rsh2701/riri/blob/main/src/utils/helpers/status_to_string.hpp): status helper · Converts status codes into readable strings · `src/utils/helpers/status_to_string.hpp`

### Third Party

Vendored external dependencies

- [unordered_dense](https://github.com/ad4rsh2701/riri/blob/main/src/include/ankerl/unordered_dense.h): hash map · Vendored high-performance hash map dependency · `src/include/ankerl/unordered_dense.h`
- [doctest](https://github.com/ad4rsh2701/riri/blob/main/tests/doctest.h): test framework · Embedded unit test framework · `tests/doctest.h`

## Connections

- riri.hpp → Commands: aggregates · Umbrella header exposes the command API
- riri.hpp → Parser: aggregates · Umbrella header exposes parsing boundary
- riri.hpp → Persistence: aggregates · Umbrella header exposes persistence API
- riri.hpp → RapidResponse: aggregates · Umbrella header exposes responses
- riri.hpp → RapidTypes: aggregates · Umbrella header exposes typed data model
- riri.hpp → utils: aggregates · Umbrella header exposes utilities
- utils → Accessors: includes · Utility facade includes accessor helpers
- Commands → RapidTypes: uses · Commands operate on typed nodes and values
- Commands → RapidResponse: returns · Commands return structured statuses and results
- Parser → RapidTypes: parses · Parser converts input into typed nodes
- Command impls → DataManager: orchestrates · Command wrappers delegate core mutations and reads
- Command impls → RapidResponse: builds · Command layer assembles operation responses
- DataManager → MemoryMaps: stores in · Data manager coordinates the underlying in-memory maps
- DataManager → status text: formats · Uses status helpers for readable results
- MemoryMaps → unordered_dense: backed by · Main storage uses vendored dense hash maps
- Persistence core → Loader: loads via · Persistence coordinator restores state through loader
- Persistence core → Dumper: saves via · Persistence coordinator snapshots state through dumper
- Loader → MemoryMaps: restores · Loader repopulates the in-memory store
- Dumper → MemoryMaps: reads · Dumper serializes current store state
- Main → CLI parser: uses · CLI entrypoint consumes parsed input
- CLI parser → Command impls: invokes · CLI adapter routes requests into command execution
- RapidLogger → DataManager: supports · Logging aids core execution and diagnostics
- RapidLogger → Command impls: supports · Logging aids command orchestration
- doctest → Command impls: tests · Unit tests validate command behavior
- doctest → DataManager: tests · Unit tests validate core store behavior
- doctest → status text: tests · Unit tests validate response/status helpers