# qlever-dev/qlever-control architecture

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

- Interactive diagram: https://gitdiagram.com/qlever-dev/qlever-control
- Repository: https://github.com/qlever-dev/qlever-control

## Overview

QLever Control is a Python CLI for configuring and operating the QLever RDF/SPARQL database. Its main workflow is to load Qleverfile settings, run an operational command (such as building an index or issuing queries), and interact with the QLever server. A substantial companion capability is the query-monitor TUI, which reads query and resource logs and presents live and historic views. The graph includes documented command families whose implementations were not sampled; their internal calls are therefore left unasserted.

Main entry points: [`src/qlever/monitor_queries/views`](https://github.com/qlever-dev/qlever-control/tree/main/src/qlever/monitor_queries/views) (Live and historic views), [`src/qlever/monitor_queries/app.py`](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/app.py) (Monitor TUI), [`src/qlever/monitor_queries/live_data.py`](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/live_data.py) (Live query state), [`src/qlever/qlever_main.py`](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/qlever_main.py) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and configuration"]
  node_cli_entry["CLI entry<br/>[qlever_main.py]"]
  node_config["Config loading<br/>[config.py]"]
  node_qleverfile["Qleverfile<br/>[qleverfile.py]"]
  node_command_base["Command contract<br/>[command.py]"]
end

subgraph group_operations["Database operations"]
  node_indexing["Index lifecycle<br/>[index.py]"]
  node_querying["SPARQL queries<br/>[query.py]"]
  node_server_control["Server control<br/>[start.py]"]
  node_data_updates["Data updates<br/>[update.py]"]
end

subgraph group_observability["Query monitoring"]
  node_monitor_app["Monitor TUI<br/>[app.py]"]
  node_live_state["Live query state<br/>[live_data.py]"]
  node_historic_data["Historic queries<br/>[historic_data.py]"]
  node_resource_data["Resource readings<br/>[resource_data.py]"]
  node_log_reader["Query log reader<br/>[log_reader.py]"]
  node_models["Monitor models<br/>[models.py]"]
  node_monitor_views["Live and historic views"]
  node_query_table["Query tables<br/>[query_table.py]"]
  node_resource_plot["Resource plot"]
end

subgraph group_evaluation["Evaluation tools"]
  node_benchmarking["Query benchmarks"]
  node_evaluation_app["Evaluation UI"]
  node_evaluation_frontend["Execution comparison<br/>[comparison.js]"]
end

node_user(("Operator"))
node_query_log["Query log"]
node_resource_log["Resource log"]

node_user -->|"runs CLI"| node_cli_entry
node_cli_entry -->|"loads settings"| node_config
node_config -->|"parses settings"| node_qleverfile
node_cli_entry -.->|"dispatches commands"| node_command_base
node_indexing -->|"implements contract"| node_command_base
node_querying -->|"implements contract"| node_command_base
node_indexing -->|"renders usage plots"| node_resource_plot
node_user -.->|"opens monitor"| node_monitor_app
node_monitor_app -->|"starts log tailer"| node_live_state
node_monitor_app -->|"shows screens"| node_monitor_views
node_monitor_app -->|"tails"| node_query_log
node_live_state -->|"parses events"| node_log_reader
node_historic_data -->|"reads log data"| node_log_reader
node_historic_data -->|"produces rows"| node_models
node_live_state -->|"produces rows"| node_models
node_resource_data -->|"produces series"| node_models
node_resource_data -.->|"reads samples"| node_resource_log
node_monitor_views -->|"loads history"| node_historic_data
node_monitor_views -->|"reads live state"| node_live_state
node_monitor_views -->|"loads readings"| node_resource_data
node_monitor_views -->|"renders queries"| node_query_table
node_monitor_views -->|"renders resources"| node_resource_plot
node_user -.->|"runs benchmarks"| node_benchmarking
node_user -.->|"opens evaluation"| node_evaluation_app
node_evaluation_app -.->|"serves interface"| node_evaluation_frontend

click node_cli_entry "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/qlever_main.py"
click node_config "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/config.py"
click node_qleverfile "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/qleverfile.py"
click node_command_base "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/command.py"
click node_indexing "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/index.py"
click node_querying "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/query.py"
click node_server_control "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/start.py"
click node_data_updates "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/update.py"
click node_benchmarking "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/benchmark_queries.py"
click node_evaluation_app "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/serve_evaluation_app.py"
click node_evaluation_frontend "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/evaluation/www/comparison.js"
click node_monitor_app "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/app.py"
click node_live_state "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/live_data.py"
click node_historic_data "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/historic_data.py"
click node_resource_data "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/resource_data.py"
click node_log_reader "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/log_reader.py"
click node_models "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/models.py"
click node_monitor_views "https://github.com/qlever-dev/qlever-control/tree/main/src/qlever/monitor_queries/views"
click node_query_table "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/widgets/query_table.py"
click node_resource_plot "https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/widgets/resource_plot_pane.py"

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_entry,node_config,node_qleverfile,node_command_base toneBlue
class node_indexing,node_querying,node_server_control,node_data_updates toneAmber
class node_monitor_app,node_live_state,node_historic_data,node_resource_data,node_log_reader,node_models,node_monitor_views,node_query_table,node_resource_plot toneMint
class node_benchmarking,node_evaluation_app,node_evaluation_frontend toneRose
class node_user,node_query_log,node_resource_log toneIndigo
```

## Components

### CLI and configuration

- [CLI entry](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/qlever_main.py): `src/qlever/qlever_main.py`
- [Config loading](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/config.py): `src/qlever/config.py`
- [Qleverfile](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/qleverfile.py): `src/qlever/qleverfile.py`
- [Command contract](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/command.py): `src/qlever/command.py`

### Database operations

- [Index lifecycle](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/index.py): `src/qlever/commands/index.py`
- [SPARQL queries](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/query.py): `src/qlever/commands/query.py`
- [Server control](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/start.py): `src/qlever/commands/start.py`
- [Data updates](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/update.py): `src/qlever/commands/update.py`

### Query monitoring

- [Monitor TUI](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/app.py): `src/qlever/monitor_queries/app.py`
- [Live query state](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/live_data.py): `src/qlever/monitor_queries/live_data.py`
- [Historic queries](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/historic_data.py): `src/qlever/monitor_queries/historic_data.py`
- [Resource readings](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/resource_data.py): `src/qlever/monitor_queries/resource_data.py`
- [Query log reader](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/log_reader.py): `src/qlever/monitor_queries/log_reader.py`
- [Monitor models](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/models.py): `src/qlever/monitor_queries/models.py`
- [Live and historic views](https://github.com/qlever-dev/qlever-control/tree/main/src/qlever/monitor_queries/views): `src/qlever/monitor_queries/views`
- [Query tables](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/widgets/query_table.py): `src/qlever/monitor_queries/widgets/query_table.py`
- [Resource plot](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/monitor_queries/widgets/resource_plot_pane.py): `src/qlever/monitor_queries/widgets/resource_plot_pane.py`

### Evaluation tools

- [Query benchmarks](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/benchmark_queries.py): `src/qlever/commands/benchmark_queries.py`
- [Evaluation UI](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/commands/serve_evaluation_app.py): `src/qlever/commands/serve_evaluation_app.py`
- [Execution comparison](https://github.com/qlever-dev/qlever-control/blob/main/src/qlever/evaluation/www/comparison.js): `src/qlever/evaluation/www/comparison.js`

### Other components

- **Operator**
- **Query log**
- **Resource log**

## Connections

- Operator → CLI entry: runs CLI
- CLI entry → Config loading: loads settings (evidence: `src/qlever/qlever_main.py`)
- Config loading → Qleverfile: parses settings (evidence: `src/qlever/config.py`)
- CLI entry → Command contract: dispatches commands
- Index lifecycle → Command contract: implements contract (evidence: `src/qlever/commands/index.py`)
- SPARQL queries → Command contract: implements contract (evidence: `src/qlever/commands/query.py`)
- Index lifecycle → Resource plot: renders usage plots (evidence: `src/qlever/commands/index.py`)
- Operator → Monitor TUI: opens monitor
- Monitor TUI → Live query state: starts log tailer (evidence: `src/qlever/monitor_queries/app.py`)
- Monitor TUI → Live and historic views: shows screens (evidence: `src/qlever/monitor_queries/app.py`)
- Monitor TUI → Query log: tails (evidence: `src/qlever/monitor_queries/app.py`)
- Live query state → Query log reader: parses events (evidence: `src/qlever/monitor_queries/live_data.py`)
- Historic queries → Query log reader: reads log data (evidence: `src/qlever/monitor_queries/historic_data.py`)
- Historic queries → Monitor models: produces rows (evidence: `src/qlever/monitor_queries/historic_data.py`)
- Live query state → Monitor models: produces rows (evidence: `src/qlever/monitor_queries/live_data.py`)
- Resource readings → Monitor models: produces series (evidence: `src/qlever/monitor_queries/resource_data.py`)
- Resource readings → Resource log: reads samples
- Live and historic views → Historic queries: loads history (evidence: `src/qlever/monitor_queries/views/historic.py`)
- Live and historic views → Live query state: reads live state (evidence: `src/qlever/monitor_queries/views/live.py`)
- Live and historic views → Resource readings: loads readings (evidence: `src/qlever/monitor_queries/views/historic.py`)
- Live and historic views → Query tables: renders queries (evidence: `src/qlever/monitor_queries/views/live.py`)
- Live and historic views → Resource plot: renders resources (evidence: `src/qlever/monitor_queries/views/resource_plot_modal.py`)
- Operator → Query benchmarks: runs benchmarks
- Operator → Evaluation UI: opens evaluation
- Evaluation UI → Execution comparison: serves interface
