# waldronlab/bioanalyzer-backend architecture

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

- Interactive diagram: https://gitdiagram.com/waldronlab/bioanalyzer-backend
- Repository: https://github.com/waldronlab/bioanalyzer-backend

## Overview

BioAnalyzer turns a PMID into curator-facing BugSigDB predictions: retrieve PubMed/PMC metadata and text, extract five fields plus curation signals, normalize ontology-backed fields, and return status, confidence, and mapping metadata. The API exposes simple v1 and RAG-enhanced v2 analysis; the repository also includes study-analysis and curator-table capabilities. The graph follows documented flow and shown references; links for unsampled subsystems are omitted where their runtime wiring is not evidenced.

Main entry points: [`app/services/bugsigdb_analyzer/rag_analysis.py`](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/bugsigdb_analyzer/rag_analysis.py) (RAG analysis), [`app/api/routers/bugsigdb_analysis_v2.py`](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/routers/bugsigdb_analysis_v2.py) (Analysis routes), [`app/services/data_retrieval.py`](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/data_retrieval.py) (PubMed retrieval), [`app/api/app.py`](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/app.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and presentation"]
  node_api["FastAPI application<br/>[app.py]"]
  node_analysis_routes["Analysis routes"]
  node_study_routes["Study analysis<br/>[study_analysis.py]"]
  node_curator_table["Curator table<br/>[app.py]"]
  node_api_models["API result models<br/>[api_models.py]"]
end

subgraph group_retrieval["Paper retrieval"]
  node_retrieval_service["PubMed retrieval<br/>[data_retrieval.py]"]
  node_cache[("SQLite cache<br/>[cache_manager.py]")]
end

subgraph group_analysis["Extraction and grounding"]
  node_field_analysis["BugSigDB extraction"]
  node_simple_analysis["Simple analysis<br/>[simple_analysis.py]"]
  node_rag_analysis["RAG analysis<br/>[rag_analysis.py]"]
  node_advanced_rag["RAG context<br/>[advanced_rag.py]"]
  node_chunking["Text chunking<br/>[chunking.py]"]
  node_normalizers["Field normalization"]
  node_condition["Condition mapping<br/>[condition.py]"]
  node_agent["Study agent"]
end

subgraph group_platform["Models and state"]
  node_qa["Unified QA<br/>[unified_qa.py]"]
  node_llm_provider["LLM provider<br/>[llm_provider.py]"]
end

node_researcher(("API or CLI user"))
node_pubmed(("PubMed and PMC"))
node_llm_service(("LLM APIs"))

node_researcher -->|"submits PMID"| node_api
node_api -->|"registers routes"| node_analysis_routes
node_api -->|"registers routes"| node_study_routes
node_analysis_routes -->|"runs v1 analysis"| node_simple_analysis
node_analysis_routes -->|"runs v2 analysis"| node_rag_analysis
node_retrieval_service -->|"requests paper data"| node_pubmed
node_simple_analysis -->|"retrieves paper"| node_retrieval_service
node_rag_analysis -->|"retrieves paper"| node_retrieval_service
node_retrieval_service -.->|"caches retrieval"| node_cache
node_simple_analysis -->|"extracts fields"| node_field_analysis
node_rag_analysis -->|"extracts fields"| node_field_analysis
node_rag_analysis -->|"chunks text"| node_chunking
node_rag_analysis -->|"builds context"| node_advanced_rag
node_field_analysis -->|"normalizes fields"| node_normalizers
node_condition -.->|"provides condition mapping"| node_normalizers
node_qa -->|"delegates chat"| node_llm_provider
node_llm_provider -->|"sends completions"| node_llm_service
node_rag_analysis -.->|"queries model"| node_qa
node_study_routes -.->|"orchestrates study"| node_agent
node_analysis_routes -->|"returns typed results"| node_api_models

click node_api "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/app.py"
click node_analysis_routes "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/routers/bugsigdb_analysis_v2.py"
click node_study_routes "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/routers/study_analysis.py"
click node_curator_table "https://github.com/waldronlab/bioanalyzer-backend/blob/main/curator_table/app.py"
click node_api_models "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/models/api_models.py"
click node_retrieval_service "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/data_retrieval.py"
click node_cache "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/cache_manager.py"
click node_field_analysis "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/bugsigdb_analyzer/field_extraction.py"
click node_simple_analysis "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/bugsigdb_analyzer/simple_analysis.py"
click node_rag_analysis "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/bugsigdb_analyzer/rag_analysis.py"
click node_advanced_rag "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/advanced_rag.py"
click node_chunking "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/utils/chunking.py"
click node_normalizers "https://github.com/waldronlab/bioanalyzer-backend/tree/main/app/normalization"
click node_condition "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/normalization/condition.py"
click node_qa "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/models/unified_qa.py"
click node_llm_provider "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/models/llm_provider.py"
click node_agent "https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/agent_orchestrator.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_api,node_analysis_routes,node_study_routes,node_curator_table,node_api_models,node_researcher toneBlue
class node_retrieval_service,node_cache toneAmber
class node_field_analysis,node_simple_analysis,node_rag_analysis,node_advanced_rag,node_chunking,node_normalizers,node_condition,node_agent,node_llm_service toneMint
class node_qa,node_llm_provider toneRose
class node_pubmed toneIndigo
```

## Components

### API and presentation

- [FastAPI application](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/app.py): `app/api/app.py`
- [Analysis routes](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/routers/bugsigdb_analysis_v2.py): `app/api/routers/bugsigdb_analysis_v2.py`
- [Study analysis](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/routers/study_analysis.py): `app/api/routers/study_analysis.py`
- [Curator table](https://github.com/waldronlab/bioanalyzer-backend/blob/main/curator_table/app.py): `curator_table/app.py`
- [API result models](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/api/models/api_models.py): `app/api/models/api_models.py`

### Paper retrieval

- [PubMed retrieval](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/data_retrieval.py): `app/services/data_retrieval.py`
- [SQLite cache](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/cache_manager.py): `app/services/cache_manager.py`

### Extraction and grounding

- [BugSigDB extraction](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/bugsigdb_analyzer/field_extraction.py): `app/services/bugsigdb_analyzer/field_extraction.py`
- [Simple analysis](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/bugsigdb_analyzer/simple_analysis.py): `app/services/bugsigdb_analyzer/simple_analysis.py`
- [RAG analysis](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/bugsigdb_analyzer/rag_analysis.py): `app/services/bugsigdb_analyzer/rag_analysis.py`
- [RAG context](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/advanced_rag.py): `app/services/advanced_rag.py`
- [Text chunking](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/utils/chunking.py): `app/utils/chunking.py`
- [Field normalization](https://github.com/waldronlab/bioanalyzer-backend/tree/main/app/normalization): `app/normalization`
- [Condition mapping](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/normalization/condition.py): `app/normalization/condition.py`
- [Study agent](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/services/agent_orchestrator.py): `app/services/agent_orchestrator.py`

### Models and state

- [Unified QA](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/models/unified_qa.py): `app/models/unified_qa.py`
- [LLM provider](https://github.com/waldronlab/bioanalyzer-backend/blob/main/app/models/llm_provider.py): `app/models/llm_provider.py`

### Other components

- **API or CLI user**
- **PubMed and PMC**
- **LLM APIs**

## Connections

- API or CLI user → FastAPI application: submits PMID (evidence: `README.md`)
- FastAPI application → Analysis routes: registers routes (evidence: `app/api/app.py`)
- FastAPI application → Study analysis: registers routes (evidence: `app/api/app.py`)
- Analysis routes → Simple analysis: runs v1 analysis (evidence: `app/api/routers/bugsigdb_analysis_v2.py`)
- Analysis routes → RAG analysis: runs v2 analysis (evidence: `README.md`)
- PubMed retrieval → PubMed and PMC: requests paper data (evidence: `app/services/data_retrieval.py`)
- Simple analysis → PubMed retrieval: retrieves paper (evidence: `README.md`)
- RAG analysis → PubMed retrieval: retrieves paper (evidence: `app/services/bugsigdb_analyzer/rag_analysis.py`)
- PubMed retrieval → SQLite cache: caches retrieval
- Simple analysis → BugSigDB extraction: extracts fields (evidence: `app/services/bugsigdb_analyzer/__init__.py`)
- RAG analysis → BugSigDB extraction: extracts fields (evidence: `app/services/bugsigdb_analyzer/rag_analysis.py`)
- RAG analysis → Text chunking: chunks text (evidence: `app/services/bugsigdb_analyzer/rag_analysis.py`)
- RAG analysis → RAG context: builds context (evidence: `app/services/bugsigdb_analyzer/rag_analysis.py`)
- BugSigDB extraction → Field normalization: normalizes fields (evidence: `app/services/bugsigdb_analyzer/field_extraction.py`)
- Condition mapping → Field normalization: provides condition mapping (evidence: `app/normalization/condition.py`)
- Unified QA → LLM provider: delegates chat (evidence: `app/models/unified_qa.py`)
- LLM provider → LLM APIs: sends completions (evidence: `app/models/llm_provider.py`)
- RAG analysis → Unified QA: queries model
- Study analysis → Study agent: orchestrates study (evidence: `app/api/routers/study_analysis.py`)
- Analysis routes → API result models: returns typed results (evidence: `app/api/routers/bugsigdb_analysis_v2.py`)