# snowteam2023/medrag architecture

> Architecture diagram of the GitHub repository snowteam2023/medrag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snowteam2023/medrag
- Repository: https://github.com/snowteam2023/medrag

## Overview

##### Project Type and Purpose
- MedRAG is a research-driven, full-fledged implementation for a healthcare copilot that integrates knowledge graphs into RAG models.
- Its purpose is to improve diagnostic accuracy through enhanced reasoning and retrieval by leveraging a diagnostic knowledge graph, as described in the README.

##### Main Components to Highlight
a. Data & Knowledge Ingestion:
- Dataset: Represented by the “dataset” directory which includes the “knowledge graph of DDXPlus.xlsx”. This file is used for building the disease knowledge graph.
- Embeddings: The “Embeddings_saved” directory contains pre-computed embeddings (CP_DC_embeddings and CP_KG_embeddings) that are used to represent either the clinical data or the knowledge graph nodes.
b. Core Processing Units:
- Knowledge Graph Construction Module: This includes hierarchical aggregation logic (referenced in the README figures and images like DDXPlusKG.pdf) that builds and maintains the disease knowledge graph.
- RAG-based Reasoning Module: This module integrates EHR retrieval with the diagnostic knowledge graph for enhanced reasoning. It is central to the MedRAG approach.
- KG Retrieval Module: Indicated by the file “KG_Retrieve.py”, this module likely handles the retrieval of relevant knowledge from the constructed graph given a query.
c. User Interface / Execution Entry Points:
- Main Application Scripts: “main.py” and “main_MedRAG.py” are the primary entry points. They coordinate the processing workflows, invoking data ingestion, retrieval, and diagnostic suggestion generation.
- Authentication & API Integration: “authentication.py” handles token management for third-party services like OpenAI’s API and Hugging Face, ensuring that external model calls are authenticated.
d. Evaluation & Metrics:
- Metrics: The “metrics” directory (e.g., “metrics DDXPlus.py”) is used for evaluation and performance measurement of the model outputs compared to baselines.
e. Supporting Artifacts:

##### Relationships and Interactions
- Embeddings Flow: The pre-computed embeddings stored under Embeddings_saved are fed into the retrieval modules to facilitate faster, high-quality matching.
- Authentication and External APIs: The authentication module connects to external language model APIs (OpenAI/Hugging Face) with tokens, which are then used by the RAG module for generating diagnostic recommendations.
- Control Flow: The main scripts (main.py and main_MedRAG.py) integrate the above components. They orchestrate the flow from input data, through retrieval and reasoning, to output (diagnostic suggestions along with follow-up questions).

##### Architectural Patterns & Key Design Principles
- Modularity: Each component (data ingestion, KG construction, retrieval, reasoning, and evaluation) is clearly separated for better maintainability.
- Pipeline Workflow: The architecture is primarily a data processing pipeline where raw clinical data and knowledge graphs are sequentially processed, combined with real-time API calls for augmented generation.
- Extensibility/Plug-in Points: The design should allow easy swapping or enhancement of individual modules (for instance, different backbone LLMs or an updated KG_Retrieve component).

##### Relevant Technologies & Frameworks
- APIs: Usage of OpenAI and Hugging Face LLM APIs for augmentation.
- Data Processing: Excel-based datasets and pre-saved embeddings.
- Evaluation: Custom metrics scripts for measuring diagnostic accuracy across multiple criteria.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data & Knowledge Ingestion"
        d1["Dataset (Knowledge Graph Excel)"] 
        d2["Embeddings Storage"]
    end

    subgraph "Core Processing Units"
        p1["Knowledge Graph Construction"]
        p2["KG Retrieval Module"]
        p3["RAG-based Reasoning Module"]
    end

    subgraph "User Interface & External Integration"
        e1["API Authentication & External Model Calls"]
        e2["Main Orchestration & Execution"]
    end

    subgraph "Evaluation & Artifacts"
        ev["Evaluation & Metrics"]
        vis["Visualizations & Supporting Artifacts"]
    end

    %% Data Flow
    d1 -->|"feeds"| p1
    d2 -->|"provides embeddings to"| p2
    p1 -->|"supplies info to"| p2
    p2 -->|"retrieved data sent to"| p3
    e1 -->|"supports"| p3
    e2 -->|"orchestrates"| p1
    e2 -->|"initiates"| p2
    e2 -->|"controls"| p3
    p3 -->|"outputs results to"| ev
    vis -.->|"references"| ev

    %% Click Events
    click d1 "https://github.com/snowteam2023/medrag/blob/main/dataset/knowledge graph of DDXPlus.xlsx"
    click d2 "https://github.com/snowteam2023/medrag/tree/main/Embeddings_saved/"
    click p1 "https://github.com/snowteam2023/medrag/blob/main/images/DDXPlusKG.pdf"
    click p2 "https://github.com/snowteam2023/medrag/blob/main/KG_Retrieve.py"
    click e1 "https://github.com/snowteam2023/medrag/blob/main/authentication.py"
    click e2 "https://github.com/snowteam2023/medrag/blob/main/main.py"
    click e2 "https://github.com/snowteam2023/medrag/blob/main/main_MedRAG.py"
    click ev "https://github.com/snowteam2023/medrag/blob/main/metrics/metrics DDXPlus.py"
    click vis "https://github.com/snowteam2023/medrag/tree/main/images/"

    %% Styles
    classDef ingestion fill:#B0E0E6,stroke:#000,stroke-width:2px;
    classDef processing fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef external fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef evaluation fill:#FFB6C1,stroke:#000,stroke-width:2px;

    class d1,d2 ingestion;
    class p1,p2,p3 processing;
    class e1,e2 external;
    class ev,vis evaluation;
```
