# olascoaga/ankora architecture

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

- Interactive diagram: https://gitdiagram.com/olascoaga/ankora
- Repository: https://github.com/olascoaga/ankora

## Overview

Ankora is a local-first molecular-docking desktop workbench. Scientists import structures and ligand libraries, inspect and prepare receptors and ligands, define a binding site, run docking or screening, then review results, validate saved poses, and export evidence. The graph preserves the major documented workspaces and backend stages; dashed links mark runtime connections not shown in the supplied excerpts. The API boundary and project-scoped runtime are included as internal layers.

Main entry points: [`backend/src/ankora_backend/api/routes.py`](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/api/routes.py) (Local API), [`apps/desktop/src/app/App.tsx`](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/app/App.tsx) (Workbench shell), [`backend/src/ankora_backend/services/vina_docking.py`](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/vina_docking.py) (Vina docking), [`backend/src/ankora_backend/services/engine_comparison.py`](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/engine_comparison.py) (Rank comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workbench"]
  node_workbench["Workbench shell<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_viewer["Molecular viewer"]
end

subgraph group_preparation["Structure preparation"]
  node_structure["Structure inspection<br/>[App.tsx]"]
  node_receptor["Receptor preparation"]
  node_ligand["Ligand preparation"]
  node_binding_site["Binding-site definition"]
end

subgraph group_compute["Docking and screening"]
  node_docking_ui["Docking workspace"]
  node_engine_compare["Engine comparison"]
  node_vina["Vina docking<br/>[vina_docking.py]"]
  node_gnina_screening["GNINA screening"]
end

subgraph group_evidence["Results and evidence"]
  node_results["Results review"]
  node_validation["Redocking validation"]
  node_export["Export workspace"]
  node_comparison_service["Rank comparison"]
end

subgraph group_backend["Backend runtime"]
  node_backend_api["Local API<br/>[routes.py]"]
  node_api_app["API application<br/>[app.py]"]
  node_project_runtime["Project context<br/>[project_context.py]"]
  node_resource_arbiter["Resource arbiter"]
  node_docking_store[("Docking records<br/>[docking_store.py]")]
  node_ligand_store[("Ligand records<br/>[ligand_store.py]")]
  node_receptor_store[("Receptor records<br/>[receptor_store.py]")]
end

node_scientist(("Scientist"))

node_scientist -->|"uses"| node_workbench
node_workbench -->|"opens"| node_structure
node_workbench -->|"loads"| node_api_client
node_workbench -->|"renders"| node_viewer
node_scientist -->|"prepares"| node_receptor
node_scientist -->|"curates"| node_ligand
node_scientist -->|"defines"| node_binding_site
node_scientist -->|"runs"| node_docking_ui
node_scientist -->|"reviews"| node_results
node_scientist -->|"validates"| node_validation
node_scientist -->|"exports"| node_export
node_api_client -->|"requests"| node_backend_api
node_api_app -->|"mounts routes"| node_backend_api
node_api_app -->|"binds project"| node_project_runtime
node_backend_api -.->|"prepares"| node_receptor
node_backend_api -.->|"dispatches"| node_vina
node_backend_api -.->|"dispatches"| node_gnina_screening
node_vina -.->|"uses"| node_resource_arbiter
node_gnina_screening -->|"uses"| node_resource_arbiter
node_vina -.->|"persists"| node_docking_store
node_backend_api -.->|"reads and writes"| node_ligand_store
node_backend_api -.->|"reads and writes"| node_receptor_store
node_results -.->|"compares rankings"| node_comparison_service
node_comparison_service -->|"reads Vina"| node_docking_store
node_comparison_service -->|"reads AutoDock4"| node_docking_store

click node_workbench "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/app/App.tsx"
click node_api_client "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/api/client.ts"
click node_viewer "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/viewer/MolecularViewer.tsx"
click node_structure "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/app/App.tsx"
click node_receptor "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/receptor/ReceptorWorkspace.tsx"
click node_ligand "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/ligand/LigandWorkspace.tsx"
click node_binding_site "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/binding-site/BindingSiteWorkspace.tsx"
click node_docking_ui "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/docking/DockingWorkspace.tsx"
click node_engine_compare "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/docking/EngineComparisonWorkspace.tsx"
click node_backend_api "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/api/routes.py"
click node_api_app "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/api/app.py"
click node_project_runtime "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/domain/project_context.py"
click node_resource_arbiter "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/resource_arbiter.py"
click node_vina "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/vina_docking.py"
click node_gnina_screening "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/gnina_screening_service.py"
click node_results "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/results/ResultsWorkspace.tsx"
click node_validation "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/validation/RedockingWorkspace.tsx"
click node_export "https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/export/ExportWorkspace.tsx"
click node_comparison_service "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/engine_comparison.py"
click node_docking_store "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/persistence/docking_store.py"
click node_ligand_store "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/persistence/ligand_store.py"
click node_receptor_store "https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/persistence/receptor_store.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_workbench,node_api_client,node_viewer toneBlue
class node_structure,node_receptor,node_ligand,node_binding_site toneAmber
class node_docking_ui,node_engine_compare,node_vina,node_gnina_screening toneMint
class node_results,node_validation,node_export,node_comparison_service toneRose
class node_backend_api,node_api_app,node_project_runtime,node_resource_arbiter,node_docking_store,node_ligand_store,node_receptor_store,node_scientist toneIndigo
```

## Components

### Desktop workbench

- [Workbench shell](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/app/App.tsx): `apps/desktop/src/app/App.tsx`
- [API client](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/api/client.ts): `apps/desktop/src/api/client.ts`
- [Molecular viewer](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/viewer/MolecularViewer.tsx): `apps/desktop/src/viewer/MolecularViewer.tsx`

### Structure preparation

- [Structure inspection](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/app/App.tsx): `apps/desktop/src/app/App.tsx`
- [Receptor preparation](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/receptor/ReceptorWorkspace.tsx): `apps/desktop/src/features/receptor/ReceptorWorkspace.tsx`
- [Ligand preparation](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/ligand/LigandWorkspace.tsx): `apps/desktop/src/features/ligand/LigandWorkspace.tsx`
- [Binding-site definition](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/binding-site/BindingSiteWorkspace.tsx): `apps/desktop/src/features/binding-site/BindingSiteWorkspace.tsx`

### Docking and screening

- [Docking workspace](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/docking/DockingWorkspace.tsx): `apps/desktop/src/features/docking/DockingWorkspace.tsx`
- [Engine comparison](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/docking/EngineComparisonWorkspace.tsx): `apps/desktop/src/features/docking/EngineComparisonWorkspace.tsx`
- [Vina docking](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/vina_docking.py): `backend/src/ankora_backend/services/vina_docking.py`
- [GNINA screening](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/gnina_screening_service.py): `backend/src/ankora_backend/services/gnina_screening_service.py`

### Results and evidence

- [Results review](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/results/ResultsWorkspace.tsx): `apps/desktop/src/features/results/ResultsWorkspace.tsx`
- [Redocking validation](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/validation/RedockingWorkspace.tsx): `apps/desktop/src/features/validation/RedockingWorkspace.tsx`
- [Export workspace](https://github.com/olascoaga/ankora/blob/main/apps/desktop/src/features/export/ExportWorkspace.tsx): `apps/desktop/src/features/export/ExportWorkspace.tsx`
- [Rank comparison](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/engine_comparison.py): `backend/src/ankora_backend/services/engine_comparison.py`

### Backend runtime

- [Local API](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/api/routes.py): `backend/src/ankora_backend/api/routes.py`
- [API application](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/api/app.py): `backend/src/ankora_backend/api/app.py`
- [Project context](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/domain/project_context.py): `backend/src/ankora_backend/domain/project_context.py`
- [Resource arbiter](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/services/resource_arbiter.py): `backend/src/ankora_backend/services/resource_arbiter.py`
- [Docking records](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/persistence/docking_store.py): `backend/src/ankora_backend/persistence/docking_store.py`
- [Ligand records](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/persistence/ligand_store.py): `backend/src/ankora_backend/persistence/ligand_store.py`
- [Receptor records](https://github.com/olascoaga/ankora/blob/main/backend/src/ankora_backend/persistence/receptor_store.py): `backend/src/ankora_backend/persistence/receptor_store.py`

### Other components

- **Scientist**

## Connections

- Scientist → Workbench shell: uses (evidence: `README.md`)
- Workbench shell → Structure inspection: opens (evidence: `apps/desktop/src/app/App.tsx`)
- Workbench shell → API client: loads (evidence: `apps/desktop/src/app/App.tsx`)
- Workbench shell → Molecular viewer: renders (evidence: `apps/desktop/src/app/App.tsx`)
- Scientist → Receptor preparation: prepares (evidence: `README.md`)
- Scientist → Ligand preparation: curates (evidence: `README.md`)
- Scientist → Binding-site definition: defines (evidence: `README.md`)
- Scientist → Docking workspace: runs (evidence: `README.md`)
- Scientist → Results review: reviews (evidence: `README.md`)
- Scientist → Redocking validation: validates (evidence: `README.md`)
- Scientist → Export workspace: exports (evidence: `README.md`)
- API client → Local API: requests (evidence: `apps/desktop/src/api/client.ts`)
- API application → Local API: mounts routes (evidence: `backend/src/ankora_backend/api/app.py`)
- API application → Project context: binds project (evidence: `backend/src/ankora_backend/api/app.py`)
- Local API → Receptor preparation: prepares
- Local API → Vina docking: dispatches
- Local API → GNINA screening: dispatches
- Vina docking → Resource arbiter: uses
- GNINA screening → Resource arbiter: uses (evidence: `backend/src/ankora_backend/services/gnina_screening_service.py`)
- Vina docking → Docking records: persists
- Local API → Ligand records: reads and writes (evidence: `backend/src/ankora_backend/api/routes.py`)
- Local API → Receptor records: reads and writes (evidence: `backend/src/ankora_backend/api/routes.py`)
- Results review → Rank comparison: compares rankings
- Rank comparison → Docking records: reads Vina (evidence: `backend/src/ankora_backend/services/engine_comparison.py`)
- Rank comparison → Docking records: reads AutoDock4 (evidence: `backend/src/ankora_backend/services/engine_comparison.py`)
