# Architecture

ViralUnity is a thin Python orchestration layer over Snakemake workflows. The
Python code validates inputs, writes a YAML config, and launches one of six
Snakemake workflows; all the bioinformatics lives in the `.smk` rule files.

## Data flow

```
CLI (click)                       viralunity_cli.py  →  <subcommand>_cli.py
   │  parses options, configures logging (--log-level / --json-logs)
   ▼
main(args)                        viralunity_consensus.py / viralunity_meta.py
   │  thin wrapper around…
   ▼
_orchestrator.run_pipeline(...)   viralunity/_orchestrator.py
   │  resolve_paths → validate → generate_config → [run manifest] → run_workflow
   ▼
ConfigGenerator → YAML            viralunity/config_generator.py
   │  emits the exact keys the .smk files read (config["samples"], …)
   ▼
snakemake(workflow.smk, config)   viralunity/scripts/<pipeline>_<datatype>.smk
   │  rule all → _all_inputs() → include: rules/*.smk
   ▼
per-rule conda envs               viralunity/scripts/envs/*.yaml  (--use-conda)
```

## Module map

| Module | Responsibility |
|---|---|
| `viralunity_cli.py` | Top-level click group; wires `--log-level` / `--json-logs`. |
| `<sub>_cli.py` | Per-subcommand click options → plain `args` dict. |
| `viralunity_consensus.py`, `viralunity_meta.py` | Own `validate_args`, `generate_config_file`, `run_snakemake_workflow`; call the orchestrator. |
| `_orchestrator.py` | Shared `run_pipeline` skeleton (resolve → validate → config → manifest → run) with structured error handling. |
| `validators.py` | File/dir existence, sample-sheet parsing, cross-dependency checks, input sanitization, and content-level input-integrity orchestration (`validate_consensus_input_integrity`). |
| `integrity.py` | Streaming, pure-stdlib content validators for consensus inputs (FASTQ/FASTA/BED/GFF3); collect `IntegrityIssue`s rather than raising. |
| `reference_splitter.py` | Splits a multi-record `--reference` FASTA (and a combined annotation) into the per-segment `{segment: path}` dict the segmented workflows consume. |
| `config_generator.py` | Writes the YAML config (the contract with the `.smk` files). |
| `constants.py` | `ConfigKeys`, `DataType`, `ResourceDefaults` (per-pipeline rule lists). |
| `exceptions.py` | Typed error hierarchy with machine-readable `code`s. |
| `logging_config.py` | Central logging (run id, text/JSON). |
| `provenance.py` | `run_manifest.json` (version, config, input checksums). |
| `_subprocess.py` | `run_command` for external tools (get-databases / build-deacon-index), with timeouts. |
| `scripts/*.smk`, `scripts/rules/*.smk` | The actual pipelines. |
| `scripts/python/*.py` | Helpers run via Snakemake's `script:` directive. |

## The config is the contract

`ConfigGenerator` emits keys that are hard-coded as strings in the `.smk` files
(e.g. `config["samples"]`, `config["output"]`, `config["run_denovo_assembly"]`).
Adding a pipeline option means touching four places: the click option in the
relevant `*_cli.py`, the `validators.py` check, a `ConfigGenerator.add_*` setter,
and the rule(s) that read it. `config["samples"]` maps `sample-<id>` to a **list**
of FASTQ paths (readers tolerate the legacy space-joined string form too).

## Workflow selection

`run_snakemake_workflow` formats a path:
`scripts/{consensus,metagenomics}_{illumina,nanopore}[_segmented].smk`.
Segmentation is chosen when `args["reference"]` is a dict — built either from
repeatable `--segmented-reference SEGMENT=PATH`, or by `reference_splitter.py`
auto-splitting a single multi-record `--reference` FASTA during validation
(unless `--single-reference`). There is no segmented metagenomics variant.