# pathogenomics-lab/snpick architecture

> Architecture diagram of the GitHub repository pathogenomics-lab/snpick, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pathogenomics-lab/snpick
- Repository: https://github.com/pathogenomics-lab/snpick

## Overview

##### Project Type and Purpose
- SNPick is a Rust-based command-line tool (CLI) for bioinformatics, designed to extract SNP sites from large FASTA alignments.
- It targets high-performance, memory-efficient batch processing of genomic data, producing either a reduced SNP-only FASTA or a standard VCF file for downstream phylogenetic tools (RAxML, IQ-TREE).

##### File-Structure Analysis
- Top-level:
- Cargo.toml / Cargo.lock – Rust build and dependency manifests
- src/main.rs – single binary entry point, likely organizing modules internally
- .github/ – CI (GitHub Actions), issue/pr templates, code of conduct
- README.md, LICENSE – documentation and licensing
- No separate “lib” or “tests” directory, so internal modules and tests live inside src/main.rs or nested sub-modules.
- Build workflows: rust.yml under .github/workflows for automated testing and release builds.

##### Key README Insights
- Core features: FASTA reader, SNP detection engine, multi-threading, IUPAC nucleotide handling, VCF writer, progress bar.
- CLI flags: –fasta, –output, –threads, –vcf, –vcf-output, –include-gaps.
- Packaging: distributed via Bioconda and GitHub releases.

a. Main Components
1. CLI Argument Parser
2. FASTA Input Module
3. SNP Extraction Core
4. Thread Pool / Task Scheduler
5. Memory Manager / Data Structures
6. Output Writer (FASTA & VCF)
7. Progress Monitor
8. External Interfaces (Filesystem, User Shell, Downstream Tools)
b. Relationships & Interactions
- User invokes the binary with flags → Argument Parser configures modules
- FASTA Input Module reads sequences (File I/O) → passes to SNP Extraction Core
- Thread Pool dispatches alignment chunks to parallel Extraction workers
- Extraction Core uses Memory Manager to track variable sites, handles IUPAC codes
- As SNPs are discovered, data is buffered and fed to Output Writer
- Progress Monitor polls I/O and worker progress → updates spinner/bar to STDERR
- Final output files written to disk; user may pipe into RAxML/IQ-TREE or open VCF
c. Architectural Patterns & Principles
- Single-process, multi-threaded pipeline (shared-memory concurrency)
- Modular separation of concerns: I/O ↔ Processing ↔ Output ↔ Monitoring
- Efficient memory use via streaming and chunking, avoiding full in-memory alignment
- CLI-first design, minimal dependencies for portability
d. Technologies & Libraries
- Rust (Cargo build system)
- Likely crates: clap or structopt (argument parsing), rayon (thread pool), bio or custom FASTA parser, indicatif (progress bar), serde or custom VCF writer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interfaces
    subgraph "External Interfaces" 
        direction TB
        UserShell(("User Shell")):::external
        DownstreamTools(("Downstream Tools (RAxML/IQ-TREE)")):::external
    end

    %% Core Pipeline
    subgraph "CLI Pipeline"
        direction TB
        ArgumentParser["CLI Argument Parser"]:::control
        FastaInput["FASTA Input Module"]:::io
        ThreadPool["Thread Pool / Task Scheduler"]:::compute
        SNPExtraction["SNP Extraction Core"]:::compute
        MemoryManager["Memory Manager / Data Structures"]:::compute
        OutputWriter["Output Writer (FASTA & VCF)"]:::io
        ProgressMonitor["Progress Monitor"]:::control
    end

    %% File System
    FileSystem[(File System / Disk)]:::storage

    %% Infrastructure
    subgraph "Project Infrastructure"
        direction TB
        CIWorkflow["CI Workflow (.github/workflows/rust.yml)"]:::infra
        ProjectMetadata["Project Metadata & Dependencies (Cargo.toml)"]:::infra
        Documentation["Documentation & License (README.md)"]:::infra
    end

    %% Data Flow
    UserShell -->|invokes with flags| ArgumentParser
    ArgumentParser -->|configures| FastaInput
    ArgumentParser -->|configures| ThreadPool
    ArgumentParser -->|configures| OutputWriter

    FileSystem -->|reads FASTA| FastaInput
    FastaInput -->|chunks sequences| ThreadPool
    ThreadPool -->|dispatches work| SNPExtraction
    SNPExtraction -->|identifies SNPs| MemoryManager
    MemoryManager -->|buffers SNP data| OutputWriter
    OutputWriter -->|writes files| FileSystem
    OutputWriter -->|produces output| DownstreamTools

    %% Progress Monitoring
    FastaInput -.->|observes| ProgressMonitor
    ThreadPool -.->|observes| ProgressMonitor
    SNPExtraction -.->|observes| ProgressMonitor
    OutputWriter -.->|observes| ProgressMonitor

    %% Infrastructure Links
    CIWorkflow --> ProjectMetadata
    ProjectMetadata --> Documentation

    %% Click Events
    click ArgumentParser "https://github.com/pathogenomics-lab/snpick/blob/main/src/main.rs"
    click FastaInput "https://github.com/pathogenomics-lab/snpick/blob/main/src/main.rs"
    click SNPExtraction "https://github.com/pathogenomics-lab/snpick/blob/main/src/main.rs"
    click ThreadPool "https://github.com/pathogenomics-lab/snpick/blob/main/Cargo.toml"
    click MemoryManager "https://github.com/pathogenomics-lab/snpick/blob/main/src/main.rs"
    click OutputWriter "https://github.com/pathogenomics-lab/snpick/blob/main/src/main.rs"
    click ProgressMonitor "https://github.com/pathogenomics-lab/snpick/blob/main/Cargo.toml"
    click FileSystem "https://github.com/pathogenomics-lab/snpick/blob/main/src/main.rs"
    click DownstreamTools "https://github.com/pathogenomics-lab/snpick/blob/main/README.md"
    click CIWorkflow "https://github.com/pathogenomics-lab/snpick/blob/main/.github/workflows/rust.yml"
    click ProjectMetadata "https://github.com/pathogenomics-lab/snpick/blob/main/Cargo.toml"
    click Documentation "https://github.com/pathogenomics-lab/snpick/blob/main/README.md"

    %% Styles
    classDef compute fill:#cce5ff,stroke:#004085,color:#004085
    classDef io fill:#d5f5e3,stroke:#1e8449,color:#1e8449
    classDef control fill:#fcf3cf,stroke:#b9770e,color:#b9770e
    classDef external fill:#f2f3f4,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 5
    classDef storage fill:#f0f0f0,stroke:#7f8c8d,color:#7f8c8d
    classDef infra fill:#f9e79f,stroke:#b7950b,color:#7f6000
```
