# rishabh-108272/multi-agentic-rag-for-biomarker-validation architecture

> Architecture diagram of the GitHub repository rishabh-108272/multi-agentic-rag-for-biomarker-validation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation
- Repository: https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation

## Overview

1. **Top-level shape**
   - The repo is split into two primary runtime boundaries:
     - `backend/`: a Django-based API and analysis engine.
     - `project/`: a React + TypeScript client built with Vite.
   - The frontend is mostly a presentation and orchestration layer; the backend owns the biomedical pipeline, persistence, and async work.

2. **User-facing flow**
   - The main user journey starts on `project/src/pages/HomePage.tsx`, where a CSV patient file is uploaded and analysis is initiated.
   - `project/src/pages/ResultsPage.tsx` then polls for progress and renders the outputs once backend processing completes.
   - The UI is decomposed into result-specific components such as subtype cards, gene/drug tables, agent reports, summary reports, and a progress view.

3. **Frontend integration boundary**
   - `project/src/lib/api.ts` is the client’s main HTTP bridge to the backend REST endpoints.
   - `project/src/lib/supabase.ts` plus the `project/supabase/migrations/` folder indicate a secondary persistence/integration layer on the frontend side, likely for analysis history or dashboard data.
   - The frontend is therefore not just static display; it coordinates upload, status polling, and result retrieval from backend services.

4. **Backend API layer**
   - The backend Django project lives under `backend/lung_cancer_api/`, with routing in `urls.py` and HTTP entry points in `views.py`.
   - The `backend/pipeline/views.py` and `backend/pipeline/urls.py` modules expose the analysis API surface: upload, status, results, summary retrieval, and cleanup.
   - This API layer is the external contract the frontend depends on.

5. **Async orchestration**
   - The heavy analysis is not handled inline with the request; it is orchestrated through Celery in `backend/lung_cancer_api/celery.py`, `backend/pipeline/tasks.py`, and `backend/pipeline/queue_tasks.py`.
   - This is the main scalability boundary: request/response traffic stays in Django, while long-running work is queued and processed separately.
   - The presence of `celerybeat-schedule*` files suggests scheduled/background execution is part of the runtime model as well.

6. **Core analysis pipeline**
   - The pipeline is a staged workflow that transforms raw CSV input into layered biomedical interpretation.
   - The stages visible in the repo are:
     1. input normalization,
     2. subtype classification,
     3. explainability and feature ranking,
     4. gene mapping,
     5. drug candidate discovery,
     6. multi-agent evidence validation,
     7. final summary synthesis.
   - `backend/pipeline/tasks.py` is the orchestration center for these steps.

7. **Subtype classification subsystem**
   - `backend/pipeline/ml_classifier.py` handles subtype prediction and confidence scoring.
   - The README indicates the implementation can call remote Hugging Face Spaces endpoints, so classification is effectively an external model service dependency rather than only local inference.
   - The current system supports at least lung and colorectal analysis flows.

8. **Explainability and gene interpretation**
   - `backend/pipeline/xai_engine.py` generates feature importance and explanation artifacts, likely using SHAP/LIME-style logic with fallback strategies for high-dimensional data.
   - `backend/pipeline/gene_mapper.py` and `backend/pipeline/gene_index_map.json` convert opaque model features into biologically interpretable gene-level entities.
   - This is an important semantic boundary: model outputs become domain-readable markers before downstream drug and evidence analysis.

9. **Drug candidate subsystem**
   - `backend/pipeline/drug_engine.py` links genes to possible therapeutic options, using interaction data such as DGIdb-derived associations.
   - The output of this stage is not a treatment recommendation engine by itself; it is a ranked candidate list that feeds later validation and reporting.
   - In architecture terms, this is the bridge from biomarker interpretation to therapeutic exploration.

10. **Multi-agent RAG validation layer**
   - `backend/pipeline/langgraph_pipeline.py` is the reasoning layer that validates and enriches intermediate results using a multi-agent RAG approach.
   - The README describes this stage as assembling evidence from biomedical literature and domain knowledge sources, then consolidating it into interpretable reports.
   - This is the system’s main “validation boundary”: predictions and drug suggestions are cross-checked against external evidence rather than presented alone.

