# marat-kabirov/kg-evolution-explorer architecture

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

- Interactive diagram: https://gitdiagram.com/marat-kabirov/kg-evolution-explorer
- Repository: https://github.com/marat-kabirov/kg-evolution-explorer

## Overview

KG Evolution Explorer lets analysts search for an entity and inspect its change history, timeline, and graph neighbourhood without querying the knowledge graph directly. The React app coordinates search and selection with the FastAPI API; the API reads a normalized change log from SQLite and returns entity, history, and neighbourhood data. Dataset preparation is a separate route: Wikidata ingestion or generic CSV import produces data for the same schema. The README documents the major visualizations and source-agnostic import path; some ingestion internals were not sampled, so only documented, supported connections are shown.

Main entry points: [`frontend/src/App.jsx`](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/App.jsx) (App state), [`backend/ingest.py`](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/ingest.py) (Wikidata ingestion), [`backend/import_changelog.py`](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/import_changelog.py) (CSV import), [`frontend/src/components/EntitySearch.jsx`](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/EntitySearch.jsx) (Entity search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Explorer UI"]
  node_app["App state<br/>[App.jsx]"]
  node_search["Entity search<br/>[EntitySearch.jsx]"]
  node_timeline["Timeline<br/>[TimeLine.jsx]"]
  node_detail["Change log<br/>[EntityDetail.jsx]"]
  node_graph["Graph view<br/>[GraphView.jsx]"]
end

subgraph group_api["API and Storage"]
  node_api_service["REST API<br/>[main.py]"]
  node_db_access["Database queries<br/>[db.py]"]
  node_entity_index["Entity search index<br/>[entity_index.py]"]
  node_sqlite[("Change log database")]
end

subgraph group_ingestion["Change Log Ingestion"]
  node_wikidata_ingest["Wikidata ingestion<br/>[ingest.py]"]
  node_csv_import["CSV import"]
  node_schema["Normalized schema"]
end

subgraph group_external["External Data"]
  node_wikidata{{"Wikidata"}}
end

node_analyst(("Data analyst"))
node_csv_source["Change-log CSV"]

node_analyst -->|"searches"| node_search
node_search -->|"selects entity"| node_app
node_app -->|"requests data"| node_api_service
node_search -->|"searches entities"| node_api_service
node_api_service -->|"queries"| node_db_access
node_db_access -->|"reads"| node_sqlite
node_db_access -->|"searches labels"| node_entity_index
node_app -->|"supplies history"| node_timeline
node_app -->|"supplies history"| node_detail
node_app -->|"supplies neighbours"| node_graph
node_timeline -->|"sets time range"| node_app
node_graph -->|"selects neighbour"| node_app
node_analyst -.->|"requests dataset"| node_wikidata_ingest
node_wikidata_ingest -.->|"fetches data"| node_wikidata
node_wikidata_ingest -->|"uses schema"| node_schema
node_wikidata_ingest -->|"writes events"| node_sqlite
node_csv_source -->|"provides rows"| node_csv_import
node_csv_import -->|"validates rows"| node_schema
node_csv_import -->|"rebuilds index"| node_entity_index
node_csv_import -->|"writes events"| node_sqlite

click node_app "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/App.jsx"
click node_search "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/EntitySearch.jsx"
click node_timeline "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/TimeLine.jsx"
click node_detail "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/EntityDetail.jsx"
click node_graph "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/GraphView.jsx"
click node_api_service "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/main.py"
click node_db_access "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/db.py"
click node_entity_index "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/entity_index.py"
click node_sqlite "https://github.com/marat-kabirov/kg-evolution-explorer/tree/main/backend/data"
click node_wikidata_ingest "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/ingest.py"
click node_csv_import "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/import_changelog.py"
click node_schema "https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/changelog_schema.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_app,node_search,node_timeline,node_detail,node_graph toneBlue
class node_api_service,node_db_access,node_entity_index,node_sqlite toneAmber
class node_wikidata_ingest,node_csv_import,node_schema toneMint
class node_wikidata toneRose
class node_analyst,node_csv_source toneIndigo
```

## Components

### Explorer UI

- [App state](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Entity search](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/EntitySearch.jsx): `frontend/src/components/EntitySearch.jsx`
- [Timeline](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/TimeLine.jsx): `frontend/src/components/TimeLine.jsx`
- [Change log](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/EntityDetail.jsx): `frontend/src/components/EntityDetail.jsx`
- [Graph view](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/frontend/src/components/GraphView.jsx): `frontend/src/components/GraphView.jsx`

### API and Storage

- [REST API](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/main.py): `backend/main.py`
- [Database queries](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/db.py): `backend/db.py`
- [Entity search index](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/entity_index.py): `backend/entity_index.py`
- [Change log database](https://github.com/marat-kabirov/kg-evolution-explorer/tree/main/backend/data): `backend/data`

### Change Log Ingestion

- [Wikidata ingestion](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/ingest.py): `backend/ingest.py`
- [CSV import](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/import_changelog.py): `backend/import_changelog.py`
- [Normalized schema](https://github.com/marat-kabirov/kg-evolution-explorer/blob/main/backend/changelog_schema.py): `backend/changelog_schema.py`

### External Data

- **Wikidata**

### Other components

- **Data analyst**
- **Change-log CSV**

## Connections

- Data analyst → Entity search: searches
- Entity search → App state: selects entity
- App state → REST API: requests data
- Entity search → REST API: searches entities
- REST API → Database queries: queries
- Database queries → Change log database: reads
- Database queries → Entity search index: searches labels
- App state → Timeline: supplies history
- App state → Change log: supplies history
- App state → Graph view: supplies neighbours
- Timeline → App state: sets time range
- Graph view → App state: selects neighbour
- Data analyst → Wikidata ingestion: requests dataset
- Wikidata ingestion → Wikidata: fetches data
- Wikidata ingestion → Normalized schema: uses schema
- Wikidata ingestion → Change log database: writes events
- Change-log CSV → CSV import: provides rows
- CSV import → Normalized schema: validates rows
- CSV import → Entity search index: rebuilds index
- CSV import → Change log database: writes events