# ise-fizkarlsruhe/chemotion-kg architecture

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

- Interactive diagram: https://gitdiagram.com/ise-fizkarlsruhe/chemotion-kg
- Repository: https://github.com/ise-fizkarlsruhe/chemotion-kg

## Overview

Chemotion-KG is a chemical-research knowledge graph, with repository code focused on acquiring publication metadata and transforming RDF/JSON-LD into graph outputs. The visible workflow downloads publication JSON-LD into a year/month data store; separate processors merge records, create per-year graphs, or transform RDF into NFDI Core form, and another utility partitions an RDF graph by subject. These scripts are not wired into one end-to-end runner in the sampled evidence. The README describes FAIR graph data, but does not document a query service; the repository also includes a Turtle graph and query documentation.

Main entry points: [`processing/worker_downloader.py`](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/worker_downloader.py) (Publication downloader), [`data`](https://github.com/ise-fizkarlsruhe/chemotion-kg/tree/main/data) (Downloaded JSON-LD), [`processing/main_parallel_downloader.py`](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/main_parallel_downloader.py) (Parallel downloader), [`processing/all.py`](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/all.py) (Graph merger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Metadata acquisition"]
  node_parallel_runner["Parallel downloader"]
  node_worker["Publication downloader"]
  node_jsonld_store[("Downloaded JSON-LD")]
end

subgraph group_rdfprocessing["RDF processing"]
  node_merge_graph["Graph merger<br/>[all.py]"]
  node_yearly_convert["Yearly converter<br/>[convert-all.py]"]
  node_nfdicore_transform["NFDI Core transform<br/>[all-nfdicore.py]"]
  node_graph_splitter["Subject splitter"]
end

subgraph group_outputs["Graph outputs"]
  node_merged_output[("Merged RDF")]
  node_yearly_output[("Yearly RDF")]
  node_split_output[("RDF chunks")]
  node_static_graph[("Knowledge graph<br/>[chemotion-kg.ttl]")]
end

node_researcher(("Research user"))
node_chemotion_api{{"Chemotion API"}}

node_researcher -.->|"starts download"| node_parallel_runner
node_parallel_runner -->|"launches subprocess"| node_worker
node_worker -->|"fetches publications"| node_chemotion_api
node_worker -->|"writes JSON-LD"| node_jsonld_store
node_jsonld_store -->|"reads JSON-LD"| node_merge_graph
node_merge_graph -->|"serializes merged graph"| node_merged_output
node_jsonld_store -->|"reads JSON-LD"| node_yearly_convert
node_yearly_convert -->|"writes yearly graphs"| node_yearly_output
node_researcher -.->|"provides RDF input"| node_nfdicore_transform
node_nfdicore_transform -.->|"returns transformed graph"| node_researcher
node_researcher -->|"provides RDF input"| node_graph_splitter
node_graph_splitter -->|"writes chunks"| node_split_output

click node_parallel_runner "https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/main_parallel_downloader.py"
click node_worker "https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/worker_downloader.py"
click node_jsonld_store "https://github.com/ise-fizkarlsruhe/chemotion-kg/tree/main/data"
click node_merge_graph "https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/all.py"
click node_yearly_convert "https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/convert-all.py"
click node_nfdicore_transform "https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/all-nfdicore.py"
click node_graph_splitter "https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/split_by_subject.py"
click node_static_graph "https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/data/chemotion-kg.ttl"

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_parallel_runner,node_worker,node_jsonld_store,node_researcher toneBlue
class node_merge_graph,node_yearly_convert,node_nfdicore_transform,node_graph_splitter toneAmber
class node_merged_output,node_yearly_output,node_split_output,node_static_graph,node_chemotion_api toneMint
```

## Components

### Metadata acquisition

- [Parallel downloader](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/main_parallel_downloader.py): `processing/main_parallel_downloader.py`
- [Publication downloader](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/worker_downloader.py): `processing/worker_downloader.py`
- [Downloaded JSON-LD](https://github.com/ise-fizkarlsruhe/chemotion-kg/tree/main/data): `data`

### RDF processing

- [Graph merger](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/all.py): `processing/all.py`
- [Yearly converter](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/convert-all.py): `processing/convert-all.py`
- [NFDI Core transform](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/all-nfdicore.py): `processing/all-nfdicore.py`
- [Subject splitter](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/processing/split_by_subject.py): `processing/split_by_subject.py`

### Graph outputs

- **Merged RDF**
- **Yearly RDF**
- **RDF chunks**
- [Knowledge graph](https://github.com/ise-fizkarlsruhe/chemotion-kg/blob/main/data/chemotion-kg.ttl): `data/chemotion-kg.ttl`

### Other components

- **Research user**
- **Chemotion API**

## Connections

- Research user → Parallel downloader: starts download
- Parallel downloader → Publication downloader: launches subprocess (evidence: `processing/main_parallel_downloader.py`)
- Publication downloader → Chemotion API: fetches publications (evidence: `processing/worker_downloader.py`)
- Publication downloader → Downloaded JSON-LD: writes JSON-LD (evidence: `processing/worker_downloader.py`)
- Downloaded JSON-LD → Graph merger: reads JSON-LD (evidence: `processing/all.py`)
- Graph merger → Merged RDF: serializes merged graph (evidence: `processing/all.py`)
- Downloaded JSON-LD → Yearly converter: reads JSON-LD (evidence: `processing/convert-all.py`)
- Yearly converter → Yearly RDF: writes yearly graphs (evidence: `processing/convert-all.py`)
- Research user → NFDI Core transform: provides RDF input
- NFDI Core transform → Research user: returns transformed graph
- Research user → Subject splitter: provides RDF input (evidence: `processing/split_by_subject.py`)
- Subject splitter → RDF chunks: writes chunks (evidence: `processing/split_by_subject.py`)
