# lvn2007/xstore architecture

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

- Interactive diagram: https://gitdiagram.com/lvn2007/xstore
- Repository: https://github.com/lvn2007/xstore

## Overview

XStore is a time-series/key-value database served over ZeroMQ and Protocol Buffers. Its principal workflow is a client request reaching the server and using the store’s data operations; the README also documents WAL-backed durability, index rebuilding, optional CURVE authentication, and a separate viewer for browsing, querying, aggregates, and host monitoring. The viewer and several storage subsystems are represented at their supported source paths, but their internal call wiring was not sampled, so uncertain links are omitted. The source index and README support the shown relationships; unsampled implementation details are not asserted.

Main entry points: [`src/XStore_Networking/ZMQ_Server.cpp`](https://github.com/lvn2007/xstore/blob/main/src/XStore_Networking/ZMQ_Server.cpp) (ZMQ server), [`src/main.cpp`](https://github.com/lvn2007/xstore/blob/main/src/main.cpp) (Server bootstrap), [`include/XStore/XStore.h`](https://github.com/lvn2007/xstore/blob/main/include/XStore/XStore.h) (XStore API), [`src/XStore/XStore_Wal.cpp`](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_Wal.cpp) (Write-ahead log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_main["Server bootstrap<br/>[main.cpp]"]
  node_server["ZMQ server<br/>[ZMQ_Server.cpp]"]
  node_broker["Reply broker<br/>[ZMQ_Broker.cpp]"]
  node_stream["Stream flow control<br/>[ZMQ_StreamFlow.h]"]
  node_gone["Gone-client tracking<br/>[ZMQ_GoneClients.h]"]
end

subgraph group_storage["Storage engine"]
  node_storeapi["XStore API<br/>[XStore.h]"]
  node_management["Database management"]
  node_batch["Batch operations"]
  node_range["Range operations"]
  node_unary["Unary operations"]
  node_aggregates["Aggregates"]
  node_catidx["Category index<br/>[XStore_CatIdx.cpp]"]
  node_zonemap["Zone map index<br/>[XStore_ZoneMap.cpp]"]
  node_wal["Write-ahead log<br/>[XStore_Wal.cpp]"]
  node_walring["WAL ring<br/>[XStore_WalRing.cpp]"]
  node_checkpoint["WAL checkpoint"]
  node_datafiles[("Data store")]
end

subgraph group_security["Security"]
  node_curve["CURVE authentication<br/>[XStore_Curve.cpp]"]
  node_keys["Key administration<br/>[main.cpp]"]
end

subgraph group_clients["Clients and viewer"]
  node_cppclient["C++ client<br/>[XStore_Client.h]"]
  node_pyclient["Python client<br/>[XStore.py]"]
  node_viewerclient["Viewer server client<br/>[client.rs]"]
  node_viewerui["Viewer interface<br/>[app.js]"]
  node_viewerweb["Viewer web host<br/>[web.rs]"]
end

node_user(("Application client"))

node_user -->|"uses"| node_cppclient
node_user -->|"uses"| node_pyclient
node_cppclient -.->|"requests"| node_server
node_pyclient -.->|"requests"| node_server
node_main -->|"starts"| node_server
node_main -->|"initializes"| node_storeapi
node_main -->|"configures"| node_curve
node_main -->|"configures"| node_walring
node_main -->|"configures"| node_checkpoint
node_server -->|"uses"| node_broker
node_server -->|"controls replies"| node_stream
node_gone -->|"cancels windows"| node_stream
node_wal -->|"uses"| node_walring
node_wal -->|"uses"| node_checkpoint
node_wal -.->|"replays into"| node_datafiles
node_management -->|"rebuilds"| node_zonemap
node_management -->|"rebuilds"| node_catidx
node_storeapi -.->|"dispatches operations"| node_batch
node_storeapi -.->|"dispatches operations"| node_range
node_storeapi -.->|"dispatches operations"| node_unary
node_storeapi -.->|"provides aggregates"| node_aggregates
node_keys -->|"manages keys"| node_curve
node_curve -->|"authenticates peers"| node_server
node_user -->|"browses"| node_viewerui
node_viewerui -.->|"queries server"| node_viewerclient
node_viewerweb -.->|"hosts interface"| node_viewerui
node_viewerclient -->|"queries"| node_server

click node_main "https://github.com/lvn2007/xstore/blob/main/src/main.cpp"
click node_server "https://github.com/lvn2007/xstore/blob/main/src/XStore_Networking/ZMQ_Server.cpp"
click node_broker "https://github.com/lvn2007/xstore/blob/main/src/XStore_Networking/ZMQ_Broker.cpp"
click node_stream "https://github.com/lvn2007/xstore/blob/main/include/Networking/ZMQ_StreamFlow.h"
click node_gone "https://github.com/lvn2007/xstore/blob/main/include/Networking/ZMQ_GoneClients.h"
click node_storeapi "https://github.com/lvn2007/xstore/blob/main/include/XStore/XStore.h"
click node_management "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_Management.cpp"
click node_batch "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_BatchOps.cpp"
click node_range "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_RangeOps.cpp"
click node_unary "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_UnaryOps.cpp"
click node_aggregates "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_Aggregates.cpp"
click node_catidx "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_CatIdx.cpp"
click node_zonemap "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_ZoneMap.cpp"
click node_wal "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_Wal.cpp"
click node_walring "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_WalRing.cpp"
click node_checkpoint "https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_WalCheckpoint.cpp"
click node_curve "https://github.com/lvn2007/xstore/blob/main/src/XStore_Networking/XStore_Curve.cpp"
click node_keys "https://github.com/lvn2007/xstore/blob/main/tools/xstore-keys/main.cpp"
click node_cppclient "https://github.com/lvn2007/xstore/blob/main/client_src/Cpp/XStore_Client.h"
click node_pyclient "https://github.com/lvn2007/xstore/blob/main/client_src/Python/XStore.py"
click node_viewerclient "https://github.com/lvn2007/xstore/blob/main/tools/xstore-viewer/src/client.rs"
click node_viewerui "https://github.com/lvn2007/xstore/blob/main/tools/xstore-viewer/frontend/app.js"
click node_viewerweb "https://github.com/lvn2007/xstore/blob/main/tools/xstore-viewer/src/web.rs"

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_main,node_server,node_broker,node_stream,node_gone,node_user toneBlue
class node_storeapi,node_management,node_batch,node_range,node_unary,node_aggregates,node_catidx,node_zonemap,node_wal,node_walring,node_checkpoint,node_datafiles toneAmber
class node_curve,node_keys toneMint
class node_cppclient,node_pyclient,node_viewerclient,node_viewerui,node_viewerweb toneRose
```

## Components

### Server runtime

- [Server bootstrap](https://github.com/lvn2007/xstore/blob/main/src/main.cpp): `src/main.cpp`
- [ZMQ server](https://github.com/lvn2007/xstore/blob/main/src/XStore_Networking/ZMQ_Server.cpp): `src/XStore_Networking/ZMQ_Server.cpp`
- [Reply broker](https://github.com/lvn2007/xstore/blob/main/src/XStore_Networking/ZMQ_Broker.cpp): `src/XStore_Networking/ZMQ_Broker.cpp`
- [Stream flow control](https://github.com/lvn2007/xstore/blob/main/include/Networking/ZMQ_StreamFlow.h): `include/Networking/ZMQ_StreamFlow.h`
- [Gone-client tracking](https://github.com/lvn2007/xstore/blob/main/include/Networking/ZMQ_GoneClients.h): `include/Networking/ZMQ_GoneClients.h`

### Storage engine

- [XStore API](https://github.com/lvn2007/xstore/blob/main/include/XStore/XStore.h): `include/XStore/XStore.h`
- [Database management](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_Management.cpp): `src/XStore/XStore_Management.cpp`
- [Batch operations](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_BatchOps.cpp): `src/XStore/XStore_BatchOps.cpp`
- [Range operations](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_RangeOps.cpp): `src/XStore/XStore_RangeOps.cpp`
- [Unary operations](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_UnaryOps.cpp): `src/XStore/XStore_UnaryOps.cpp`
- [Aggregates](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_Aggregates.cpp): `src/XStore/XStore_Aggregates.cpp`
- [Category index](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_CatIdx.cpp): `src/XStore/XStore_CatIdx.cpp`
- [Zone map index](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_ZoneMap.cpp): `src/XStore/XStore_ZoneMap.cpp`
- [Write-ahead log](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_Wal.cpp): `src/XStore/XStore_Wal.cpp`
- [WAL ring](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_WalRing.cpp): `src/XStore/XStore_WalRing.cpp`
- [WAL checkpoint](https://github.com/lvn2007/xstore/blob/main/src/XStore/XStore_WalCheckpoint.cpp): `src/XStore/XStore_WalCheckpoint.cpp`
- **Data store**

### Security

- [CURVE authentication](https://github.com/lvn2007/xstore/blob/main/src/XStore_Networking/XStore_Curve.cpp): `src/XStore_Networking/XStore_Curve.cpp`
- [Key administration](https://github.com/lvn2007/xstore/blob/main/tools/xstore-keys/main.cpp): `tools/xstore-keys/main.cpp`

### Clients and viewer

- [C++ client](https://github.com/lvn2007/xstore/blob/main/client_src/Cpp/XStore_Client.h): `client_src/Cpp/XStore_Client.h`
- [Python client](https://github.com/lvn2007/xstore/blob/main/client_src/Python/XStore.py): `client_src/Python/XStore.py`
- [Viewer server client](https://github.com/lvn2007/xstore/blob/main/tools/xstore-viewer/src/client.rs): `tools/xstore-viewer/src/client.rs`
- [Viewer interface](https://github.com/lvn2007/xstore/blob/main/tools/xstore-viewer/frontend/app.js): `tools/xstore-viewer/frontend/app.js`
- [Viewer web host](https://github.com/lvn2007/xstore/blob/main/tools/xstore-viewer/src/web.rs): `tools/xstore-viewer/src/web.rs`

### Other components

- **Application client**

## Connections

- Application client → C++ client: uses
- Application client → Python client: uses
- C++ client → ZMQ server: requests
- Python client → ZMQ server: requests
- Server bootstrap → ZMQ server: starts (evidence: `src/main.cpp`)
- Server bootstrap → XStore API: initializes (evidence: `src/main.cpp`)
- Server bootstrap → CURVE authentication: configures (evidence: `src/main.cpp`)
- Server bootstrap → WAL ring: configures (evidence: `src/main.cpp`)
- Server bootstrap → WAL checkpoint: configures (evidence: `src/main.cpp`)
- ZMQ server → Reply broker: uses (evidence: `src/XStore_Networking/ZMQ_Server.cpp`)
- ZMQ server → Stream flow control: controls replies (evidence: `include/Networking/ZMQ_StreamFlow.h`)
- Gone-client tracking → Stream flow control: cancels windows (evidence: `include/Networking/ZMQ_GoneClients.h`)
- Write-ahead log → WAL ring: uses (evidence: `src/XStore/XStore_Wal.cpp`)
- Write-ahead log → WAL checkpoint: uses (evidence: `src/XStore/XStore_Wal.cpp`)
- Write-ahead log → Data store: replays into
- Database management → Zone map index: rebuilds (evidence: `src/XStore/XStore_Management.cpp`)
- Database management → Category index: rebuilds (evidence: `src/XStore/XStore_Management.cpp`)
- XStore API → Batch operations: dispatches operations
- XStore API → Range operations: dispatches operations
- XStore API → Unary operations: dispatches operations
- XStore API → Aggregates: provides aggregates
- Key administration → CURVE authentication: manages keys (evidence: `tools/xstore-keys/main.cpp`)
- CURVE authentication → ZMQ server: authenticates peers
- Application client → Viewer interface: browses
- Viewer interface → Viewer server client: queries server
- Viewer web host → Viewer interface: hosts interface
- Viewer server client → ZMQ server: queries