# isislab-unisa/kgheartbeat architecture

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

- Interactive diagram: https://gitdiagram.com/isislab-unisa/kgheartbeat
- Repository: https://github.com/isislab-unisa/kgheartbeat
- Video tour (about a minute): https://gitdiagram.com/isislab-unisa/kgheartbeat/video

## Overview

KGHeartBeat periodically measures knowledge-graph quality from registered datasets or a supplied SPARQL endpoint, computes dimension and overall scores, and emits CSV results. Its web app lets users search/select graphs and inspect scores, rankings, and quality histories; an Express API serves stored analyses from MongoDB. The README documents broad quality coverage and FAIRness evaluation. Several metric pages and API routes are unsampled, so those are represented as capability groups without speculative internal call chains.

Main entry points: [`src/manager.py`](https://github.com/isislab-unisa/kgheartbeat/blob/main/src/manager.py) (Analysis runner), [`WebApp/front-end/kg-heartbeat/src/App.js`](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/App.js) (Web application), [`src/API/Aggregator.py`](https://github.com/isislab-unisa/kgheartbeat/blob/main/src/API/Aggregator.py) (Metadata aggregator), [`WebApp/back-end/db.js`](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/back-end/db.js) (Analysis queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis engine"]
  node_manager["Analysis runner<br/>[manager.py]"]
  node_metrics["Quality metrics"]
  node_scoring["Scoring<br/>[score.py]"]
  node_csv["CSV results<br/>[OutputCSV.py]"]
  node_sparql_query["SPARQL queries<br/>[query.py]"]
end

subgraph group_metadata["KG discovery"]
  node_metadata_agg["Metadata aggregator<br/>[Aggregator.py]"]
  node_metadata_sources["Metadata sources"]
  node_kg_graph["KG network<br/>[Graph.py]"]
end

subgraph group_web["Web experience"]
  node_app["Web application<br/>[App.js]"]
  node_search["KG search<br/>[Search.js]"]
  node_search_ui["Search results<br/>[SearchResults.js]"]
  node_metric_pages["Quality views"]
  node_score_page["Score view<br/>[Score.js]"]
  node_ranking["Rankings<br/>[Ranking.js]"]
  node_upload["Analysis upload<br/>[UploadAnalysis.js]"]
end

subgraph group_service["Web API and storage"]
  node_server["HTTP server<br/>[server.js]"]
  node_routes["Analysis routes"]
  node_db_access["Analysis queries<br/>[db.js]"]
  node_mongo[("MongoDB")]
end

node_operator(("Operator"))
node_sparql{{"Knowledge graph endpoint"}}

node_operator -.->|"runs analysis"| node_manager
node_manager -.->|"resolves metadata"| node_metadata_agg
node_metadata_agg -->|"queries sources"| node_metadata_sources
node_kg_graph -->|"uses metadata"| node_metadata_agg
node_kg_graph -->|"queries registry"| node_metadata_sources
node_manager -->|"accepts endpoint"| node_sparql
node_sparql_query -->|"sends queries"| node_sparql
node_manager -->|"runs measurements"| node_metrics
node_manager -->|"computes scores"| node_scoring
node_manager -->|"writes results"| node_csv
node_operator -.->|"views results"| node_app
node_app -->|"routes to"| node_search
node_app -->|"routes to"| node_metric_pages
node_app -->|"routes to"| node_score_page
node_app -->|"routes to"| node_ranking
node_app -->|"routes to"| node_upload
node_search -->|"renders results"| node_search_ui
node_server -->|"mounts routes"| node_routes
node_routes -->|"queries analyses"| node_db_access
node_server -->|"connects database"| node_db_access
node_db_access -->|"reads analyses"| node_mongo

click node_manager "https://github.com/isislab-unisa/kgheartbeat/blob/main/src/manager.py"
click node_metrics "https://github.com/isislab-unisa/kgheartbeat/tree/main/src/QualityDimensions"
click node_scoring "https://github.com/isislab-unisa/kgheartbeat/blob/main/src/score.py"
click node_csv "https://github.com/isislab-unisa/kgheartbeat/blob/main/src/OutputCSV.py"
click node_metadata_agg "https://github.com/isislab-unisa/kgheartbeat/blob/main/src/API/Aggregator.py"
click node_metadata_sources "https://github.com/isislab-unisa/kgheartbeat/tree/main/src/API"
click node_kg_graph "https://github.com/isislab-unisa/kgheartbeat/blob/main/src/Graph.py"
click node_sparql_query "https://github.com/isislab-unisa/kgheartbeat/blob/main/src/query.py"
click node_app "https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/App.js"
click node_search "https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/pages/Search.js"
click node_search_ui "https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/components/SearchResults.js"
click node_metric_pages "https://github.com/isislab-unisa/kgheartbeat/tree/main/WebApp/front-end/kg-heartbeat/src/pages"
click node_score_page "https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/pages/Score.js"
click node_ranking "https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/pages/Ranking.js"
click node_upload "https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/pages/UploadAnalysis.js"
click node_server "https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/back-end/server.js"
click node_routes "https://github.com/isislab-unisa/kgheartbeat/tree/main/WebApp/back-end/routes"
click node_db_access "https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/back-end/db.js"

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_manager,node_metrics,node_scoring,node_csv,node_sparql_query toneBlue
class node_metadata_agg,node_metadata_sources,node_kg_graph toneAmber
class node_app,node_search,node_search_ui,node_metric_pages,node_score_page,node_ranking,node_upload toneMint
class node_server,node_routes,node_db_access,node_mongo toneRose
class node_operator,node_sparql toneIndigo
```

## Components

### Analysis engine

- [Analysis runner](https://github.com/isislab-unisa/kgheartbeat/blob/main/src/manager.py): `src/manager.py`
- [Quality metrics](https://github.com/isislab-unisa/kgheartbeat/tree/main/src/QualityDimensions): `src/QualityDimensions`
- [Scoring](https://github.com/isislab-unisa/kgheartbeat/blob/main/src/score.py): `src/score.py`
- [CSV results](https://github.com/isislab-unisa/kgheartbeat/blob/main/src/OutputCSV.py): `src/OutputCSV.py`
- [SPARQL queries](https://github.com/isislab-unisa/kgheartbeat/blob/main/src/query.py): `src/query.py`

### KG discovery

- [Metadata aggregator](https://github.com/isislab-unisa/kgheartbeat/blob/main/src/API/Aggregator.py): `src/API/Aggregator.py`
- [Metadata sources](https://github.com/isislab-unisa/kgheartbeat/tree/main/src/API): `src/API`
- [KG network](https://github.com/isislab-unisa/kgheartbeat/blob/main/src/Graph.py): `src/Graph.py`

### Web experience

- [Web application](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/App.js): `WebApp/front-end/kg-heartbeat/src/App.js`
- [KG search](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/pages/Search.js): `WebApp/front-end/kg-heartbeat/src/pages/Search.js`
- [Search results](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/components/SearchResults.js): `WebApp/front-end/kg-heartbeat/src/components/SearchResults.js`
- [Quality views](https://github.com/isislab-unisa/kgheartbeat/tree/main/WebApp/front-end/kg-heartbeat/src/pages): `WebApp/front-end/kg-heartbeat/src/pages`
- [Score view](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/pages/Score.js): `WebApp/front-end/kg-heartbeat/src/pages/Score.js`
- [Rankings](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/pages/Ranking.js): `WebApp/front-end/kg-heartbeat/src/pages/Ranking.js`
- [Analysis upload](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/front-end/kg-heartbeat/src/pages/UploadAnalysis.js): `WebApp/front-end/kg-heartbeat/src/pages/UploadAnalysis.js`

### Web API and storage

- [HTTP server](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/back-end/server.js): `WebApp/back-end/server.js`
- [Analysis routes](https://github.com/isislab-unisa/kgheartbeat/tree/main/WebApp/back-end/routes): `WebApp/back-end/routes`
- [Analysis queries](https://github.com/isislab-unisa/kgheartbeat/blob/main/WebApp/back-end/db.js): `WebApp/back-end/db.js`
- **MongoDB**

### Other components

- **Operator**
- **Knowledge graph endpoint**

## Connections

- Operator → Analysis runner: runs analysis
- Analysis runner → Metadata aggregator: resolves metadata (evidence: `src/manager.py`)
- Metadata aggregator → Metadata sources: queries sources (evidence: `src/API/Aggregator.py`)
- KG network → Metadata aggregator: uses metadata (evidence: `src/Graph.py`)
- KG network → Metadata sources: queries registry (evidence: `src/Graph.py`)
- Analysis runner → Knowledge graph endpoint: accepts endpoint
- SPARQL queries → Knowledge graph endpoint: sends queries (evidence: `src/query.py`)
- Analysis runner → Quality metrics: runs measurements
- Analysis runner → Scoring: computes scores (evidence: `src/manager.py`)
- Analysis runner → CSV results: writes results (evidence: `src/manager.py`)
- Operator → Web application: views results
- Web application → KG search: routes to (evidence: `WebApp/front-end/kg-heartbeat/src/App.js`)
- Web application → Quality views: routes to (evidence: `WebApp/front-end/kg-heartbeat/src/App.js`)
- Web application → Score view: routes to (evidence: `WebApp/front-end/kg-heartbeat/src/App.js`)
- Web application → Rankings: routes to (evidence: `WebApp/front-end/kg-heartbeat/src/App.js`)
- Web application → Analysis upload: routes to (evidence: `WebApp/front-end/kg-heartbeat/src/App.js`)
- KG search → Search results: renders results (evidence: `WebApp/front-end/kg-heartbeat/src/pages/Search.js`)
- HTTP server → Analysis routes: mounts routes (evidence: `WebApp/back-end/server.js`)
- Analysis routes → Analysis queries: queries analyses (evidence: `WebApp/back-end/routes/contextual.js`)
- HTTP server → Analysis queries: connects database (evidence: `WebApp/back-end/server.js`)
- Analysis queries → MongoDB: reads analyses (evidence: `WebApp/back-end/db.js`)
