# jonathan-bravo/telsvirus architecture

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

- Interactive diagram: https://gitdiagram.com/jonathan-bravo/telsvirus
- Repository: https://github.com/jonathan-bravo/telsvirus

## Overview

TELSVirus is a Snakemake workflow for detecting viral strains and reconstructing their haplotypes from sequencing reads. The main user-to-result path is read preparation and host/viral alignment, followed by viral-target selection, per-target haplotype reconstruction, and summary output. The repository also includes reference acquisition, duplicate handling, strain annotation, and mapping summaries. The README and selected scripts establish these capabilities, but the Snakefile and rules were not sampled, so workflow wiring is shown only at the documented, high-level orchestration boundary.

Main entry points: [`workflow/Snakefile`](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/Snakefile) (Snakemake workflow), [`workflow/rules/get_host_ref.smk`](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/rules/get_host_ref.smk) (Host references), [`workflow/scripts/get_ref.py`](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/get_ref.py) (Host reference fetch), [`workflow/scripts/find_viral_targets.py`](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/find_viral_targets.py) (Viral target selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Workflow control"]
  node_workflow["Snakemake workflow"]
end

subgraph group_reads["Read processing"]
  node_trim["Barcode trimming<br/>[trim.py]"]
  node_align_targets["Target alignment"]
  node_host_refs["Host references<br/>[get_host_ref.smk]"]
  node_host_ref_fetch["Host reference fetch<br/>[get_ref.py]"]
end

subgraph group_viral["Viral analysis"]
  node_target_select["Viral target selection"]
  node_duplicate_scan["Duplicate detection<br/>[find_duplicates.py]"]
  node_cluster["Read clustering<br/>[cluster_reads.py]"]
  node_blat["BLAT alignment<br/>[run_blat.py]"]
  node_deduplicate["Read deduplication<br/>[deduplicate.py]"]
  node_preflight["RVHaplo preflight"]
  node_rvhaplo["Haplotype reconstruction"]
end

subgraph group_results["References and results"]
  node_parse_haplotypes["Haplotype parsing<br/>[parse_rvhaplo.py]"]
  node_strain_db[("Strain database")]
  node_strain_db_workflow["Strain database rules<br/>[strain_db.smk]"]
  node_strain_db_generator["Strain database generator"]
  node_viral_annotation["Viral segment annotation"]
  node_mapping_summary["Mapping summaries"]
end

node_user(("Analyst"))
node_refseq(("NCBI RefSeq"))
node_entrez(("NCBI Entrez"))
node_blat_tool(("BLAT"))
node_reads_input(("Sequencing reads"))

node_user -->|"runs"| node_workflow
node_reads_input -->|"provides reads"| node_workflow
node_workflow -->|"dispatches"| node_trim
node_workflow -->|"dispatches"| node_host_refs
node_workflow -->|"dispatches"| node_target_select
node_workflow -->|"dispatches"| node_duplicate_scan
node_workflow -->|"dispatches"| node_cluster
node_workflow -->|"dispatches"| node_deduplicate
node_workflow -->|"dispatches"| node_preflight
node_workflow -->|"dispatches"| node_rvhaplo
node_workflow -->|"dispatches"| node_parse_haplotypes
node_workflow -->|"dispatches"| node_strain_db_workflow
node_workflow -->|"dispatches"| node_viral_annotation
node_workflow -->|"dispatches"| node_mapping_summary
node_host_refs -->|"invokes"| node_host_ref_fetch
node_host_ref_fetch -->|"downloads genome"| node_refseq
node_blat -->|"invokes"| node_blat_tool
node_viral_annotation -->|"fetches metadata"| node_entrez
node_strain_db_workflow -->|"invokes"| node_strain_db_generator
node_target_select -->|"reads names"| node_strain_db
node_parse_haplotypes -->|"reads names"| node_strain_db
node_mapping_summary -->|"reads names"| node_strain_db

click node_workflow "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/Snakefile"
click node_trim "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/trim.py"
click node_align_targets "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/align_to_targets.sh"
click node_host_refs "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/rules/get_host_ref.smk"
click node_host_ref_fetch "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/get_ref.py"
click node_target_select "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/find_viral_targets.py"
click node_duplicate_scan "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/find_duplicates.py"
click node_cluster "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/cluster_reads.py"
click node_blat "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/run_blat.py"
click node_deduplicate "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/deduplicate.py"
click node_preflight "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/rvhaplo_preflight.py"
click node_rvhaplo "https://github.com/jonathan-bravo/telsvirus/tree/main/RVHaplo"
click node_parse_haplotypes "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/parse_rvhaplo.py"
click node_strain_db_workflow "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/rules/strain_db.smk"
click node_strain_db_generator "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/gen_strain_source_db.py"
click node_viral_annotation "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/add_viral_segments.py"
click node_mapping_summary "https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/summarize_idxstats.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_workflow toneBlue
class node_trim,node_align_targets,node_host_refs,node_host_ref_fetch toneAmber
class node_target_select,node_duplicate_scan,node_cluster,node_blat,node_deduplicate,node_preflight,node_rvhaplo toneMint
class node_parse_haplotypes,node_strain_db,node_strain_db_workflow,node_strain_db_generator,node_viral_annotation,node_mapping_summary toneRose
class node_user,node_refseq,node_entrez,node_blat_tool,node_reads_input toneIndigo
```

## Components

### Workflow control

- [Snakemake workflow](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/Snakefile): `workflow/Snakefile`

### Read processing

- [Barcode trimming](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/trim.py): `workflow/scripts/trim.py`
- [Target alignment](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/align_to_targets.sh): `workflow/scripts/align_to_targets.sh`
- [Host references](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/rules/get_host_ref.smk): `workflow/rules/get_host_ref.smk`
- [Host reference fetch](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/get_ref.py): `workflow/scripts/get_ref.py`

### Viral analysis

- [Viral target selection](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/find_viral_targets.py): `workflow/scripts/find_viral_targets.py`
- [Duplicate detection](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/find_duplicates.py): `workflow/scripts/find_duplicates.py`
- [Read clustering](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/cluster_reads.py): `workflow/scripts/cluster_reads.py`
- [BLAT alignment](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/run_blat.py): `workflow/scripts/run_blat.py`
- [Read deduplication](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/deduplicate.py): `workflow/scripts/deduplicate.py`
- [RVHaplo preflight](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/rvhaplo_preflight.py): `workflow/scripts/rvhaplo_preflight.py`
- [Haplotype reconstruction](https://github.com/jonathan-bravo/telsvirus/tree/main/RVHaplo): `RVHaplo`

### References and results

- [Haplotype parsing](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/parse_rvhaplo.py): `workflow/scripts/parse_rvhaplo.py`
- **Strain database**
- [Strain database rules](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/rules/strain_db.smk): `workflow/rules/strain_db.smk`
- [Strain database generator](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/gen_strain_source_db.py): `workflow/scripts/gen_strain_source_db.py`
- [Viral segment annotation](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/add_viral_segments.py): `workflow/scripts/add_viral_segments.py`
- [Mapping summaries](https://github.com/jonathan-bravo/telsvirus/blob/main/workflow/scripts/summarize_idxstats.py): `workflow/scripts/summarize_idxstats.py`

### Other components

- **Analyst**
- **NCBI RefSeq**
- **NCBI Entrez**
- **BLAT**
- **Sequencing reads**

## Connections

- Analyst → Snakemake workflow: runs
- Sequencing reads → Snakemake workflow: provides reads
- Snakemake workflow → Barcode trimming: dispatches
- Snakemake workflow → Host references: dispatches
- Snakemake workflow → Viral target selection: dispatches
- Snakemake workflow → Duplicate detection: dispatches
- Snakemake workflow → Read clustering: dispatches
- Snakemake workflow → Read deduplication: dispatches
- Snakemake workflow → RVHaplo preflight: dispatches
- Snakemake workflow → Haplotype reconstruction: dispatches
- Snakemake workflow → Haplotype parsing: dispatches
- Snakemake workflow → Strain database rules: dispatches
- Snakemake workflow → Viral segment annotation: dispatches
- Snakemake workflow → Mapping summaries: dispatches
- Host references → Host reference fetch: invokes
- Host reference fetch → NCBI RefSeq: downloads genome
- BLAT alignment → BLAT: invokes
- Viral segment annotation → NCBI Entrez: fetches metadata
- Strain database rules → Strain database generator: invokes
- Viral target selection → Strain database: reads names
- Haplotype parsing → Strain database: reads names
- Mapping summaries → Strain database: reads names