MedGraphRAG

MedGraphRAG is a robust, graph-augmented retrieval and interactive clinical simulation platform designed for medical education, clinical pathway tracking, and automated research reporting.

1. Project Overview

MedGraphRAG bridges the gap between static medical guidelines and interactive clinical reasoning. It supports an immersive "Graph Simulation Runtime" that evaluates clinical decision-making dynamically, as well as a rich Visual Authoring environment for Medical Educators to construct, manage, and publish complex clinical scenarios.

2. Visual Scenario Authoring (Current Implementation Focus)

The platform provides a comprehensive visual authoring suite for Medical Educators:

• Scenario Catalog: A unified interface to browse, search, and filter clinical scenarios.
• Scenario Lifecycle & Governance: Strict state management moving scenarios through draft -> under_review -> approved -> published -> archived. Governance hashes track structural integrity and audit logs capture all lifecycle changes.
• Scenario Authoring Workspace: A React and Cytoscape.js based visual editor. Features a node-link Graph Canvas allowing authors to create clinical states, define branching pathways, and design clinical logic visually.
• Catalog → Editor Workflow: Seamless integration allowing users to open scenarios directly from the Catalog into the Authoring Workspace.
• Scenario Persistence: RESTful endpoints with a controlled merge strategy ensure the underlying JSON graph truth is preserved without corrupting metadata during saving operations.

3. Evidence & Media Architecture

Scenarios are enriched with clinical evidence assets to simulate real-world diagnostic environments:

• Media Catalog & Evidence Assets: Scenarios can assign visual evidence (e.g., 12-lead ECGs, imaging) to specific clinical states. These assets are tracked within the scenario's JSON schema and surface during the simulation.
• Evidence Panel: The frontend architecture includes dedicated sidebars to assign and manage these assets on a per-node basis.

4. Architecture Overview

MedGraphRAG uses a strict separation of concerns for data governance:

• Neo4j = Clinical Truth: Authoritative source for competency mappings, learning objectives, educational frameworks, and scenario metadata.
• SQLite = Analytics Truth: Authoritative source for session analytics, longitudinal metrics, and pseudonymized learner telemetry.
• DashboardAPI: The integration layer facilitating reads (Join-at-Read architecture) without complex ETL pipelines.

5. Technology Stack

• Frontend: React, Vite, TailwindCSS, Cytoscape.js
• Backend: Python, Flask, llama-cpp-python
• Databases: Neo4j (Knowledge Graph), SQLite (Analytics & Telemetry), FAISS
• Modeling: Local GGUF models (e.g., Qwen 2.5 3B Instruct) and MiniLM embeddings

6. Installation & Setup

Prerequisites

• Python 3.10+
• Node.js 18+
• Neo4j Desktop or Neo4j Docker container

git clone https://github.com/your-org/medgraphrag.git
cd medgraphrag

Environment Configuration

Copy the template configuration and modify it with your local settings. Never commit the .env file.

cp .env.template .env

Backend Startup

cd backend
python -m venv .venv
source .venv/bin/activate  # Or .venv\Scripts\activate on Windows
pip install -r requirements.txt

# Start the Flask server
python server.py

Frontend Startup

Create a .env.local file in the frontend directory with VITE_API_URL=http://127.0.0.1:5050 to ensure proper IPv4 resolution.

cd frontend
npm install
npm run dev

Current Status

Completed Milestones

• Scenario Catalog UI and Backend API
• Scenario Metadata Viewer
• Visual Graph Canvas (Cytoscape integration)
• Create Node & Create Branch capabilities
• Open Existing Scenario / Open STEMI Graph workflow
• Save to Backend (Persistence)

Remaining Issues

• Scenario Persistence Validation: Needs thorough verification after a full save/reload cycle to ensure complex graph states survive accurately.

Next Priorities

• Phase 3: Evidence & Media Catalog implementation.
• Stabilize and fix the Edit Node Sidebar rendering bug.
• End-to-end integration of Visual Scenarios into the Simulation Engine.

Known Issues

• Edit Node Sidebar Rendering Bug: The right-hand sidebar for editing node properties currently does not render consistently when a node is selected on the canvas. This is an active rendering issue that interrupts the node property authoring flow and prevents assigning titles, types, and media URLs to newly created nodes.

Download Required Models

The repository does not contain local model weights.

Download:

• moondream2-text-model-f16.gguf
• moondream2-mmproj-f16.gguf

Place them in: backend/models/

Example:

backend/models/
├── moondream2-text-model-f16.gguf
└── moondream2-mmproj-f16.gguf