11. **Persistence model**
   - `backend/pipeline/models.py` defines persisted analysis entities such as `PatientAnalysis`, `XAIResult`, `DrugCandidate`, `AgentReport`, and `PatientSummaryReport`.
   - These models capture the full lifecycle of a run: metadata, intermediate artifacts, agent outputs, and final summaries.
   - The backend uses Django migrations and, by default, SQLite, which makes persistence local and simple unless overridden in deployment.

12. **Result composition**
   - The final response to the client is assembled from multiple backend outputs rather than a single monolithic score.
   - The frontend renders this as separate sections: subtype prediction, driver genes, drug candidates, agent reports, and a summary narrative.
   - That separation mirrors the backend data model and makes the system well-suited for diagramming as a pipeline with fan-out/fan-in stages.

13. **Deployment/runtime boundaries**
   - The backend includes a `Dockerfile`, `requirements.txt`, and `runtime.txt`, indicating it is designed for containerized or platform-managed Python deployment.
   - The frontend includes `vercel.json`, showing it is intended for Vercel-style static hosting.
   - The overall architecture is therefore a decoupled web client plus a compute-heavy Python service with async workers and external biomedical APIs.

14. **What to emphasize in an architecture diagram**
   - Show the frontend as the entry point for upload and visualization.
   - Show the Django API as the control plane, Celery as the async execution plane, and the pipeline modules as sequential processing blocks.
   - Show external dependencies on Hugging Face model services, DGIdb, literature/evidence sources, and the LLM-backed agent layer.
   - Show persistence as a shared backend datastore for analyses, explanation artifacts, drug candidates, and generated reports.

