# dsk-dev-ai/genomeai architecture

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

- Interactive diagram: https://gitdiagram.com/dsk-dev-ai/genomeai
- Repository: https://github.com/dsk-dev-ai/genomeai

## Overview

GenomeAI is an AI-augmented biomedical research platform: researchers use its web interface or API to request biological data and analyses, which can draw on public scientific sources and return results for exploration and visualization. Its runtime also includes a DAG workflow engine with queued execution, retries, and scheduling. The README documents the major capabilities; sampled source confirms API setup, workflow execution, and parts of the visualization data lifecycle. Several subsystem links are therefore documented at a high level rather than verified call-by-call.

Main entry points: [`apps/api/src/genomeai_api/main.py`](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/main.py) (REST API), [`apps/web/src/app/research/page.tsx`](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/app/research/page.tsx) (Web Research UI), [`apps/api/src/genomeai_api/services/gene_analysis.py`](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/services/gene_analysis.py) (AI Analysis), [`apps/api/src/genomeai_api/routes/genes.py`](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/routes/genes.py) (Domain Endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_web["Web Research UI<br/>[page.tsx]"]
  node_python_sdk["Python SDK<br/>[client.py]"]
  node_visualizations["Scientific Visualizations"]
  node_genome_viewer["Genome Browser<br/>[GenomeBrowser.tsx]"]
  node_protein_viewer["Protein Viewer<br/>[ProteinViewer.tsx]"]
  node_network_viewer["Network Graphs<br/>[NetworkViewer.tsx]"]
end

subgraph group_api["API and Analysis"]
  node_api_entry["REST API<br/>[main.py]"]
  node_analysis["AI Analysis<br/>[gene_analysis.py]"]
  node_domain_routes["Domain Endpoints<br/>[genes.py]"]
  node_workflow_routes["Workflow Endpoints<br/>[workflows.py]"]
end

subgraph group_research["Research Data"]
  node_connectors["Scientific Connectors"]
  node_external_sources["Public Data Sources"]
  node_domain_models["Biological Models<br/>[gene.py]"]
  node_repositories["Data Repositories<br/>[gene.py]"]
  node_ai_providers["Gemini and Ollama"]
end

subgraph group_orchestration["Workflow Orchestration"]
  node_workflow_engine["DAG Execution<br/>[engine.py]"]
  node_workflow_worker["Run Worker<br/>[worker.py]"]
  node_workflow_queue["Redis Queue<br/>[queueing.py]"]
  node_scheduler["Workflow Scheduler<br/>[scheduler.py]"]
end

subgraph group_platform["Runtime Platform"]
  node_database[("PostgreSQL<br/>[engine.py]")]
  node_redis[("Redis Cache<br/>[redis.py]")]
end

node_researcher(("Researcher"))
node_llm_services["LLM Providers"]

node_researcher -->|"requests research"| node_web
node_web -->|"calls API"| node_api_entry
node_python_sdk -.->|"calls API"| node_api_entry
node_api_entry -->|"registers routes"| node_domain_routes
node_api_entry -->|"registers routes"| node_workflow_routes
node_domain_routes -.->|"requests analysis"| node_analysis
node_analysis -.->|"retrieves evidence"| node_connectors
node_connectors -->|"queries databases"| node_external_sources
node_analysis -->|"uses models"| node_ai_providers
node_ai_providers -->|"sends prompts"| node_llm_services
node_domain_routes -.->|"persists data"| node_repositories
node_repositories -.->|"reads and writes"| node_database
node_repositories -.->|"uses models"| node_domain_models
node_api_entry -.->|"supports workflows"| node_workflow_engine
node_workflow_routes -.->|"enqueues runs"| node_workflow_queue
node_workflow_queue -.->|"claims jobs"| node_workflow_worker
node_workflow_worker -->|"executes runs"| node_workflow_engine
node_workflow_engine -.->|"records run state"| node_database
node_scheduler -.->|"schedules runs"| node_workflow_queue
node_api_entry -->|"initializes cache"| node_redis
node_analysis -.->|"returns analysis results"| node_visualizations
node_web -.->|"presents genome data"| node_genome_viewer
node_web -.->|"presents protein data"| node_protein_viewer
node_web -.->|"presents networks"| node_network_viewer

click node_web "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/app/research/page.tsx"
click node_python_sdk "https://github.com/dsk-dev-ai/genomeai/blob/main/packages/sdk-python/src/genomeai_sdk/client.py"
click node_api_entry "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/main.py"
click node_analysis "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/services/gene_analysis.py"
click node_domain_routes "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/routes/genes.py"
click node_workflow_routes "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/routes/workflows.py"
click node_connectors "https://github.com/dsk-dev-ai/genomeai/tree/main/apps/api/src/genomeai_api/integration/connectors"
click node_domain_models "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/models/gene.py"
click node_repositories "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/repositories/gene.py"
click node_ai_providers "https://github.com/dsk-dev-ai/genomeai/tree/main/apps/api/src/genomeai_api/ai"
click node_visualizations "https://github.com/dsk-dev-ai/genomeai/tree/main/apps/web/src/components/scientific"
click node_genome_viewer "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/components/genome/GenomeBrowser.tsx"
click node_protein_viewer "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/components/protein/ProteinViewer.tsx"
click node_network_viewer "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/components/network/NetworkViewer.tsx"
click node_workflow_engine "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/workflows/execution/engine.py"
click node_workflow_worker "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/services/worker.py"
click node_workflow_queue "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/workflows/queueing.py"
click node_scheduler "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/services/scheduler.py"
click node_database "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/database/engine.py"
click node_redis "https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/cache/redis.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_web,node_python_sdk,node_visualizations,node_genome_viewer,node_protein_viewer,node_network_viewer toneBlue
class node_api_entry,node_analysis,node_domain_routes,node_workflow_routes toneAmber
class node_connectors,node_external_sources,node_domain_models,node_repositories,node_ai_providers toneMint
class node_workflow_engine,node_workflow_worker,node_workflow_queue,node_scheduler toneRose
class node_database,node_redis,node_researcher,node_llm_services toneIndigo
```

## Components

### User Interfaces

- [Web Research UI](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/app/research/page.tsx): `apps/web/src/app/research/page.tsx`
- [Python SDK](https://github.com/dsk-dev-ai/genomeai/blob/main/packages/sdk-python/src/genomeai_sdk/client.py): `packages/sdk-python/src/genomeai_sdk/client.py`
- [Scientific Visualizations](https://github.com/dsk-dev-ai/genomeai/tree/main/apps/web/src/components/scientific): `apps/web/src/components/scientific`
- [Genome Browser](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/components/genome/GenomeBrowser.tsx): `apps/web/src/components/genome/GenomeBrowser.tsx`
- [Protein Viewer](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/components/protein/ProteinViewer.tsx): `apps/web/src/components/protein/ProteinViewer.tsx`
- [Network Graphs](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/web/src/components/network/NetworkViewer.tsx): `apps/web/src/components/network/NetworkViewer.tsx`

### API and Analysis

- [REST API](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/main.py): `apps/api/src/genomeai_api/main.py`
- [AI Analysis](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/services/gene_analysis.py): `apps/api/src/genomeai_api/services/gene_analysis.py`
- [Domain Endpoints](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/routes/genes.py): `apps/api/src/genomeai_api/routes/genes.py`
- [Workflow Endpoints](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/routes/workflows.py): `apps/api/src/genomeai_api/routes/workflows.py`

### Research Data

- [Scientific Connectors](https://github.com/dsk-dev-ai/genomeai/tree/main/apps/api/src/genomeai_api/integration/connectors): `apps/api/src/genomeai_api/integration/connectors`
- **Public Data Sources**
- [Biological Models](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/models/gene.py): `apps/api/src/genomeai_api/models/gene.py`
- [Data Repositories](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/repositories/gene.py): `apps/api/src/genomeai_api/repositories/gene.py`
- [Gemini and Ollama](https://github.com/dsk-dev-ai/genomeai/tree/main/apps/api/src/genomeai_api/ai): `apps/api/src/genomeai_api/ai`

### Workflow Orchestration

- [DAG Execution](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/workflows/execution/engine.py): `apps/api/src/genomeai_api/workflows/execution/engine.py`
- [Run Worker](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/services/worker.py): `apps/api/src/genomeai_api/services/worker.py`
- [Redis Queue](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/workflows/queueing.py): `apps/api/src/genomeai_api/workflows/queueing.py`
- [Workflow Scheduler](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/services/scheduler.py): `apps/api/src/genomeai_api/services/scheduler.py`

### Runtime Platform

- [PostgreSQL](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/database/engine.py): `apps/api/src/genomeai_api/database/engine.py`
- [Redis Cache](https://github.com/dsk-dev-ai/genomeai/blob/main/apps/api/src/genomeai_api/cache/redis.py): `apps/api/src/genomeai_api/cache/redis.py`

### Other components

- **Researcher**
- **LLM Providers**

## Connections

- Researcher → Web Research UI: requests research (evidence: `README.md`)
- Web Research UI → REST API: calls API (evidence: `README.md`)
- Python SDK → REST API: calls API
- REST API → Domain Endpoints: registers routes (evidence: `apps/api/src/genomeai_api/main.py`)
- REST API → Workflow Endpoints: registers routes (evidence: `apps/api/src/genomeai_api/main.py`)
- Domain Endpoints → AI Analysis: requests analysis
- AI Analysis → Scientific Connectors: retrieves evidence (evidence: `README.md`)
- Scientific Connectors → Public Data Sources: queries databases (evidence: `README.md`)
- AI Analysis → Gemini and Ollama: uses models (evidence: `README.md`)
- Gemini and Ollama → LLM Providers: sends prompts (evidence: `README.md`)
- Domain Endpoints → Data Repositories: persists data
- Data Repositories → PostgreSQL: reads and writes
- Data Repositories → Biological Models: uses models
- REST API → DAG Execution: supports workflows (evidence: `README.md`)
- Workflow Endpoints → Redis Queue: enqueues runs (evidence: `README.md`)
- Redis Queue → Run Worker: claims jobs (evidence: `README.md`)
- Run Worker → DAG Execution: executes runs (evidence: `apps/api/src/genomeai_api/services/worker.py`)
- DAG Execution → PostgreSQL: records run state
- Workflow Scheduler → Redis Queue: schedules runs (evidence: `README.md`)
- REST API → Redis Cache: initializes cache (evidence: `apps/api/src/genomeai_api/main.py`)
- AI Analysis → Scientific Visualizations: returns analysis results (evidence: `README.md`)
- Web Research UI → Genome Browser: presents genome data (evidence: `README.md`)
- Web Research UI → Protein Viewer: presents protein data (evidence: `README.md`)
- Web Research UI → Network Graphs: presents networks (evidence: `README.md`)
