# nirjhardebnath/anemodb architecture

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

- Interactive diagram: https://gitdiagram.com/nirjhardebnath/anemodb
- Repository: https://github.com/nirjhardebnath/anemodb

## Overview

Anemo DB accepts SQL-over-TCP requests, queues them for worker processing, and returns read results from an LRU/TTL cache or PostgreSQL on a miss. Its in-band stats feed the terminal monitor and Flask dashboard; the dashboard also controls optional cache-versus-database traffic simulation. Benchmark scripts and SQL dataset tooling are documented capabilities, but are outside the runtime workflow. Core request/cache wiring is supported by the README and sampled C++ excerpts; dashboard wiring is sampled, while unsampled implementation details are kept at subsystem level.

Main entry points: [`Cache Components/CacheEngine.hpp`](https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/CacheEngine.hpp) (TCP Engine), [`Web Dashboard/web_dashboard.py`](https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/web_dashboard.py) (Flask Backend), [`Web Dashboard/static/script.js`](https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/static/script.js) (Dashboard Scripts), [`Web Dashboard/traffic_generator.py`](https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/traffic_generator.py) (Traffic Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Cache Server"]
  node_entry["Server Entry<br/>[main.cpp]"]
  node_engine["TCP Engine<br/>[CacheEngine.hpp]"]
  node_queue["Bounded Queue"]
  node_cache[("TTL LRU Cache<br/>[Cache.hpp]")]
  node_pool["DB Pool<br/>[ConnectionPool.hpp]"]
end

subgraph group_observability["Monitoring"]
  node_monitor["Terminal Monitor<br/>[monitor_cache.py]"]
end

subgraph group_dashboard["Web Dashboard"]
  node_dashboard_ui["Dashboard UI<br/>[index.html]"]
  node_dashboard_js["Dashboard Scripts<br/>[script.js]"]
  node_dashboard_backend["Flask Backend<br/>[web_dashboard.py]"]
  node_traffic["Traffic Generator"]
end

subgraph group_validation["Benchmarking"]
  node_bench_clients["Benchmark Clients"]
  node_dataset["SQL Dataset"]
end

node_client(("SQL Client"))
node_postgres[("PostgreSQL")]
node_browser(("Dashboard User"))

node_client -->|"sends SQL"| node_engine
node_engine -->|"enqueues request"| node_queue
node_queue -->|"dispatches task"| node_engine
node_engine -->|"looks up or reserves"| node_cache
node_engine -->|"fetches on miss"| node_pool
node_pool -->|"queries"| node_postgres
node_engine -->|"returns response"| node_client
node_engine -->|"serves STATS"| node_monitor
node_monitor -->|"polls STATS"| node_engine
node_browser -->|"uses dashboard"| node_dashboard_ui
node_dashboard_ui -->|"loads scripts"| node_dashboard_js
node_dashboard_js -->|"requests stats"| node_dashboard_backend
node_dashboard_backend -->|"polls STATS_JSON"| node_engine
node_dashboard_backend -->|"reads metrics"| node_traffic
node_dashboard_js -->|"controls traffic"| node_dashboard_backend
node_traffic -->|"sends simulated SQL"| node_engine
node_traffic -.->|"runs direct queries"| node_postgres
node_bench_clients -->|"benchmarks cache"| node_engine
node_bench_clients -->|"benchmarks direct DB"| node_postgres
node_dataset -.->|"initializes schema"| node_postgres

click node_entry "https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/main.cpp"
click node_engine "https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/CacheEngine.hpp"
click node_queue "https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/ThreadSafeQueue.hpp"
click node_cache "https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/Cache.hpp"
click node_pool "https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/ConnectionPool.hpp"
click node_monitor "https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Monitor/monitor_cache.py"
click node_dashboard_ui "https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/templates/index.html"
click node_dashboard_js "https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/static/script.js"
click node_dashboard_backend "https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/web_dashboard.py"
click node_traffic "https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/traffic_generator.py"
click node_bench_clients "https://github.com/nirjhardebnath/anemodb/tree/main/Cache%20Benchmark"
click node_dataset "https://github.com/nirjhardebnath/anemodb/tree/main/Cache%20Benchmark/create_db"

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_engine,node_queue,node_cache,node_pool,node_client,node_browser toneBlue
class node_monitor,node_postgres toneAmber
class node_dashboard_ui,node_dashboard_js,node_dashboard_backend,node_traffic toneMint
class node_bench_clients,node_dataset toneRose
```

## Components

### Cache Server

- [Server Entry](https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/main.cpp): `Cache Components/main.cpp`
- [TCP Engine](https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/CacheEngine.hpp): `Cache Components/CacheEngine.hpp`
- [Bounded Queue](https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/ThreadSafeQueue.hpp): `Cache Components/ThreadSafeQueue.hpp`
- [TTL LRU Cache](https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/Cache.hpp): `Cache Components/Cache.hpp`
- [DB Pool](https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Components/ConnectionPool.hpp): `Cache Components/ConnectionPool.hpp`

### Monitoring

- [Terminal Monitor](https://github.com/nirjhardebnath/anemodb/blob/main/Cache%20Monitor/monitor_cache.py): `Cache Monitor/monitor_cache.py`

### Web Dashboard

- [Dashboard UI](https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/templates/index.html): `Web Dashboard/templates/index.html`
- [Dashboard Scripts](https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/static/script.js): `Web Dashboard/static/script.js`
- [Flask Backend](https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/web_dashboard.py): `Web Dashboard/web_dashboard.py`
- [Traffic Generator](https://github.com/nirjhardebnath/anemodb/blob/main/Web%20Dashboard/traffic_generator.py): `Web Dashboard/traffic_generator.py`

### Benchmarking

- [Benchmark Clients](https://github.com/nirjhardebnath/anemodb/tree/main/Cache%20Benchmark): `Cache Benchmark`
- [SQL Dataset](https://github.com/nirjhardebnath/anemodb/tree/main/Cache%20Benchmark/create_db): `Cache Benchmark/create_db`

### Other components

- **SQL Client**
- **PostgreSQL**
- **Dashboard User**

## Connections

- SQL Client → TCP Engine: sends SQL
- TCP Engine → Bounded Queue: enqueues request
- Bounded Queue → TCP Engine: dispatches task
- TCP Engine → TTL LRU Cache: looks up or reserves
- TCP Engine → DB Pool: fetches on miss
- DB Pool → PostgreSQL: queries
- TCP Engine → SQL Client: returns response
- TCP Engine → Terminal Monitor: serves STATS
- Terminal Monitor → TCP Engine: polls STATS
- Dashboard User → Dashboard UI: uses dashboard
- Dashboard UI → Dashboard Scripts: loads scripts
- Dashboard Scripts → Flask Backend: requests stats
- Flask Backend → TCP Engine: polls STATS_JSON
- Flask Backend → Traffic Generator: reads metrics
- Dashboard Scripts → Flask Backend: controls traffic
- Traffic Generator → TCP Engine: sends simulated SQL
- Traffic Generator → PostgreSQL: runs direct queries
- Benchmark Clients → TCP Engine: benchmarks cache
- Benchmark Clients → PostgreSQL: benchmarks direct DB
- SQL Dataset → PostgreSQL: initializes schema