Main entry points: [`backend/pipeline/tasks.py`](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/tasks.py) (Pipeline tasks), [`project/src/pages/ResultsPage.tsx`](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/pages/ResultsPage.tsx) (Results page), [`backend/lung_cancer_api`](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/tree/main/backend/lung_cancer_api) (Django API), [`backend/pipeline/langgraph_pipeline.py`](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/langgraph_pipeline.py) (RAG agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_home_page["Home page<br/>ui entry<br/>[HomePage.tsx]"]
  node_results_page["Results page<br/>ui results<br/>[ResultsPage.tsx]"]
  node_api_client["API client<br/>http bridge<br/>[api.ts]"]
  node_supabase_client["Supabase client<br/>integration layer<br/>[supabase.ts]"]
  node_upload_box["Upload box<br/>upload UI<br/>[UploadBox.tsx]"]
  node_pipeline_progress["Progress view<br/>status UI"]
  node_result_cards["Result views<br/>presentation components<br/>[SubtypeCard.tsx]"]
end

subgraph group_backend["Backend"]
  node_django_api["Django API<br/>backend app"]
  node_api_routes["API routes<br/>routing<br/>[urls.py]"]
  node_api_views["API views<br/>http handlers<br/>[views.py]"]
  node_pipeline_api["Pipeline API<br/>analysis endpoints<br/>[views.py]"]
  node_celery_orchestrator{{"Celery<br/>async orchestration<br/>[celery.py]"}}
  node_pipeline_tasks["Pipeline tasks<br/>workflow orchestration<br/>[tasks.py]"]
  node_queue_tasks["Queue tasks<br/>job workers<br/>[queue_tasks.py]"]
  node_classifier["Classifier<br/>subtype model<br/>[ml_classifier.py]"]
  node_xai_engine["XAI engine<br/>explainability<br/>[xai_engine.py]"]
  node_gene_mapper["Gene mapper<br/>gene interpretation<br/>[gene_mapper.py]"]
  node_drug_engine["Drug engine<br/>candidate ranking<br/>[drug_engine.py]"]
  node_rag_pipeline{{"RAG agents<br/>evidence validation"}}
  node_models[("Data models<br/>persistence model<br/>[models.py]")]
end

subgraph group_external["External services"]
  node_hf_model(("HF models<br/>external model service"))
  node_evidence_sources["Evidence sources<br/>literature data"]
  node_supabase_db[("Supabase<br/>external datastore")]
end

node_home_page -->|"uploads CSV"| node_upload_box
node_home_page -->|"start analysis"| node_api_client
node_results_page -->|"polls status"| node_pipeline_progress
node_results_page -->|"renders outputs"| node_result_cards
node_api_client -->|"REST calls"| node_django_api
node_supabase_client -->|"syncs data"| node_supabase_db
node_django_api -->|"routes"| node_api_routes
node_api_routes -->|"dispatches"| node_api_views
node_api_views -->|"exposes"| node_pipeline_api
node_pipeline_api -->|"queues work"| node_celery_orchestrator
node_celery_orchestrator -->|"runs workflow"| node_pipeline_tasks
node_pipeline_tasks -->|"dispatches jobs"| node_queue_tasks
node_pipeline_tasks -->|"classifies subtype"| node_classifier
node_pipeline_tasks -->|"explains features"| node_xai_engine
node_xai_engine -->|"maps genes"| node_gene_mapper
node_gene_mapper -->|"feeds markers"| node_drug_engine
node_drug_engine -->|"validates candidates"| node_rag_pipeline
node_rag_pipeline -->|"consults"| node_evidence_sources
node_classifier -->|"remote inference"| node_hf_model
node_rag_pipeline -->|"persists reports"| node_models
node_pipeline_tasks -->|"persists run data"| node_models
node_django_api -->|"reads/writes"| node_models
node_results_page -->|"dashboard sync"| node_supabase_client

click node_home_page "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/pages/HomePage.tsx"
click node_results_page "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/pages/ResultsPage.tsx"
click node_api_client "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/lib/api.ts"
click node_supabase_client "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/lib/supabase.ts"
click node_upload_box "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/components/UploadBox.tsx"
click node_pipeline_progress "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/components/PipelineProgress.tsx"
click node_result_cards "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/components/SubtypeCard.tsx"
click node_django_api "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/tree/main/backend/lung_cancer_api"
click node_api_routes "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/lung_cancer_api/urls.py"
click node_api_views "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/lung_cancer_api/views.py"
click node_pipeline_api "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/views.py"
click node_celery_orchestrator "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/lung_cancer_api/celery.py"
click node_pipeline_tasks "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/tasks.py"
click node_queue_tasks "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/queue_tasks.py"
click node_classifier "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/ml_classifier.py"
click node_xai_engine "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/xai_engine.py"
click node_gene_mapper "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/gene_mapper.py"
click node_drug_engine "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/drug_engine.py"
click node_rag_pipeline "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/langgraph_pipeline.py"
click node_models "https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/models.py"

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_home_page,node_results_page,node_api_client,node_supabase_client,node_upload_box,node_pipeline_progress,node_result_cards toneBlue
class node_django_api,node_api_routes,node_api_views,node_pipeline_api,node_celery_orchestrator,node_pipeline_tasks,node_queue_tasks,node_classifier,node_xai_engine,node_gene_mapper,node_drug_engine,node_rag_pipeline,node_models toneAmber
class node_hf_model,node_evidence_sources,node_supabase_db toneMint
```

## Components

### Frontend

React + TypeScript client in project/

- [Home page](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/pages/HomePage.tsx): ui entry · Upload and analysis start screen · `project/src/pages/HomePage.tsx`
- [Results page](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/pages/ResultsPage.tsx): ui results · Polls status and renders completed analysis · `project/src/pages/ResultsPage.tsx`
- [API client](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/lib/api.ts): http bridge · Frontend HTTP layer for backend calls · `project/src/lib/api.ts`
- [Supabase client](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/lib/supabase.ts): integration layer · Secondary persistence and dashboard integration · `project/src/lib/supabase.ts`
- [Upload box](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/components/UploadBox.tsx): upload UI · Patient CSV upload control · `project/src/components/UploadBox.tsx`
- [Progress view](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/components/PipelineProgress.tsx): status UI · Shows analysis progress and polling state · `project/src/components/PipelineProgress.tsx`
- [Result views](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/project/src/components/SubtypeCard.tsx): presentation components · Subtype, genes, drugs, reports, and summary panels · `project/src/components/SubtypeCard.tsx`

### Backend

Django API, async workers, and analysis pipeline in backend/

- [Django API](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/tree/main/backend/lung_cancer_api): backend app · Main backend project and HTTP control plane · `backend/lung_cancer_api`
- [API routes](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/lung_cancer_api/urls.py): routing · Backend URL routing and entrypoints · `backend/lung_cancer_api/urls.py`
- [API views](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/lung_cancer_api/views.py): http handlers · Backend request handlers and response assembly · `backend/lung_cancer_api/views.py`
- [Pipeline API](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/views.py): analysis endpoints · Upload, status, results, summary, and cleanup endpoints · `backend/pipeline/views.py`
- [Celery](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/lung_cancer_api/celery.py): async orchestration · Background job coordination and scheduling · `backend/lung_cancer_api/celery.py`
- [Pipeline tasks](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/tasks.py): workflow orchestration · Coordinates the staged biomarker analysis workflow · `backend/pipeline/tasks.py`
- [Queue tasks](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/queue_tasks.py): job workers · Queued task implementations and dispatch helpers · `backend/pipeline/queue_tasks.py`
- [Classifier](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/ml_classifier.py): subtype model · Subtype prediction and confidence scoring · `backend/pipeline/ml_classifier.py`
- [XAI engine](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/xai_engine.py): explainability · Feature importance and explanation generation · `backend/pipeline/xai_engine.py`
- [Gene mapper](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/gene_mapper.py): gene interpretation · Maps model features to gene-level entities · `backend/pipeline/gene_mapper.py`
- [Drug engine](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/drug_engine.py): candidate ranking · Links genes to therapeutic candidates · `backend/pipeline/drug_engine.py`
- [RAG agents](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/langgraph_pipeline.py): evidence validation · Multi-agent literature-backed validation and synthesis · `backend/pipeline/langgraph_pipeline.py`
- [Data models](https://github.com/rishabh-108272/multi-agentic-rag-for-biomarker-validation/blob/main/backend/pipeline/models.py): persistence model · Persisted analyses, artifacts, candidates, and reports · `backend/pipeline/models.py`

### External services

Model, evidence, and persistence integrations

- **HF models**: external model service · Remote subtype inference service dependency
- **Evidence sources**: literature data · Biomedical literature and knowledge sources used by agents
- **Supabase**: external datastore · Frontend-side persistence/integration backend

## Connections

- Home page → Upload box: uploads CSV · User starts analysis by uploading patient data
- Home page → API client: start analysis · Frontend initiates backend analysis request
- Results page → Progress view: polls status · Results view tracks backend progress
- Results page → Result views: renders outputs · Displays subtype, genes, drugs, reports, and summary
- API client → Django API: REST calls · Frontend communicates with backend API
- Supabase client → Supabase: syncs data · Client persistence and dashboard integration
- Django API → API routes: routes · Django request routing
- API routes → API views: dispatches · Routes requests to HTTP handlers
- API views → Pipeline API: exposes · Pipeline-specific analysis endpoints
- Pipeline API → Celery: queues work · Long-running analysis is handed off asynchronously
- Celery → Pipeline tasks: runs workflow · Celery executes staged pipeline orchestration
- Pipeline tasks → Queue tasks: dispatches jobs · Pipeline splits work into queued stages
- Pipeline tasks → Classifier: classifies subtype · Predicts cancer subtype from input data
- Pipeline tasks → XAI engine: explains features · Generates explainability artifacts
- XAI engine → Gene mapper: maps genes · Converts model features to biological entities
- Gene mapper → Drug engine: feeds markers · Gene-level interpretation drives therapeutic lookup
- Drug engine → RAG agents: validates candidates · Candidate drugs are checked and enriched by agents
- RAG agents → Evidence sources: consults · Agents retrieve biomedical evidence and context
- Classifier → HF models: remote inference · Subtype model can call external Hugging Face services
- RAG agents → Data models: persists reports · Agent outputs and synthesized summaries are stored
- Pipeline tasks → Data models: persists run data · Analysis metadata and intermediate artifacts are saved
- Django API → Data models: reads/writes · API layer accesses persisted analysis state
- Results page → Supabase client: dashboard sync · Frontend may read/write analysis history
