# fils/qleverflow architecture

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

- Interactive diagram: https://gitdiagram.com/fils/qleverflow
- Repository: https://github.com/fils/qleverflow

## Overview

This repository is primarily an exploratory QLever deployment toolkit: an operator configures local or Portainer stacks and serves graph datasets through QLever, with the UI and Petrimaps as companion services. Its other product branches are example catalogue Qleverfiles, SPARQL query collections, a free-text search UI, an MCP query server, and SHACL validation utilities. The validation flow is visible in sampled source; several deployment and catalogue details are documented only at a high level, so their wiring is not expanded beyond that evidence.

Main entry points: [`validation/shapeValidator/validateToOxigraph.py`](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToOxigraph.py) (Validation Runner), [`validation/shapeValidator/validateToLance.py`](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToLance.py) (Lance Validation), [`deployment/docker-compose.yml`](https://github.com/fils/qleverflow/blob/master/deployment/docker-compose.yml) (Compose Stack), [`ui/client.py`](https://github.com/fils/qleverflow/blob/master/ui/client.py) (Text Search UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deploy["Deployment"]
  node_compose["Compose Stack<br/>[docker-compose.yml]"]
  node_stack_config["QLever Services"]
  node_qlever["QLever Server"]
  node_qlever_ui["QLever UI"]
  node_petrimaps["Petrimaps"]
end

subgraph group_catalogue["Graph Catalogues"]
  node_catalogues["Dataset Qleverfiles"]
  node_graph_data["Graph Data Products<br/>[README.md]"]
end

subgraph group_discovery["Search and Query"]
  node_query_library["SPARQL Queries"]
  node_text_ui["Text Search UI<br/>[client.py]"]
  node_ui_usage["Usage Information<br/>[usage_info.py]"]
  node_query_prep["Query Preparation<br/>[query_prep.py]"]
  node_mcp_server["MCP Query Server<br/>[main.py]"]
  node_mcp_client["QLever MCP Client<br/>[qleverClient.py]"]
end

subgraph group_validation["SHACL Validation"]
  node_validator_runner["Validation Runner"]
  node_dataset_discovery["Dataset Discovery<br/>[getGraphs.py]"]
  node_graph_construct["Graph Construction<br/>[getConstruct.py]"]
  node_shape_reader["Shape Reader<br/>[getShape.py]"]
  node_shacl["SHACL Validation<br/>[shaclValidator.py]"]
  node_result_store[("Validation Result Store")]
  node_lance_runner["Lance Validation<br/>[validateToLance.py]"]
  node_lance_store[("LanceDB<br/>[validateToLance.py]")]
  node_shape_files["SHACL Shape Files"]
end

node_operator(("Operator"))

node_operator -->|"deploys"| node_compose
node_compose -.->|"configures"| node_stack_config
node_compose -->|"provides"| node_qlever
node_compose -->|"provides"| node_qlever_ui
node_compose -->|"provides"| node_petrimaps
node_catalogues -->|"describes"| node_graph_data
node_text_ui -->|"queries"| node_qlever
node_text_ui -->|"renders"| node_ui_usage
node_query_prep -.->|"supports"| node_text_ui
node_mcp_server -->|"queries"| node_qlever
node_mcp_client -.->|"connects"| node_mcp_server
node_validator_runner -->|"discovers"| node_dataset_discovery
node_validator_runner -->|"loads"| node_shape_reader
node_validator_runner -->|"constructs"| node_graph_construct
node_validator_runner -->|"validates"| node_shacl
node_validator_runner -->|"loads results"| node_result_store
node_shape_reader -.->|"reads"| node_shape_files
node_lance_runner -->|"discovers"| node_dataset_discovery
node_lance_runner -->|"loads"| node_shape_reader
node_lance_runner -->|"constructs"| node_graph_construct
node_lance_runner -->|"validates"| node_shacl
node_lance_runner -->|"opens table"| node_lance_store

click node_compose "https://github.com/fils/qleverflow/blob/master/deployment/docker-compose.yml"
click node_stack_config "https://github.com/fils/qleverflow/blob/master/deployment/qlever_services.yaml"
click node_catalogues "https://github.com/fils/qleverflow/tree/master/catalogues"
click node_graph_data "https://github.com/fils/qleverflow/blob/master/catalogues/README.md"
click node_query_library "https://github.com/fils/qleverflow/tree/master/queries"
click node_text_ui "https://github.com/fils/qleverflow/blob/master/ui/client.py"
click node_ui_usage "https://github.com/fils/qleverflow/blob/master/ui/defs/usage_info.py"
click node_query_prep "https://github.com/fils/qleverflow/blob/master/ui/query_prep.py"
click node_mcp_server "https://github.com/fils/qleverflow/blob/master/mcp/server/main.py"
click node_mcp_client "https://github.com/fils/qleverflow/blob/master/mcp/agent/qleverClient.py"
click node_validator_runner "https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToOxigraph.py"
click node_dataset_discovery "https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/defs/getGraphs.py"
click node_graph_construct "https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/defs/getConstruct.py"
click node_shape_reader "https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/defs/getShape.py"
click node_shacl "https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/defs/shaclValidator.py"
click node_result_store "https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToOxigraph.py"
click node_lance_runner "https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToLance.py"
click node_lance_store "https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToLance.py"
click node_shape_files "https://github.com/fils/qleverflow/tree/master/validation/shapes"

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_compose,node_stack_config,node_qlever,node_qlever_ui,node_petrimaps toneBlue
class node_catalogues,node_graph_data toneAmber
class node_query_library,node_text_ui,node_ui_usage,node_query_prep,node_mcp_server,node_mcp_client toneMint
class node_validator_runner,node_dataset_discovery,node_graph_construct,node_shape_reader,node_shacl,node_result_store,node_lance_runner,node_lance_store,node_shape_files toneRose
class node_operator toneIndigo
```

## Components

### Deployment

- [Compose Stack](https://github.com/fils/qleverflow/blob/master/deployment/docker-compose.yml): `deployment/docker-compose.yml`
- [QLever Services](https://github.com/fils/qleverflow/blob/master/deployment/qlever_services.yaml): `deployment/qlever_services.yaml`
- **QLever Server**
- **QLever UI**
- **Petrimaps**

### Graph Catalogues

- [Dataset Qleverfiles](https://github.com/fils/qleverflow/tree/master/catalogues): `catalogues`
- [Graph Data Products](https://github.com/fils/qleverflow/blob/master/catalogues/README.md): `catalogues/README.md`

### Search and Query

- [SPARQL Queries](https://github.com/fils/qleverflow/tree/master/queries): `queries`
- [Text Search UI](https://github.com/fils/qleverflow/blob/master/ui/client.py): `ui/client.py`
- [Usage Information](https://github.com/fils/qleverflow/blob/master/ui/defs/usage_info.py): `ui/defs/usage_info.py`
- [Query Preparation](https://github.com/fils/qleverflow/blob/master/ui/query_prep.py): `ui/query_prep.py`
- [MCP Query Server](https://github.com/fils/qleverflow/blob/master/mcp/server/main.py): `mcp/server/main.py`
- [QLever MCP Client](https://github.com/fils/qleverflow/blob/master/mcp/agent/qleverClient.py): `mcp/agent/qleverClient.py`

### SHACL Validation

- [Validation Runner](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToOxigraph.py): `validation/shapeValidator/validateToOxigraph.py`
- [Dataset Discovery](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/defs/getGraphs.py): `validation/shapeValidator/defs/getGraphs.py`
- [Graph Construction](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/defs/getConstruct.py): `validation/shapeValidator/defs/getConstruct.py`
- [Shape Reader](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/defs/getShape.py): `validation/shapeValidator/defs/getShape.py`
- [SHACL Validation](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/defs/shaclValidator.py): `validation/shapeValidator/defs/shaclValidator.py`
- [Validation Result Store](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToOxigraph.py): `validation/shapeValidator/validateToOxigraph.py`
- [Lance Validation](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToLance.py): `validation/shapeValidator/validateToLance.py`
- [LanceDB](https://github.com/fils/qleverflow/blob/master/validation/shapeValidator/validateToLance.py): `validation/shapeValidator/validateToLance.py`
- [SHACL Shape Files](https://github.com/fils/qleverflow/tree/master/validation/shapes): `validation/shapes`

### Other components

- **Operator**

## Connections

- Operator → Compose Stack: deploys (evidence: `README.md`)
- Compose Stack → QLever Services: configures
- Compose Stack → QLever Server: provides (evidence: `README.md`)
- Compose Stack → QLever UI: provides (evidence: `README.md`)
- Compose Stack → Petrimaps: provides (evidence: `README.md`)
- Dataset Qleverfiles → Graph Data Products: describes (evidence: `README.md`)
- Text Search UI → QLever Server: queries (evidence: `ui/client.py`)
- Text Search UI → Usage Information: renders (evidence: `ui/client.py`)
- Query Preparation → Text Search UI: supports
- MCP Query Server → QLever Server: queries (evidence: `mcp/server/main.py`)
- QLever MCP Client → MCP Query Server: connects
- Validation Runner → Dataset Discovery: discovers (evidence: `validation/shapeValidator/validateToOxigraph.py`)
- Validation Runner → Shape Reader: loads (evidence: `validation/shapeValidator/validateToOxigraph.py`)
- Validation Runner → Graph Construction: constructs (evidence: `validation/shapeValidator/validateToOxigraph.py`)
- Validation Runner → SHACL Validation: validates (evidence: `validation/shapeValidator/validateToOxigraph.py`)
- Validation Runner → Validation Result Store: loads results (evidence: `validation/shapeValidator/validateToOxigraph.py`)
- Shape Reader → SHACL Shape Files: reads
- Lance Validation → Dataset Discovery: discovers (evidence: `validation/shapeValidator/validateToLance.py`)
- Lance Validation → Shape Reader: loads (evidence: `validation/shapeValidator/validateToLance.py`)
- Lance Validation → Graph Construction: constructs (evidence: `validation/shapeValidator/validateToLance.py`)
- Lance Validation → SHACL Validation: validates (evidence: `validation/shapeValidator/validateToLance.py`)
- Lance Validation → LanceDB: opens table (evidence: `validation/shapeValidator/validateToLance.py`)
