# qcezads123456/rare-seq-finder architecture

> Architecture diagram of the GitHub repository qcezads123456/rare-seq-finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qcezads123456/rare-seq-finder
- Repository: https://github.com/qcezads123456/rare-seq-finder

## Overview

Rare Sequence Finder is a C++ command-line detector: users supply reference and target FASTA files plus optional thresholds; the program parses arguments, reads both inputs, indexes reference k-mers, finds rare target k-mers, and writes candidate-region reports and metadata. A separate, optional simulation-and-analysis workflow validates detections against mutation ground truth. The detector’s call relationships are supported by excerpts; validation links reflect README descriptions, since its runtime implementation was not sampled.

Main entry points: [`src/main.cpp`](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/main.cpp) (Program entry), [`src/result_processor.cpp`](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/result_processor.cpp) (Result processor), [`src/Kmer_encoder.cpp`](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/Kmer_encoder.cpp) (Reference k-mers), [`result`](https://github.com/qcezads123456/rare-seq-finder/tree/main/result) (TXT, TSV, JSON)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Detection inputs"]
  node_cli["CLI parsing<br/>[cli.cpp]"]
  node_fasta["FASTA reader<br/>[Fasta_reader.cpp]"]
end

subgraph group_detection["K-mer detection"]
  node_entry["Program entry<br/>[main.cpp]"]
  node_processor["Result processor"]
  node_index["Reference k-mers<br/>[Kmer_encoder.cpp]"]
  node_rare["Rare k-mers<br/>[Kmer_encoder.cpp]"]
  node_decoder["K-mer utilities<br/>[decoder.cpp]"]
end

subgraph group_reports["Detection reports"]
  node_reports["TXT, TSV, JSON"]
end

subgraph group_validation["Optional validation"]
  node_simdata["Simulated sequences"]
  node_truth["Ground truth"]
  node_analysis["Validation summaries<br/>[summary_create.py]"]
end

node_user(("User"))
node_simulator["Mutation Simulator"]

node_user -->|"runs"| node_entry
node_entry -->|"parses arguments"| node_cli
node_entry -->|"reads FASTA"| node_fasta
node_entry -->|"processes sequences"| node_processor
node_processor -->|"builds index"| node_index
node_processor -->|"finds candidates"| node_rare
node_index -->|"counts references"| node_decoder
node_rare -->|"counts references"| node_decoder
node_processor -->|"writes reports"| node_reports
node_simulator -->|"generates sequences"| node_simdata
node_simulator -->|"generates ground truth"| node_truth
node_reports -->|"evaluated against"| node_analysis
node_truth -->|"compared with"| node_analysis

click node_cli "https://github.com/qcezads123456/rare-seq-finder/blob/main/src/cli.cpp"
click node_fasta "https://github.com/qcezads123456/rare-seq-finder/blob/main/src/Fasta_reader.cpp"
click node_entry "https://github.com/qcezads123456/rare-seq-finder/blob/main/src/main.cpp"
click node_processor "https://github.com/qcezads123456/rare-seq-finder/blob/main/src/result_processor.cpp"
click node_index "https://github.com/qcezads123456/rare-seq-finder/blob/main/src/Kmer_encoder.cpp"
click node_rare "https://github.com/qcezads123456/rare-seq-finder/blob/main/src/Kmer_encoder.cpp"
click node_decoder "https://github.com/qcezads123456/rare-seq-finder/blob/main/src/decoder.cpp"
click node_reports "https://github.com/qcezads123456/rare-seq-finder/tree/main/result"
click node_simdata "https://github.com/qcezads123456/rare-seq-finder/tree/main/data/MS_output"
click node_truth "https://github.com/qcezads123456/rare-seq-finder/tree/main/data"
click node_analysis "https://github.com/qcezads123456/rare-seq-finder/blob/main/analysis/summary_create.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_fasta,node_user toneBlue
class node_entry,node_processor,node_index,node_rare,node_decoder toneAmber
class node_reports toneMint
class node_simdata,node_truth,node_analysis toneRose
class node_simulator toneIndigo
```

## Components

### Detection inputs

- [CLI parsing](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/cli.cpp): `src/cli.cpp`
- [FASTA reader](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/Fasta_reader.cpp): `src/Fasta_reader.cpp`

### K-mer detection

- [Program entry](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/main.cpp): `src/main.cpp`
- [Result processor](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/result_processor.cpp): `src/result_processor.cpp`
- [Reference k-mers](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/Kmer_encoder.cpp): `src/Kmer_encoder.cpp`
- [Rare k-mers](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/Kmer_encoder.cpp): `src/Kmer_encoder.cpp`
- [K-mer utilities](https://github.com/qcezads123456/rare-seq-finder/blob/main/src/decoder.cpp): `src/decoder.cpp`

### Detection reports

- [TXT, TSV, JSON](https://github.com/qcezads123456/rare-seq-finder/tree/main/result): `result`

### Optional validation

- [Simulated sequences](https://github.com/qcezads123456/rare-seq-finder/tree/main/data/MS_output): `data/MS_output`
- [Ground truth](https://github.com/qcezads123456/rare-seq-finder/tree/main/data): `data`
- [Validation summaries](https://github.com/qcezads123456/rare-seq-finder/blob/main/analysis/summary_create.py): `analysis/summary_create.py`

### Other components

- **User**
- **Mutation Simulator**

## Connections

- User → Program entry: runs (evidence: `README.md`)
- Program entry → CLI parsing: parses arguments (evidence: `src/main.cpp`)
- Program entry → FASTA reader: reads FASTA (evidence: `src/main.cpp`)
- Program entry → Result processor: processes sequences (evidence: `src/main.cpp`)
- Result processor → Reference k-mers: builds index (evidence: `src/result_processor.cpp`)
- Result processor → Rare k-mers: finds candidates (evidence: `src/result_processor.cpp`)
- Reference k-mers → K-mer utilities: counts references (evidence: `src/Kmer_encoder.cpp`)
- Rare k-mers → K-mer utilities: counts references (evidence: `src/Kmer_encoder.cpp`)
- Result processor → TXT, TSV, JSON: writes reports (evidence: `src/result_processor.cpp`)
- Mutation Simulator → Simulated sequences: generates sequences (evidence: `README.md`)
- Mutation Simulator → Ground truth: generates ground truth (evidence: `README.md`)
- TXT, TSV, JSON → Validation summaries: evaluated against (evidence: `README.md`)
- Ground truth → Validation summaries: compared with (evidence: `README.md`)