# devingupta1/biographrag architecture

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

- Interactive diagram: https://gitdiagram.com/devingupta1/biographrag
- Repository: https://github.com/devingupta1/biographrag

## Overview

##### Project Type and Purpose
- BioGraphRAG is a full-stack solution focused on biomedical knowledge graphs (starting with BioKG) and their integration with large language models (LLMs).
- Its main goal is to ingest and analyze biomedical triplets into a NebulaGraph database and provide both interactive and analytical capabilities via distinct frontend and backend components.

##### File Structure
- Top-level directories:
- backend: Contains core application code including configuration (config.py), main API logic (main.py), database setup (setup_biokg_graphdb.py), and utility functions.
- frontend: Houses the Chainlit-based UI configuration and application (app.py) with its own Chainlit config files.
- analysis: Includes multiple Python scripts for performing specific graph analyses (e.g., HighDegreeAnalysis.py, MidDegreeAnalysis.py, etc.) as well as CSV processing scripts.
- scripts: Contains supporting scripts such as entity type mappings and a separate Streamlit app for potential additional visualization.
- Root-level files and configuration files (e.g., README, gitignore) support project operations and version control.
- Configuration/Deployment Aids:
- Environment variable instructions in the README suggest reliance on Docker (for NebulaGraph), Conda, and Git LFS, hinting at a containerized database and controlled Python environments.

##### Key Architectural Components
a. Main Components to Represent
- Frontend UI: The Chainlit-driven user interface (frontend/app.py) that users interact with.
- Backend API: The core application server (backend/main.py) handling API endpoints, interfacing with NebulaGraph, and coordinating LLM interactions.
- Graph Database: NebulaGraph instance (typically running in a Docker container per instructions) which stores and serves the biomedical knowledge graph triplets.
- Analysis Modules: A set of analysis scripts (in the analysis folder) used for various degrees of graph analysis, and potentially generating visual reports.
- Utility/Setup Scripts: Additional supporting scripts (in the scripts folder) for configuring mappings or running alternative interfaces (Streamlit app).
- External Services: LLMs (via OpenAI API) invoked during GraphRAG processes and possibly additional external APIs (if any) as defined by environment variables.

b. Relationships and Interactions
- The Frontend and Backend communicate via API calls; the frontend (Chainlit) sends user queries which the backend handles.
- The Backend connects to the NebulaGraph database to execute queries and insert triplets (notably via the setup_biokg_graphdb.py script).
- Analysis scripts periodically or interactively process graph data — reading from CSV outputs (or directly from NebulaGraph) — and produce insights.
- The system utilizes environment variables (like OpenAI API keys) to communicate with external LLM services when required.

c. Architectural Patterns / Design Principles
- Modular separation: Distinct directories separate responsibilities (UI, backend logic, data analysis, utility scripts).
- Microservices-like aspects: Although in a single repository, a clear division exists (web interface vs. API backend vs. analysis scripts).
- Containerization: Use of Docker Desktop for NebulaGraph emphasizes a containerized data persistence layer.
- Configuration-driven: Extensive use of environmental variables indicates a design that favors external configuration for deployment agility.

d. Relevant Technologies & Libraries
- NebulaGraph: Graph database for storing triplets.
- Chainlit: Frontend framework for interactive chatbot-like UI.
- Uvicorn: ASGI server (as invoked by uvicorn main:app) for backend service hosting.
- Python environment (Conda): Managing dependencies.
- Docker: For running NebulaGraph efficiently in containers.
- OpenAI API: For LLM integrations as indicated by environment variables.
- Streamlit: Alternative visualization interface provided in scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        FE_UI["Frontend UI (Chainlit)"]:::frontend
        FE_Config["Chainlit Config Files"]:::frontend
    end

    %% Application Logic Layer
    subgraph "Application Logic Layer"
        subgraph "Backend API Service"
            BE1["main.py"]:::backend
            BE2["config.py"]:::backend
            BE3["setup_biokg_graphdb.py"]:::backend
            BE4["utils.py"]:::backend
        end
    end

    %% Data Persistence Layer
    subgraph "Data Persistence Layer"
        DB["Graph Database (NebulaGraph)"]:::database
        DB2["BioKG Data Package"]:::database
    end

    %% Analysis/Utility Layer
    subgraph "Analysis/Utility Layer"
        subgraph "Analysis Modules"
            AN1["HighDegreeAnalysis.py"]:::analysis
            AN2["MidDegreeAnalysis.py"]:::analysis
            AN3["LowDegreeAnalysis.py"]:::analysis
            AN4["analysis_csv.py"]:::analysis
            AN5["combined_analysis.py"]:::analysis
        end
        subgraph "Utility/Support Scripts"
            UT1["create_entity_type_mappings.py"]:::utility
            UT2["streamlit_app.py"]:::utility
        end
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM Service (OpenAI API)"]:::external
    end

    %% Connections
    FE_UI -->|"API_Call"| BE1
    BE3 -->|"DBSetup"| DB
    BE1 -.->|"LLM_Call"| LLM
    AN1 -->|"Analysis_Query"| DB
    UT2 -.->|"Visualization_Interface"| DB

    %% Styles
    classDef frontend fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef backend fill:#00ced1,stroke:#333,stroke-width:2px;
    classDef database fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef analysis fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef utility fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;

    %% Click Events for Frontend
    click FE_UI "https://github.com/devingupta1/biographrag/blob/main/frontend/app.py"
    click FE_Config "https://github.com/devingupta1/biographrag/blob/main/frontend/.chainlit"

    %% Click Events for Backend
    click BE1 "https://github.com/devingupta1/biographrag/blob/main/backend/main.py"
    click BE2 "https://github.com/devingupta1/biographrag/blob/main/backend/config.py"
    click BE3 "https://github.com/devingupta1/biographrag/blob/main/backend/setup_biokg_graphdb.py"
    click BE4 "https://github.com/devingupta1/biographrag/blob/main/backend/utils.py"

    %% Click Events for Graph Database
    click DB2 "https://github.com/devingupta1/biographrag/blob/main/bioKG.tar.gz"

    %% Click Events for Analysis Modules
    click AN1 "https://github.com/devingupta1/biographrag/blob/main/analysis/HighDegreeAnalysis.py"
    click AN2 "https://github.com/devingupta1/biographrag/blob/main/analysis/MidDegreeAnalysis.py"
    click AN3 "https://github.com/devingupta1/biographrag/blob/main/analysis/LowDegreeAnalysis.py"
    click AN4 "https://github.com/devingupta1/biographrag/blob/main/analysis/analysis_csv.py"
    click AN5 "https://github.com/devingupta1/biographrag/blob/main/analysis/combined_analysis.py"

    %% Click Events for Utility/Support Scripts
    click UT1 "https://github.com/devingupta1/biographrag/blob/main/scripts/create_entity_type_mappings.py"
    click UT2 "https://github.com/devingupta1/biographrag/blob/main/scripts/streamlit_app.py"
```
