# octavianix/sangercap architecture

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

- Interactive diagram: https://gitdiagram.com/octavianix/sangercap
- Repository: https://github.com/octavianix/sangercap

## Overview

SangerCap is a Sanger-trace sequencing workflow for microbiology labs. Users start a run from the CLI or desktop, which reaches the shared run service and pipeline: traces are read and trimmed, reads may be grouped, contigs assembled, and sequences identified using BLAST candidates plus end-to-end alignment and taxonomic classification. Results include review flags and HTML reports. The README also documents editing, vector screening, database management, scheduled runs and remote-server use. Pipeline-stage links are supported by the README and pipeline excerpt; unsampled interface wiring is left unasserted or marked unverified.

Main entry points: [`sangercap/core/pipeline.py`](https://github.com/octavianix/sangercap/blob/main/sangercap/core/pipeline.py) (Pipeline), [`sangercap/interfaces/runservice.py`](https://github.com/octavianix/sangercap/blob/main/sangercap/interfaces/runservice.py) (Run service), [`sangercap/interfaces/desktop/shell.py`](https://github.com/octavianix/sangercap/blob/main/sangercap/interfaces/desktop/shell.py) (Desktop app), [`sangercap/core/blast.py`](https://github.com/octavianix/sangercap/blob/main/sangercap/core/blast.py) (BLAST search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_desktop["Desktop app<br/>[shell.py]"]
  node_runservice["Run service<br/>[runservice.py]"]
end

subgraph group_analysis["Analysis pipeline"]
  node_pipeline["Pipeline<br/>[pipeline.py]"]
  node_formats["Trace and sequence formats<br/>[formats.py]"]
  node_abi["ABI trace reader<br/>[abi.py]"]
  node_trimming["Quality trimming<br/>[trim.py]"]
  node_grouping["Read grouping<br/>[cluster.py]"]
  node_assembly["CAP3 assembly<br/>[cap3.py]"]
  node_identification["BLAST search<br/>[blast.py]"]
  node_alignment["Global alignment<br/>[align.py]"]
  node_classification["Taxonomic classification<br/>[classify.py]"]
  node_editor["Trace editor<br/>[editor.py]"]
  node_vector["Vector screening<br/>[vector.py]"]
end

subgraph group_results["Results and review"]
  node_review["Review flags<br/>[pipeline.py]"]
  node_report["HTML report<br/>[report_html.py]"]
end

subgraph group_operations["Operations and integrations"]
  node_database_manager["Database manager<br/>[dbmanager.py]"]
  node_database_catalogue["Marker database catalogue<br/>[databases.py]"]
  node_scheduler["Scheduled runs<br/>[scheduler.py]"]
  node_remote["Remote server adapter<br/>[remote.py]"]
  node_mailer["Result email<br/>[mailer.py]"]
  node_config["Settings and tool discovery<br/>[config.py]"]
end

node_lab_user(("Lab user"))
node_trace_tuner["TraceTuner"]
node_ncbi["NCBI BLAST"]
node_cap3_tool["CAP3 tool"]

node_lab_user -->|"starts run"| node_cli
node_lab_user -->|"opens traces"| node_desktop
node_cli -->|"delegates run"| node_runservice
node_desktop -.->|"submits run"| node_runservice
node_runservice -->|"executes"| node_pipeline
node_pipeline -->|"reads and writes"| node_formats
node_formats -->|"reads ABI"| node_abi
node_pipeline -->|"trims reads"| node_trimming
node_pipeline -->|"groups reads"| node_grouping
node_pipeline -->|"assembles groups"| node_assembly
node_assembly -->|"runs"| node_cap3_tool
node_pipeline -->|"searches candidates"| node_identification
node_identification -.->|"queries online"| node_ncbi
node_pipeline -->|"classifies hits"| node_classification
node_classification -->|"aligns candidates"| node_alignment
node_pipeline -->|"flags samples"| node_review
node_pipeline -->|"writes report"| node_report
node_desktop -->|"provides editing"| node_editor
node_desktop -->|"provides screening"| node_vector
node_identification -.->|"searches local databases"| node_database_manager
node_database_manager -->|"uses catalogue"| node_database_catalogue
node_scheduler -.->|"updates databases"| node_database_manager
node_scheduler -.->|"schedules runs"| node_runservice
node_remote -.->|"returns results"| node_lab_user
node_runservice -->|"emails results"| node_mailer
node_runservice -->|"uses settings"| node_config
node_trimming -.->|"runs when configured"| node_trace_tuner

click node_cli "https://github.com/octavianix/sangercap/blob/main/sangercap/interfaces/cli/main.py"
click node_desktop "https://github.com/octavianix/sangercap/blob/main/sangercap/interfaces/desktop/shell.py"
click node_runservice "https://github.com/octavianix/sangercap/blob/main/sangercap/interfaces/runservice.py"
click node_pipeline "https://github.com/octavianix/sangercap/blob/main/sangercap/core/pipeline.py"
click node_formats "https://github.com/octavianix/sangercap/blob/main/sangercap/core/formats.py"
click node_abi "https://github.com/octavianix/sangercap/blob/main/sangercap/core/abi.py"
click node_trimming "https://github.com/octavianix/sangercap/blob/main/sangercap/core/trim.py"
click node_grouping "https://github.com/octavianix/sangercap/blob/main/sangercap/core/cluster.py"
click node_assembly "https://github.com/octavianix/sangercap/blob/main/sangercap/core/cap3.py"
click node_identification "https://github.com/octavianix/sangercap/blob/main/sangercap/core/blast.py"
click node_alignment "https://github.com/octavianix/sangercap/blob/main/sangercap/core/align.py"
click node_classification "https://github.com/octavianix/sangercap/blob/main/sangercap/core/classify.py"
click node_editor "https://github.com/octavianix/sangercap/blob/main/sangercap/core/editor.py"
click node_vector "https://github.com/octavianix/sangercap/blob/main/sangercap/core/vector.py"
click node_review "https://github.com/octavianix/sangercap/blob/main/sangercap/core/pipeline.py"
click node_report "https://github.com/octavianix/sangercap/blob/main/sangercap/core/report_html.py"
click node_database_manager "https://github.com/octavianix/sangercap/blob/main/sangercap/core/dbmanager.py"
click node_database_catalogue "https://github.com/octavianix/sangercap/blob/main/sangercap/core/databases.py"
click node_scheduler "https://github.com/octavianix/sangercap/blob/main/sangercap/adapters/scheduler.py"
click node_remote "https://github.com/octavianix/sangercap/blob/main/sangercap/adapters/remote.py"
click node_mailer "https://github.com/octavianix/sangercap/blob/main/sangercap/adapters/mailer.py"
click node_config "https://github.com/octavianix/sangercap/blob/main/sangercap/config.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_cli,node_desktop,node_runservice,node_lab_user toneBlue
class node_pipeline,node_formats,node_abi,node_trimming,node_grouping,node_assembly,node_identification,node_alignment,node_classification,node_editor,node_vector toneAmber
class node_review,node_report toneMint
class node_database_manager,node_database_catalogue,node_scheduler,node_remote,node_mailer,node_config toneRose
class node_trace_tuner,node_ncbi,node_cap3_tool toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/octavianix/sangercap/blob/main/sangercap/interfaces/cli/main.py): `sangercap/interfaces/cli/main.py`
- [Desktop app](https://github.com/octavianix/sangercap/blob/main/sangercap/interfaces/desktop/shell.py): `sangercap/interfaces/desktop/shell.py`
- [Run service](https://github.com/octavianix/sangercap/blob/main/sangercap/interfaces/runservice.py): `sangercap/interfaces/runservice.py`

### Analysis pipeline

- [Pipeline](https://github.com/octavianix/sangercap/blob/main/sangercap/core/pipeline.py): `sangercap/core/pipeline.py`
- [Trace and sequence formats](https://github.com/octavianix/sangercap/blob/main/sangercap/core/formats.py): `sangercap/core/formats.py`
- [ABI trace reader](https://github.com/octavianix/sangercap/blob/main/sangercap/core/abi.py): `sangercap/core/abi.py`
- [Quality trimming](https://github.com/octavianix/sangercap/blob/main/sangercap/core/trim.py): `sangercap/core/trim.py`
- [Read grouping](https://github.com/octavianix/sangercap/blob/main/sangercap/core/cluster.py): `sangercap/core/cluster.py`
- [CAP3 assembly](https://github.com/octavianix/sangercap/blob/main/sangercap/core/cap3.py): `sangercap/core/cap3.py`
- [BLAST search](https://github.com/octavianix/sangercap/blob/main/sangercap/core/blast.py): `sangercap/core/blast.py`
- [Global alignment](https://github.com/octavianix/sangercap/blob/main/sangercap/core/align.py): `sangercap/core/align.py`
- [Taxonomic classification](https://github.com/octavianix/sangercap/blob/main/sangercap/core/classify.py): `sangercap/core/classify.py`
- [Trace editor](https://github.com/octavianix/sangercap/blob/main/sangercap/core/editor.py): `sangercap/core/editor.py`
- [Vector screening](https://github.com/octavianix/sangercap/blob/main/sangercap/core/vector.py): `sangercap/core/vector.py`

### Results and review

- [Review flags](https://github.com/octavianix/sangercap/blob/main/sangercap/core/pipeline.py): `sangercap/core/pipeline.py`
- [HTML report](https://github.com/octavianix/sangercap/blob/main/sangercap/core/report_html.py): `sangercap/core/report_html.py`

### Operations and integrations

- [Database manager](https://github.com/octavianix/sangercap/blob/main/sangercap/core/dbmanager.py): `sangercap/core/dbmanager.py`
- [Marker database catalogue](https://github.com/octavianix/sangercap/blob/main/sangercap/core/databases.py): `sangercap/core/databases.py`
- [Scheduled runs](https://github.com/octavianix/sangercap/blob/main/sangercap/adapters/scheduler.py): `sangercap/adapters/scheduler.py`
- [Remote server adapter](https://github.com/octavianix/sangercap/blob/main/sangercap/adapters/remote.py): `sangercap/adapters/remote.py`
- [Result email](https://github.com/octavianix/sangercap/blob/main/sangercap/adapters/mailer.py): `sangercap/adapters/mailer.py`
- [Settings and tool discovery](https://github.com/octavianix/sangercap/blob/main/sangercap/config.py): `sangercap/config.py`

### Other components

- **Lab user**
- **TraceTuner**
- **NCBI BLAST**
- **CAP3 tool**

## Connections

- Lab user → CLI: starts run (evidence: `README.md`)
- Lab user → Desktop app: opens traces (evidence: `README.md`)
- CLI → Run service: delegates run (evidence: `sangercap/interfaces/cli/main.py`)
- Desktop app → Run service: submits run
- Run service → Pipeline: executes (evidence: `sangercap/interfaces/runservice.py`)
- Pipeline → Trace and sequence formats: reads and writes (evidence: `sangercap/core/pipeline.py`)
- Trace and sequence formats → ABI trace reader: reads ABI (evidence: `sangercap/core/formats.py`)
- Pipeline → Quality trimming: trims reads (evidence: `README.md`)
- Pipeline → Read grouping: groups reads (evidence: `README.md`)
- Pipeline → CAP3 assembly: assembles groups (evidence: `sangercap/core/pipeline.py`)
- CAP3 assembly → CAP3 tool: runs (evidence: `README.md`)
- Pipeline → BLAST search: searches candidates (evidence: `sangercap/core/pipeline.py`)
- BLAST search → NCBI BLAST: queries online (evidence: `README.md`)
- Pipeline → Taxonomic classification: classifies hits (evidence: `sangercap/core/pipeline.py`)
- Taxonomic classification → Global alignment: aligns candidates (evidence: `sangercap/core/classify.py`)
- Pipeline → Review flags: flags samples (evidence: `README.md`)
- Pipeline → HTML report: writes report (evidence: `sangercap/core/pipeline.py`)
- Desktop app → Trace editor: provides editing (evidence: `README.md`)
- Desktop app → Vector screening: provides screening (evidence: `README.md`)
- BLAST search → Database manager: searches local databases
- Database manager → Marker database catalogue: uses catalogue (evidence: `sangercap/core/dbmanager.py`)
- Scheduled runs → Database manager: updates databases
- Scheduled runs → Run service: schedules runs
- Remote server adapter → Lab user: returns results
- Run service → Result email: emails results (evidence: `sangercap/interfaces/runservice.py`)
- Run service → Settings and tool discovery: uses settings (evidence: `sangercap/interfaces/runservice.py`)
- Quality trimming → TraceTuner: runs when configured
