# ganesh-dark/bioweaver architecture

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

- Interactive diagram: https://gitdiagram.com/ganesh-dark/bioweaver
- Repository: https://github.com/ganesh-dark/bioweaver

## Overview

Bioweaver accepts biomedical questions through a chat interface or API, then a ReAct agent selects database tools or answers conceptual questions with an LLM. Tool results are retrieved from external biological services or local datasets, optionally analyzed and combined, and returned as a bounded, paginated answer. The README documents the major domain capabilities; source excerpts and the SOURCE INDEX confirm key imports and calls, but not every tool’s internal wiring.

Main entry points: [`core/agent_graph.py`](https://github.com/ganesh-dark/bioweaver/blob/master/core/agent_graph.py) (ReAct Agent), [`clients/reactome_client.py`](https://github.com/ganesh-dark/bioweaver/blob/master/clients/reactome_client.py) (Reactome Queries), [`app.py`](https://github.com/ganesh-dark/bioweaver/blob/master/app.py) (Chat API), [`clients/kegg_client.py`](https://github.com/ganesh-dark/bioweaver/blob/master/clients/kegg_client.py) (KEGG Queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_frontend["Chat Frontend<br/>[index.html]"]
  node_api["Chat API<br/>[app.py]"]
end

subgraph group_agent["Agent and Models"]
  node_react_agent{{"ReAct Agent<br/>[agent_graph.py]"}}
  node_llm["Model Provider"]
  node_hf_router["ClinVar Query Router"]
end

subgraph group_pathway["Pathway and Metabolism"]
  node_kegg_client["KEGG Queries<br/>[kegg_client.py]"]
  node_reactome_client["Reactome Queries<br/>[reactome_client.py]"]
  node_kegg_analytics["KEGG Analytics<br/>[kegg_analytics.py]"]
  node_reactome_analytics["Reactome Analytics"]
  node_reaction_data["Reaction Utilities"]
end

subgraph group_biomedical["Gene and Clinical Data"]
  node_clinvar_client["ClinVar Search<br/>[clinvar_client.py]"]
  node_ncbi_client["NCBI Gene Lookup<br/>[ncbi_client.py]"]
  node_hgnc_client["HGNC Name Cache<br/>[hgnc_client.py]"]
  node_wiki_client["Disease Overviews<br/>[wiki_client.py]"]
end

subgraph group_data["Data Sources"]
  node_kegg_store[("KEGG TSV Data")]
  node_reactome_store[("Reactome Data")]
  node_hgnc_store["HGNC Dataset"]
  node_clinvar_store[("ClinVar Database")]
end

node_user(("Researcher"))
node_kegg_service["KEGG Service"]
node_reactome_service["Reactome Service"]
node_ncbi_service["NCBI E-utilities"]
node_wikipedia["Wikipedia"]
node_model_service["LLM Provider"]

node_user -.->|"asks question"| node_frontend
node_frontend -.->|"submits question"| node_api
node_api -->|"streams answer"| node_frontend
node_api -->|"streams query"| node_react_agent
node_react_agent -->|"reasons with"| node_llm
node_llm -.->|"requests completion"| node_model_service
node_react_agent -->|"routes variants"| node_hf_router
node_hf_router -->|"extracts query fields"| node_llm
node_react_agent -->|"queries KEGG"| node_kegg_client
node_react_agent -->|"queries Reactome"| node_reactome_client
node_react_agent -->|"runs analysis"| node_kegg_analytics
node_react_agent -->|"runs analysis"| node_reactome_analytics
node_react_agent -.->|"retrieves reactions"| node_reaction_data
node_react_agent -->|"searches variants"| node_clinvar_client
node_react_agent -->|"looks up genes"| node_ncbi_client
node_react_agent -->|"gets overviews"| node_wiki_client
node_kegg_client -->|"requests records"| node_kegg_service
node_reactome_client -->|"fetches participants"| node_reactome_service
node_ncbi_client -->|"searches genes"| node_ncbi_service
node_kegg_analytics -->|"reads TSVs"| node_kegg_store
node_reactome_client -.->|"loads pathway model"| node_reactome_store
node_clinvar_client -->|"queries variants"| node_clinvar_store
node_kegg_client -->|"uses gene names"| node_hgnc_client
node_reactome_client -->|"expands symbols"| node_hgnc_client
node_hgnc_client -->|"loads gene names"| node_hgnc_store
node_react_agent -.->|"falls back for overview"| node_wikipedia

click node_frontend "https://github.com/ganesh-dark/bioweaver/blob/master/static/index.html"
click node_api "https://github.com/ganesh-dark/bioweaver/blob/master/app.py"
click node_react_agent "https://github.com/ganesh-dark/bioweaver/blob/master/core/agent_graph.py"
click node_llm "https://github.com/ganesh-dark/bioweaver/blob/master/core/ai_model_wrapper.py"
click node_hf_router "https://github.com/ganesh-dark/bioweaver/blob/master/clients/hf_router_client.py"
click node_kegg_client "https://github.com/ganesh-dark/bioweaver/blob/master/clients/kegg_client.py"
click node_reactome_client "https://github.com/ganesh-dark/bioweaver/blob/master/clients/reactome_client.py"
click node_kegg_analytics "https://github.com/ganesh-dark/bioweaver/blob/master/analytics/kegg_analytics.py"
click node_reactome_analytics "https://github.com/ganesh-dark/bioweaver/blob/master/analytics/reactome_analytics.py"
click node_reaction_data "https://github.com/ganesh-dark/bioweaver/blob/master/clients/reactome_reactions.py"
click node_clinvar_client "https://github.com/ganesh-dark/bioweaver/blob/master/clients/clinvar_client.py"
click node_ncbi_client "https://github.com/ganesh-dark/bioweaver/blob/master/clients/ncbi_client.py"
click node_hgnc_client "https://github.com/ganesh-dark/bioweaver/blob/master/clients/hgnc_client.py"
click node_wiki_client "https://github.com/ganesh-dark/bioweaver/blob/master/clients/wiki_client.py"
click node_kegg_store "https://github.com/ganesh-dark/bioweaver/tree/master/Kegg_files"
click node_reactome_store "https://github.com/ganesh-dark/bioweaver/tree/master/Reactome_files"
click node_hgnc_store "https://github.com/ganesh-dark/bioweaver/blob/master/hgnc_files/hgnc_complete_set.txt"

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_frontend,node_api toneBlue
class node_react_agent,node_llm,node_hf_router toneAmber
class node_kegg_client,node_reactome_client,node_kegg_analytics,node_reactome_analytics,node_reaction_data toneMint
class node_clinvar_client,node_ncbi_client,node_hgnc_client,node_wiki_client toneRose
class node_kegg_store,node_reactome_store,node_hgnc_store,node_clinvar_store,node_user,node_kegg_service,node_reactome_service,node_ncbi_service,node_wikipedia,node_model_service toneIndigo
```

## Components

### User Interface

- [Chat Frontend](https://github.com/ganesh-dark/bioweaver/blob/master/static/index.html): `static/index.html`
- [Chat API](https://github.com/ganesh-dark/bioweaver/blob/master/app.py): `app.py`

### Agent and Models

- [ReAct Agent](https://github.com/ganesh-dark/bioweaver/blob/master/core/agent_graph.py): `core/agent_graph.py`
- [Model Provider](https://github.com/ganesh-dark/bioweaver/blob/master/core/ai_model_wrapper.py): `core/ai_model_wrapper.py`
- [ClinVar Query Router](https://github.com/ganesh-dark/bioweaver/blob/master/clients/hf_router_client.py): `clients/hf_router_client.py`

### Pathway and Metabolism

- [KEGG Queries](https://github.com/ganesh-dark/bioweaver/blob/master/clients/kegg_client.py): `clients/kegg_client.py`
- [Reactome Queries](https://github.com/ganesh-dark/bioweaver/blob/master/clients/reactome_client.py): `clients/reactome_client.py`
- [KEGG Analytics](https://github.com/ganesh-dark/bioweaver/blob/master/analytics/kegg_analytics.py): `analytics/kegg_analytics.py`
- [Reactome Analytics](https://github.com/ganesh-dark/bioweaver/blob/master/analytics/reactome_analytics.py): `analytics/reactome_analytics.py`
- [Reaction Utilities](https://github.com/ganesh-dark/bioweaver/blob/master/clients/reactome_reactions.py): `clients/reactome_reactions.py`

### Gene and Clinical Data

- [ClinVar Search](https://github.com/ganesh-dark/bioweaver/blob/master/clients/clinvar_client.py): `clients/clinvar_client.py`
- [NCBI Gene Lookup](https://github.com/ganesh-dark/bioweaver/blob/master/clients/ncbi_client.py): `clients/ncbi_client.py`
- [HGNC Name Cache](https://github.com/ganesh-dark/bioweaver/blob/master/clients/hgnc_client.py): `clients/hgnc_client.py`
- [Disease Overviews](https://github.com/ganesh-dark/bioweaver/blob/master/clients/wiki_client.py): `clients/wiki_client.py`

### Data Sources

- [KEGG TSV Data](https://github.com/ganesh-dark/bioweaver/tree/master/Kegg_files): `Kegg_files`
- [Reactome Data](https://github.com/ganesh-dark/bioweaver/tree/master/Reactome_files): `Reactome_files`
- [HGNC Dataset](https://github.com/ganesh-dark/bioweaver/blob/master/hgnc_files/hgnc_complete_set.txt): `hgnc_files/hgnc_complete_set.txt`
- **ClinVar Database**

### Other components

- **Researcher**
- **KEGG Service**
- **Reactome Service**
- **NCBI E-utilities**
- **Wikipedia**
- **LLM Provider**

## Connections

- Researcher → Chat Frontend: asks question
- Chat Frontend → Chat API: submits question
- Chat API → Chat Frontend: streams answer (evidence: `app.py`)
- Chat API → ReAct Agent: streams query (evidence: `app.py`)
- ReAct Agent → Model Provider: reasons with (evidence: `core/agent_graph.py`)
- Model Provider → LLM Provider: requests completion
- ReAct Agent → ClinVar Query Router: routes variants (evidence: `core/agent_graph.py`)
- ClinVar Query Router → Model Provider: extracts query fields (evidence: `clients/hf_router_client.py`)
- ReAct Agent → KEGG Queries: queries KEGG (evidence: `core/agent_graph.py`)
- ReAct Agent → Reactome Queries: queries Reactome (evidence: `core/agent_graph.py`)
- ReAct Agent → KEGG Analytics: runs analysis (evidence: `core/agent_graph.py`)
- ReAct Agent → Reactome Analytics: runs analysis (evidence: `core/agent_graph.py`)
- ReAct Agent → Reaction Utilities: retrieves reactions
- ReAct Agent → ClinVar Search: searches variants (evidence: `core/agent_graph.py`)
- ReAct Agent → NCBI Gene Lookup: looks up genes (evidence: `core/agent_graph.py`)
- ReAct Agent → Disease Overviews: gets overviews (evidence: `core/agent_graph.py`)
- KEGG Queries → KEGG Service: requests records (evidence: `clients/kegg_client.py`)
- Reactome Queries → Reactome Service: fetches participants (evidence: `clients/reactome_client.py`)
- NCBI Gene Lookup → NCBI E-utilities: searches genes (evidence: `clients/ncbi_client.py`)
- KEGG Analytics → KEGG TSV Data: reads TSVs (evidence: `analytics/kegg_analytics.py`)
- Reactome Queries → Reactome Data: loads pathway model
- ClinVar Search → ClinVar Database: queries variants (evidence: `clients/clinvar_client.py`)
- KEGG Queries → HGNC Name Cache: uses gene names (evidence: `clients/kegg_client.py`)
- Reactome Queries → HGNC Name Cache: expands symbols (evidence: `clients/reactome_client.py`)
- HGNC Name Cache → HGNC Dataset: loads gene names (evidence: `clients/hgnc_client.py`)
- ReAct Agent → Wikipedia: falls back for overview (evidence: `README.md`)
