# youssefelgharbaouidevs/disease-pathway-graphrag architecture

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

- Interactive diagram: https://gitdiagram.com/youssefelgharbaouidevs/disease-pathway-graphrag
- Repository: https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag

## Overview

Disease Pathway GraphRAG is an academic prototype for exploring publication-backed disease relationships. Its current workflow starts with Jensen supplementary workbooks: extraction preserves source values, preparation creates pair evidence and separate full trajectories, review checks provenance, and import loads the records into local Neo4j. Users can then request bounded forward, backward, or combined searches by diagnosis code. The README also describes a future application and supporting-passage GraphRAG explanations, but these are not implemented. Relationships below are limited to calls or data flows shown in excerpts or explicitly documented; unsampled subsystems are not assumed to be wired.

Main entry points: [`src/extraction/extract_jensen.py`](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/extraction/extract_jensen.py) (Workbook extraction), [`src/graph/explore.py`](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/explore.py) (Bounded graph search), [`src/graph/import_jensen.py`](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/import_jensen.py) (Graph importer), [`src/graph/neo4j_client.py`](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/neo4j_client.py) (Neo4j HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus["Research corpus"]
  node_papers["Scientific papers"]
  node_register["Source register<br/>[sources.json]"]
  node_supplements["Jensen supplements"]
end

subgraph group_prep["Evidence preparation"]
  node_extract["Workbook extraction<br/>[extract_jensen.py]"]
  node_pair_tables["Pair graph tables"]
  node_trajectory_tables["Trajectory preparation"]
  node_review["Extraction review<br/>[review_jensen.py]"]
end

subgraph group_graph["Graph storage"]
  node_importer["Graph importer<br/>[import_jensen.py]"]
  node_client["Neo4j HTTP client<br/>[neo4j_client.py]"]
  node_neo4j[("Local Neo4j")]
  node_setup["Local database setup<br/>[local_neo4j.py]"]
end

subgraph group_explore["Search workflow"]
  node_search["Bounded graph search<br/>[explore.py]"]
  node_search_results["Evidence-linked results<br/>[explore.py]"]
end

subgraph group_planned["Planned experience"]
  node_retrieval["Passage retrieval"]
  node_explanations["Cited explanations"]
  node_app["Demonstration interface"]
end

node_user(("Research user"))

node_papers -->|"registered in"| node_register
node_supplements -->|"exports tables"| node_extract
node_register -->|"checks source identity"| node_extract
node_extract -->|"provides pair records"| node_pair_tables
node_extract -->|"provides trajectory records"| node_trajectory_tables
node_pair_tables -->|"provides diagnosis tables"| node_trajectory_tables
node_extract -->|"checks extraction"| node_review
node_pair_tables -->|"supplies graph tables"| node_importer
node_trajectory_tables -->|"supplies trajectories"| node_importer
node_review -->|"gates import"| node_importer
node_importer -->|"uses"| node_client
node_client -->|"commits queries"| node_neo4j
node_setup -->|"checks readiness"| node_client
node_setup -->|"starts instance"| node_neo4j
node_user -->|"searches concept"| node_search
node_search -->|"queries graph"| node_client
node_search -->|"returns paths"| node_search_results
node_search_results -->|"shows connections"| node_user
node_search_results -.->|"could retrieve passages"| node_retrieval
node_retrieval -.->|"could ground claims"| node_explanations
node_app -.->|"could expose searches"| node_search
node_explanations -.->|"could present citations"| node_user

click node_papers "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/ressources"
click node_register "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/ressources/sources.json"
click node_supplements "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/ressources/supplements"
click node_extract "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/extraction/extract_jensen.py"
click node_pair_tables "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/extraction/prepare_jensen_graph_tables.py"
click node_trajectory_tables "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/extraction/prepare_jensen_trajectories.py"
click node_review "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/review_jensen.py"
click node_importer "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/import_jensen.py"
click node_client "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/neo4j_client.py"
click node_setup "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/local_neo4j.py"
click node_search "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/explore.py"
click node_search_results "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/explore.py"
click node_retrieval "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/src/retrieval"
click node_explanations "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/src/retrieval"
click node_app "https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/app"

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_papers,node_register,node_supplements,node_user toneBlue
class node_extract,node_pair_tables,node_trajectory_tables,node_review toneAmber
class node_importer,node_client,node_neo4j,node_setup toneMint
class node_search,node_search_results toneRose
class node_retrieval,node_explanations,node_app toneIndigo
```

## Components

### Research corpus

- [Scientific papers](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/ressources): `ressources`
- [Source register](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/ressources/sources.json): `ressources/sources.json`
- [Jensen supplements](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/ressources/supplements): `ressources/supplements`

### Evidence preparation

- [Workbook extraction](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/extraction/extract_jensen.py): `src/extraction/extract_jensen.py`
- [Pair graph tables](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/extraction/prepare_jensen_graph_tables.py): `src/extraction/prepare_jensen_graph_tables.py`
- [Trajectory preparation](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/extraction/prepare_jensen_trajectories.py): `src/extraction/prepare_jensen_trajectories.py`
- [Extraction review](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/review_jensen.py): `src/graph/review_jensen.py`

### Graph storage

- [Graph importer](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/import_jensen.py): `src/graph/import_jensen.py`
- [Neo4j HTTP client](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/neo4j_client.py): `src/graph/neo4j_client.py`
- **Local Neo4j**
- [Local database setup](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/local_neo4j.py): `src/graph/local_neo4j.py`

### Search workflow

- [Bounded graph search](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/explore.py): `src/graph/explore.py`
- [Evidence-linked results](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/blob/main/src/graph/explore.py): `src/graph/explore.py`

### Planned experience

- [Passage retrieval](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/src/retrieval): `src/retrieval`
- [Cited explanations](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/src/retrieval): `src/retrieval`
- [Demonstration interface](https://github.com/youssefelgharbaouidevs/disease-pathway-graphrag/tree/main/app): `app`

### Other components

- **Research user**

## Connections

- Scientific papers → Source register: registered in (evidence: `README.md`)
- Jensen supplements → Workbook extraction: exports tables (evidence: `src/extraction/extract_jensen.py`)
- Source register → Workbook extraction: checks source identity (evidence: `src/extraction/extract_jensen.py`)
- Workbook extraction → Pair graph tables: provides pair records (evidence: `src/extraction/prepare_jensen_graph_tables.py`)
- Workbook extraction → Trajectory preparation: provides trajectory records (evidence: `src/extraction/prepare_jensen_trajectories.py`)
- Pair graph tables → Trajectory preparation: provides diagnosis tables (evidence: `src/extraction/prepare_jensen_trajectories.py`)
- Workbook extraction → Extraction review: checks extraction (evidence: `src/graph/review_jensen.py`)
- Pair graph tables → Graph importer: supplies graph tables (evidence: `README.md`)
- Trajectory preparation → Graph importer: supplies trajectories (evidence: `README.md`)
- Extraction review → Graph importer: gates import (evidence: `README.md`)
- Graph importer → Neo4j HTTP client: uses (evidence: `src/graph/import_jensen.py`)
- Neo4j HTTP client → Local Neo4j: commits queries (evidence: `src/graph/neo4j_client.py`)
- Local database setup → Neo4j HTTP client: checks readiness (evidence: `src/graph/local_neo4j.py`)
- Local database setup → Local Neo4j: starts instance (evidence: `src/graph/local_neo4j.py`)
- Research user → Bounded graph search: searches concept (evidence: `README.md`)
- Bounded graph search → Neo4j HTTP client: queries graph (evidence: `src/graph/explore.py`)
- Bounded graph search → Evidence-linked results: returns paths (evidence: `src/graph/explore.py`)
- Evidence-linked results → Research user: shows connections (evidence: `README.md`)
- Evidence-linked results → Passage retrieval: could retrieve passages (evidence: `README.md`)
- Passage retrieval → Cited explanations: could ground claims (evidence: `README.md`)
- Demonstration interface → Bounded graph search: could expose searches (evidence: `README.md`)
- Cited explanations → Research user: could present citations (evidence: `README.md`)