# cmd-oxford/orthotargetdb architecture

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

- Interactive diagram: https://gitdiagram.com/cmd-oxford/orthotargetdb
- Repository: https://github.com/cmd-oxford/orthotargetdb

## Overview

OrthoTargetDB is an interactive protein ortholog/homolog discovery and comparison application. Users provide a seed and outgroup protein (IDs or sequences); the UI invokes the controller, which searches for homologs, gathers sequence and biological annotations, assembles results, and builds a tree for interactive filtering. A separate setup capability acquires and prepares local reference data and search databases. The index identifies controller dependencies, but some implementations and UI-to-core call details were not excerpted; edges below use documented workflows or index references, and omit uncertain links.

Main entry points: [`ortho_target_db/core/controller.py`](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/controller.py) (Analysis controller), [`ortho_target_db/setup/main.py`](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/main.py) (Setup coordinator), [`ortho_target_db/ui.py`](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/ui.py) (Shiny interface), [`ortho_target_db/core/homolog_search.py`](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/homolog_search.py) (Homolog search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interactive application"]
  node_ui["Shiny interface<br/>[ui.py]"]
  node_app["App launcher<br/>[app.py]"]
  node_upload["Result uploads<br/>[manual_upload.py]"]
end

subgraph group_analysis["Search and phylogeny"]
  node_controller["Analysis controller<br/>[controller.py]"]
  node_search["Homolog search<br/>[homolog_search.py]"]
  node_ebi["EBI search client<br/>[blast_ebi.py]"]
  node_mmseqs["Local MMseqs<br/>[mmseqs_local.py]"]
  node_aligner["Sequence aligner<br/>[aligner.py]"]
  node_tree["Tree builder<br/>[treebuilder.py]"]
end

subgraph group_annotation["Biological annotation"]
  node_uniprot["Protein metadata<br/>[uniprot.py]"]
  node_trembl["TrEMBL lookup<br/>[trembl.py]"]
  node_taxonomy["Taxonomy lookup<br/>[taxonomy.py]"]
  node_species["Species metadata<br/>[species.py]"]
  node_phenotypes["Phenotype metadata"]
  node_cites["CITES status<br/>[cites.py]"]
  node_grants["Grant metadata<br/>[grants.py]"]
end

subgraph group_provisioning["Data provisioning"]
  node_setup["Setup coordinator<br/>[main.py]"]
  node_resources["Resource downloads<br/>[get_resources.py]"]
  node_uniprot_db[("UniProt database")]
  node_taxonomy_db[("Taxonomy database")]
  node_search_dbs[("Search databases<br/>[build_mmseqs_db.py]")]
  node_alliance_db[("Phenotype database")]
end

node_user(("Protein researcher"))

node_user -->|"submits proteins"| node_ui
node_app -->|"starts interface"| node_ui
node_ui -->|"runs analysis"| node_controller
node_ui -->|"loads edited results"| node_upload
node_controller -->|"dispatches searches"| node_search
node_search -->|"queries remotely"| node_ebi
node_search -->|"runs local search"| node_mmseqs
node_controller -->|"fetches sequences"| node_uniprot
node_uniprot -->|"uses fallback"| node_trembl
node_controller -->|"looks up taxonomy"| node_taxonomy
node_controller -->|"adds species data"| node_species
node_controller -->|"adds phenotypes"| node_phenotypes
node_controller -->|"adds conservation"| node_cites
node_controller -->|"adds grant data"| node_grants
node_controller -->|"builds phylogeny"| node_tree
node_tree -->|"aligns sequences"| node_aligner
node_setup -->|"downloads inputs"| node_resources
node_setup -->|"builds database"| node_uniprot_db
node_setup -->|"builds database"| node_taxonomy_db
node_setup -->|"builds indexes"| node_search_dbs
node_setup -->|"builds database"| node_alliance_db

click node_ui "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/ui.py"
click node_app "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/app.py"
click node_controller "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/controller.py"
click node_search "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/homolog_search.py"
click node_ebi "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/blast_ebi.py"
click node_mmseqs "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/mmseqs_local.py"
click node_aligner "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/aligner.py"
click node_tree "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/treebuilder.py"
click node_upload "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/manual_upload.py"
click node_uniprot "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/uniprot.py"
click node_trembl "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/trembl.py"
click node_taxonomy "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/taxonomy.py"
click node_species "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/species.py"
click node_phenotypes "https://github.com/cmd-oxford/orthotargetdb/tree/main/ortho_target_db/core/phenotypes"
click node_cites "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/cites.py"
click node_grants "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/grants.py"
click node_setup "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/main.py"
click node_resources "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/get_resources.py"
click node_uniprot_db "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/build_uniprot_db.py"
click node_taxonomy_db "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/build_taxonomy_db.py"
click node_search_dbs "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/build_mmseqs_db.py"
click node_alliance_db "https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/build_alliance_phenotypes_db.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_ui,node_app,node_upload toneBlue
class node_controller,node_search,node_ebi,node_mmseqs,node_aligner,node_tree toneAmber
class node_uniprot,node_trembl,node_taxonomy,node_species,node_phenotypes,node_cites,node_grants toneMint
class node_setup,node_resources,node_uniprot_db,node_taxonomy_db,node_search_dbs,node_alliance_db toneRose
class node_user toneIndigo
```

## Components

### Interactive application

- [Shiny interface](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/ui.py): `ortho_target_db/ui.py`
- [App launcher](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/app.py): `ortho_target_db/app.py`
- [Result uploads](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/manual_upload.py): `ortho_target_db/core/manual_upload.py`

### Search and phylogeny

- [Analysis controller](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/controller.py): `ortho_target_db/core/controller.py`
- [Homolog search](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/homolog_search.py): `ortho_target_db/core/homolog_search.py`
- [EBI search client](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/blast_ebi.py): `ortho_target_db/core/blast_ebi.py`
- [Local MMseqs](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/mmseqs_local.py): `ortho_target_db/core/mmseqs_local.py`
- [Sequence aligner](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/aligner.py): `ortho_target_db/core/aligner.py`
- [Tree builder](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/treebuilder.py): `ortho_target_db/core/treebuilder.py`

### Biological annotation

- [Protein metadata](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/uniprot.py): `ortho_target_db/core/uniprot.py`
- [TrEMBL lookup](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/trembl.py): `ortho_target_db/core/trembl.py`
- [Taxonomy lookup](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/taxonomy.py): `ortho_target_db/core/taxonomy.py`
- [Species metadata](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/species.py): `ortho_target_db/core/species.py`
- [Phenotype metadata](https://github.com/cmd-oxford/orthotargetdb/tree/main/ortho_target_db/core/phenotypes): `ortho_target_db/core/phenotypes`
- [CITES status](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/cites.py): `ortho_target_db/core/cites.py`
- [Grant metadata](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/core/grants.py): `ortho_target_db/core/grants.py`

### Data provisioning

- [Setup coordinator](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/main.py): `ortho_target_db/setup/main.py`
- [Resource downloads](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/get_resources.py): `ortho_target_db/setup/get_resources.py`
- [UniProt database](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/build_uniprot_db.py): `ortho_target_db/setup/build_uniprot_db.py`
- [Taxonomy database](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/build_taxonomy_db.py): `ortho_target_db/setup/build_taxonomy_db.py`
- [Search databases](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/build_mmseqs_db.py): `ortho_target_db/setup/build_mmseqs_db.py`
- [Phenotype database](https://github.com/cmd-oxford/orthotargetdb/blob/main/ortho_target_db/setup/build_alliance_phenotypes_db.py): `ortho_target_db/setup/build_alliance_phenotypes_db.py`

### Other components

- **Protein researcher**

## Connections

- Protein researcher → Shiny interface: submits proteins (evidence: `README.md`)
- App launcher → Shiny interface: starts interface (evidence: `ortho_target_db/app.py`)
- Shiny interface → Analysis controller: runs analysis (evidence: `README.md`)
- Shiny interface → Result uploads: loads edited results (evidence: `ortho_target_db/ui.py`)
- Analysis controller → Homolog search: dispatches searches (evidence: `ortho_target_db/core/controller.py`)
- Homolog search → EBI search client: queries remotely (evidence: `ortho_target_db/core/homolog_search.py`)
- Homolog search → Local MMseqs: runs local search (evidence: `ortho_target_db/core/homolog_search.py`)
- Analysis controller → Protein metadata: fetches sequences (evidence: `ortho_target_db/core/controller.py`)
- Protein metadata → TrEMBL lookup: uses fallback (evidence: `ortho_target_db/core/uniprot.py`)
- Analysis controller → Taxonomy lookup: looks up taxonomy (evidence: `ortho_target_db/core/controller.py`)
- Analysis controller → Species metadata: adds species data (evidence: `ortho_target_db/core/controller.py`)
- Analysis controller → Phenotype metadata: adds phenotypes (evidence: `ortho_target_db/core/controller.py`)
- Analysis controller → CITES status: adds conservation (evidence: `ortho_target_db/core/controller.py`)
- Analysis controller → Grant metadata: adds grant data (evidence: `ortho_target_db/core/controller.py`)
- Analysis controller → Tree builder: builds phylogeny (evidence: `ortho_target_db/core/controller.py`)
- Tree builder → Sequence aligner: aligns sequences (evidence: `ortho_target_db/core/treebuilder.py`)
- Setup coordinator → Resource downloads: downloads inputs (evidence: `ortho_target_db/setup/main.py`)
- Setup coordinator → UniProt database: builds database (evidence: `ortho_target_db/setup/main.py`)
- Setup coordinator → Taxonomy database: builds database (evidence: `ortho_target_db/setup/main.py`)
- Setup coordinator → Search databases: builds indexes (evidence: `ortho_target_db/setup/main.py`)
- Setup coordinator → Phenotype database: builds database (evidence: `ortho_target_db/setup/main.py`)