# hzi-bifo/ribodetector architecture

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

- Interactive diagram: https://gitdiagram.com/hzi-bifo/ribodetector
- Repository: https://github.com/hzi-bifo/ribodetector

## Overview

RiboDetector is a command-line rRNA detector for FASTA/FASTQ sequencing reads. Its main workflow loads reads, encodes them, classifies them in GPU or CPU mode, then separates non-rRNA, rRNA, and optionally unclassified reads into output files. Paired-end confidence handling and chunked processing are part of the detector workflow. The excerpts show the GPU model and shared sequence-processing calls; CPU inference uses ONNX Runtime. Some utility and loader abstractions are present, but their runtime connections are not shown.

Main entry points: [`ribodetector/detect.py`](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/detect.py) (GPU detector), [`ribodetector/detect_cpu.py`](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/detect_cpu.py) (CPU detector), [`ribodetector/data_loader/seq_encoder.py`](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/data_loader/seq_encoder.py) (Sequence encoder), [`ribodetector/parse_config.py`](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/parse_config.py) (Config parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Detection workflow"]
  node_gpu_detect["GPU detector<br/>[detect.py]"]
  node_cpu_detect["CPU detector<br/>[detect_cpu.py]"]
end

subgraph group_input["Read preparation"]
  node_read_parser["FASTX parser<br/>[fastx_parser.py]"]
  node_seq_encoder["Sequence encoder<br/>[seq_encoder.py]"]
  node_dataset["Dataset loader<br/>[dataset.py]"]
  node_base_loader["Loader base"]
end

subgraph group_models["Classification models"]
  node_gpu_model["LSTM model<br/>[model.py]"]
  node_cpu_model["CPU model<br/>[model_cpu.py]"]
  node_base_model["Model base<br/>[base_model.py]"]
end

subgraph group_support["Configuration and support"]
  node_config["Config parser<br/>[parse_config.py]"]
  node_utilities["JSON utilities<br/>[util.py]"]
  node_logger["Logger helper<br/>[logger.py]"]
end

node_user(("CLI user"))
node_read_files["FASTA/FASTQ reads"]
node_nonrrna_output["Non-rRNA reads"]
node_rrna_output["rRNA reads"]
node_unknown_output["Unclassified reads"]

node_user -->|"runs GPU mode"| node_gpu_detect
node_user -->|"runs CPU mode"| node_cpu_detect
node_read_files -->|"provides reads"| node_gpu_detect
node_read_files -->|"provides reads"| node_cpu_detect
node_gpu_detect -->|"uses configuration"| node_config
node_cpu_detect -->|"uses configuration"| node_config
node_gpu_detect -->|"encodes reads"| node_seq_encoder
node_gpu_detect -->|"loads batches"| node_dataset
node_cpu_detect -->|"encodes reads"| node_seq_encoder
node_seq_encoder -->|"parses records"| node_read_parser
node_gpu_detect -->|"classifies reads"| node_gpu_model
node_gpu_model -->|"inherits from"| node_base_model
node_cpu_model -->|"inherits from"| node_base_model
node_gpu_detect -->|"writes classified reads"| node_nonrrna_output
node_gpu_detect -->|"writes classified reads"| node_rrna_output
node_gpu_detect -->|"writes uncertain reads"| node_unknown_output
node_cpu_detect -->|"writes classified reads"| node_nonrrna_output
node_cpu_detect -->|"writes classified reads"| node_rrna_output
node_cpu_detect -->|"writes uncertain reads"| node_unknown_output
node_config -->|"reads JSON"| node_utilities

click node_gpu_detect "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/detect.py"
click node_cpu_detect "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/detect_cpu.py"
click node_read_parser "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/data_loader/fastx_parser.py"
click node_seq_encoder "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/data_loader/seq_encoder.py"
click node_dataset "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/data_loader/dataset.py"
click node_gpu_model "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/model/model.py"
click node_cpu_model "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/model/model_cpu.py"
click node_base_model "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/base/base_model.py"
click node_base_loader "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/base/base_data_loader.py"
click node_config "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/parse_config.py"
click node_utilities "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/utils/util.py"
click node_logger "https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/logger/logger.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_gpu_detect,node_cpu_detect,node_user toneBlue
class node_read_parser,node_seq_encoder,node_dataset,node_base_loader toneAmber
class node_gpu_model,node_cpu_model,node_base_model toneMint
class node_config,node_utilities,node_logger toneRose
class node_read_files,node_nonrrna_output,node_rrna_output,node_unknown_output toneIndigo
```

## Components

### Detection workflow

- [GPU detector](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/detect.py): `ribodetector/detect.py`
- [CPU detector](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/detect_cpu.py): `ribodetector/detect_cpu.py`

### Read preparation

- [FASTX parser](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/data_loader/fastx_parser.py): `ribodetector/data_loader/fastx_parser.py`
- [Sequence encoder](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/data_loader/seq_encoder.py): `ribodetector/data_loader/seq_encoder.py`
- [Dataset loader](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/data_loader/dataset.py): `ribodetector/data_loader/dataset.py`
- [Loader base](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/base/base_data_loader.py): `ribodetector/base/base_data_loader.py`

### Classification models

- [LSTM model](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/model/model.py): `ribodetector/model/model.py`
- [CPU model](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/model/model_cpu.py): `ribodetector/model/model_cpu.py`
- [Model base](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/base/base_model.py): `ribodetector/base/base_model.py`

### Configuration and support

- [Config parser](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/parse_config.py): `ribodetector/parse_config.py`
- [JSON utilities](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/utils/util.py): `ribodetector/utils/util.py`
- [Logger helper](https://github.com/hzi-bifo/ribodetector/blob/pip/ribodetector/logger/logger.py): `ribodetector/logger/logger.py`

### Other components

- **CLI user**
- **FASTA/FASTQ reads**
- **Non-rRNA reads**
- **rRNA reads**
- **Unclassified reads**

## Connections

- CLI user → GPU detector: runs GPU mode (evidence: `README.md`)
- CLI user → CPU detector: runs CPU mode (evidence: `README.md`)
- FASTA/FASTQ reads → GPU detector: provides reads (evidence: `README.md`)
- FASTA/FASTQ reads → CPU detector: provides reads (evidence: `README.md`)
- GPU detector → Config parser: uses configuration (evidence: `ribodetector/detect.py`)
- CPU detector → Config parser: uses configuration (evidence: `ribodetector/detect_cpu.py`)
- GPU detector → Sequence encoder: encodes reads (evidence: `ribodetector/detect.py`)
- GPU detector → Dataset loader: loads batches (evidence: `ribodetector/detect.py`)
- CPU detector → Sequence encoder: encodes reads (evidence: `ribodetector/detect_cpu.py`)
- Sequence encoder → FASTX parser: parses records (evidence: `ribodetector/data_loader/seq_encoder.py`)
- GPU detector → LSTM model: classifies reads (evidence: `ribodetector/detect.py`)
- LSTM model → Model base: inherits from (evidence: `ribodetector/model/model.py`)
- CPU model → Model base: inherits from (evidence: `ribodetector/model/model_cpu.py`)
- GPU detector → Non-rRNA reads: writes classified reads (evidence: `ribodetector/detect.py`)
- GPU detector → rRNA reads: writes classified reads (evidence: `ribodetector/detect.py`)
- GPU detector → Unclassified reads: writes uncertain reads (evidence: `ribodetector/detect.py`)
- CPU detector → Non-rRNA reads: writes classified reads (evidence: `ribodetector/detect_cpu.py`)
- CPU detector → rRNA reads: writes classified reads (evidence: `ribodetector/detect_cpu.py`)
- CPU detector → Unclassified reads: writes uncertain reads (evidence: `ribodetector/detect_cpu.py`)
- Config parser → JSON utilities: reads JSON (evidence: `ribodetector/parse_config.py`)
