# mydennislab/cifi-toolkit architecture

> Architecture diagram of the GitHub repository mydennislab/cifi-toolkit, 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/mydennislab/cifi-toolkit
- Repository: https://github.com/mydennislab/cifi-toolkit

## Overview

cifi-toolkit processes CiFi long reads from QC through in-silico digestion and contact generation, with an alternate unique-segment mapping route for reconstructing contacts. The CLI also exposes alignment filtering and enzyme information; outputs include reports and contact files for downstream tools. The graph combines documented workflows with source-index references and shown calls. Some command implementations and report wiring were not excerpted, so those relationships are documented rather than inferred from module names.

Main entry points: [`src/cifi_cpp/core/digestion.cpp`](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/core/digestion.cpp) (Read digestion), [`src/cifi/cli.py`](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi/cli.py) (CLI commands), [`src/cifi_cpp/contacts/contacts.cpp`](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/contacts/contacts.cpp) (Pair reconstruction), [`src/cifi_cpp/cifi.cpp`](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/cifi.cpp) (Read QC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_processing["Read processing"]
  node_qc["Read QC<br/>[cifi.cpp]"]
  node_enzyme["Enzyme definitions<br/>[enzyme.cpp]"]
  node_digest["Read digestion<br/>[digestion.cpp]"]
  node_segment_names["Segment naming<br/>[segment_name.cpp]"]
  node_bam_filter["Alignment filter<br/>[bam_filter.cpp]"]
  node_fastq_reader["FASTQ parsing<br/>[kseq.h]"]
end

subgraph group_contacts["Contact reconstruction"]
  node_contacts["Pair reconstruction<br/>[contacts.cpp]"]
  node_alignment_bam["Segment alignments"]
end

subgraph group_output["Output and analysis"]
  node_stats["Statistics<br/>[statistics.cpp]"]
  node_writers["File writers<br/>[writer.cpp]"]
  node_report["Report generation<br/>[report.py]"]
  node_hashmap["Hash map utilities"]
  node_paired_fastq["Paired FASTQ"]
  node_segments_fastq["Unique segments"]
  node_contact_output["BED or PA5 contacts"]
  node_qc_report["QC report"]
end

node_user(("Researcher"))
node_downstream(("Assembly or scaffolding"))

node_user -->|"runs commands"| node_cli
node_cli -->|"runs QC"| node_qc
node_cli -->|"runs digestion"| node_digest
node_cli -->|"lists enzymes"| node_enzyme
node_cli -->|"runs filtering"| node_bam_filter
node_cli -->|"reconstructs contacts"| node_contacts
node_cli -->|"generates reports"| node_report
node_qc -.->|"uses site"| node_enzyme
node_digest -->|"uses site"| node_enzyme
node_digest -->|"records metrics"| node_stats
node_digest -->|"writes reads"| node_writers
node_digest -.->|"names segments"| node_segment_names
node_fastq_reader -.->|"parses FASTQ"| node_digest
node_contacts -->|"parses names"| node_segment_names
node_contacts -->|"writes contacts"| node_writers
node_contacts -->|"collects metrics"| node_stats
node_stats -->|"uses hash map"| node_hashmap
node_digest -->|"emits pairs"| node_paired_fastq
node_digest -->|"emits segments"| node_segments_fastq
node_segments_fastq -->|"mapped externally"| node_alignment_bam
node_alignment_bam -->|"reconstructs pairs"| node_contacts
node_contacts -->|"writes BED or PA5"| node_contact_output
node_qc -->|"summarizes reads"| node_qc_report
node_report -->|"renders report"| node_qc_report
node_contact_output -->|"feeds scaffolding"| node_downstream
node_paired_fastq -->|"feeds assembly"| node_downstream

click node_cli "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi/cli.py"
click node_qc "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/cifi.cpp"
click node_enzyme "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/core/enzyme.cpp"
click node_digest "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/core/digestion.cpp"
click node_segment_names "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/core/segment_name.cpp"
click node_bam_filter "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/filter/bam_filter.cpp"
click node_contacts "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/contacts/contacts.cpp"
click node_stats "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/stats/statistics.cpp"
click node_writers "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/io/writer.cpp"
click node_report "https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi/report.py"
click node_fastq_reader "https://github.com/mydennislab/cifi-toolkit/blob/main/extern/kseq.h"
click node_hashmap "https://github.com/mydennislab/cifi-toolkit/tree/main/extern/parallel_hashmap/parallel_hashmap"

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 toneBlue
class node_qc,node_enzyme,node_digest,node_segment_names,node_bam_filter,node_fastq_reader toneAmber
class node_contacts,node_alignment_bam toneMint
class node_stats,node_writers,node_report,node_hashmap,node_paired_fastq,node_segments_fastq,node_contact_output,node_qc_report toneRose
class node_user,node_downstream toneIndigo
```

## Components

### User interface

- [CLI commands](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi/cli.py): `src/cifi/cli.py`

### Read processing

- [Read QC](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/cifi.cpp): `src/cifi_cpp/cifi.cpp`
- [Enzyme definitions](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/core/enzyme.cpp): `src/cifi_cpp/core/enzyme.cpp`
- [Read digestion](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/core/digestion.cpp): `src/cifi_cpp/core/digestion.cpp`
- [Segment naming](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/core/segment_name.cpp): `src/cifi_cpp/core/segment_name.cpp`
- [Alignment filter](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/filter/bam_filter.cpp): `src/cifi_cpp/filter/bam_filter.cpp`
- [FASTQ parsing](https://github.com/mydennislab/cifi-toolkit/blob/main/extern/kseq.h): `extern/kseq.h`

### Contact reconstruction

- [Pair reconstruction](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/contacts/contacts.cpp): `src/cifi_cpp/contacts/contacts.cpp`
- **Segment alignments**

### Output and analysis

- [Statistics](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/stats/statistics.cpp): `src/cifi_cpp/stats/statistics.cpp`
- [File writers](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi_cpp/io/writer.cpp): `src/cifi_cpp/io/writer.cpp`
- [Report generation](https://github.com/mydennislab/cifi-toolkit/blob/main/src/cifi/report.py): `src/cifi/report.py`
- [Hash map utilities](https://github.com/mydennislab/cifi-toolkit/tree/main/extern/parallel_hashmap/parallel_hashmap): `extern/parallel_hashmap/parallel_hashmap`
- **Paired FASTQ**
- **Unique segments**
- **BED or PA5 contacts**
- **QC report**

### Other components

- **Researcher**
- **Assembly or scaffolding**

## Connections

- Researcher → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Read QC: runs QC (evidence: `README.md`)
- CLI commands → Read digestion: runs digestion (evidence: `src/cifi/cli.py`)
- CLI commands → Enzyme definitions: lists enzymes (evidence: `README.md`)
- CLI commands → Alignment filter: runs filtering (evidence: `README.md`)
- CLI commands → Pair reconstruction: reconstructs contacts (evidence: `README.md`)
- CLI commands → Report generation: generates reports (evidence: `src/cifi/cli.py`)
- Read QC → Enzyme definitions: uses site
- Read digestion → Enzyme definitions: uses site
- Read digestion → Statistics: records metrics
- Read digestion → File writers: writes reads
- Read digestion → Segment naming: names segments
- FASTQ parsing → Read digestion: parses FASTQ
- Pair reconstruction → Segment naming: parses names (evidence: `src/cifi_cpp/contacts/contacts.cpp`)
- Pair reconstruction → File writers: writes contacts (evidence: `src/cifi_cpp/contacts/contacts.cpp`)
- Pair reconstruction → Statistics: collects metrics
- Statistics → Hash map utilities: uses hash map
- Read digestion → Paired FASTQ: emits pairs (evidence: `README.md`)
- Read digestion → Unique segments: emits segments (evidence: `README.md`)
- Unique segments → Segment alignments: mapped externally (evidence: `README.md`)
- Segment alignments → Pair reconstruction: reconstructs pairs (evidence: `README.md`)
- Pair reconstruction → BED or PA5 contacts: writes BED or PA5
- Read QC → QC report: summarizes reads (evidence: `README.md`)
- Report generation → QC report: renders report (evidence: `src/cifi/report.py`)
- BED or PA5 contacts → Assembly or scaffolding: feeds scaffolding (evidence: `README.md`)
- Paired FASTQ → Assembly or scaffolding: feeds assembly (evidence: `README.md`)
