# mikolmogorov/flye architecture

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

- Interactive diagram: https://gitdiagram.com/mikolmogorov/flye
- Repository: https://github.com/mikolmogorov/flye

## Overview

##### Project Type and Purpose
- Project Type: A command-line, pipeline-style de-novo genome assembler.
- Purpose: Takes raw long sequencing reads (PacBio or ONT), constructs a repeat graph, assembles contigs, polishes them, and recovers short plasmids.

##### High-Level Components
– Parses user arguments via main.py
– Loads configuration via flye/config/configurator.py
– Invokes sub-modules in sequence

A. “Assembly Stage”
- Python entry: flye/assembly/assemble.py
- Core C++ binary: src/assemble/main_assemble.cpp
- Subcomponents: repeat_graph builder (flye/assembly/repeat_graph.py), scaffolder
B. “Repeat Graph & Traversal”
- Python modules: flye/repeat_graph/*.py
- C++ (optional): src/repeat_graph/main_repeat.cpp and helpers
C. “Contig Extension (Contigger)”
- Python not used—pure C++: src/contigger/main_contigger.cpp
D. “Polishing Stage”
- Python: flye/polishing/polish.py
- C++ binary: src/polishing/main_polisher.cpp
E. “Short Plasmid Recovery”
- Python: flye/short_plasmids/*.py
F. “Trestle Haplotype Resolver”
- Python: flye/trestle/trestle.py

##### Third-Party Libraries
Externally bundled libs under a “Third-Party Engines” area:
- minimap2 (lib/minimap2) – invoked for read alignment
- samtools / htslib (lib/samtools-1.9) – for BAM/CRAM I/O
- libcuckoo, interval_tree, lemon – data structures and algorithms

##### Data Flow & Artifacts
- raw_reads.fq
- corrected_reads.fasta
- repeat_graph.gfa
- draft_contigs.fasta
- polished_contigs.fasta
- plasmids.fasta

##### Important Architectural Patterns
- Orchestration Layer (Python) vs. Compute Layer (C++ executables)
- Modular pipeline: each stage is independently invoked and can be debugged/tested
- Configuration injection: bin_cfg files → py_cfg → assembler parameters

##### Technologies & Frameworks
- Python 3 (entry points, orchestration, config)
- C++17 (algorithmic cores)
- Makefiles for C++ builds (src/Makefile)
- setup.py / BioConda packaging

##### Be Detailed
– Show that bin/flye is a thin wrapper that invokes Python’s main entry point.

[User Terminal]
↓
[bin/flye script]
↓
[Python Orchestrator: flye/main.py]
├─> [Configurator: flye/config]
├─> [Assembly Module]
│     • flye/assembly/*.py
│     • calls src/assemble/main_assemble
│     • uses minimap2, lemon, interval_tree
├─> [Repeat Graph Module]
│     • flye/repeat_graph/*.py
│     • calls src/repeat_graph/main_repeat
├─> [Contigger Module]
│     • calls src/contigger/main_contigger
├─> [Polisher Module]
│     • flye/polishing/*.py
│     • calls src/polishing/main_polisher
├─> [Short Plasmids Module]
│     • flye/short_plasmids/*.py
└─> [Trestle Module]
- flye/trestle/*.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and entry
    UserTerminal["User Terminal"]
    binFlye["bin/flye script"]:::python
    pyMain["flye/main.py"]:::python
    UserTerminal -->|runs| binFlye
    binFlye -->|invokes| pyMain

    %% Configuration
    configurator["flye/config/configurator.py"]:::python
    binCfg["flye/config/bin_cfg/"]:::python
    pyCfg["flye/config/py_cfg.py"]:::python
    pyMain -->|loads config| configurator
    configurator --> binCfg
    configurator --> pyCfg

    %% Python Orchestrator to stages
    pyMain -->|invoke| AssemblyStage
    pyMain -->|invoke| RepeatGraphStage
    pyMain -->|invoke| ContiggerStage
    pyMain -->|invoke| PolishingStage
    pyMain -->|invoke| ShortPlasmidsStage
    pyMain -->|invoke| TrestleStage

    %% Assembly Stage
    subgraph "Assembly Stage"
        direction TB
        assemblyPy["flye/assembly/assemble.py"]:::python
        repeaterInAssembly["flye/assembly/repeat_graph.py"]:::python
        scaffolder["flye/assembly/scaffolder.py"]:::python
        assemblyCpp["src/assemble/main_assemble.cpp"]:::cpp
    end
    AssemblyStage --> assemblyPy
    assemblyPy --> repeaterInAssembly
    assemblyPy --> scaffolder
    assemblyPy --> assemblyCpp
    assemblyCpp -->|uses| minimap2
    assemblyCpp -->|uses| lemon
    assemblyCpp -->|uses| interval_tree

    %% Repeat Graph Stage
    subgraph "Repeat Graph & Traversal"
        direction TB
        repeatGraphPy["flye/repeat_graph/*.py"]:::python
        repeatGraphCpp["src/repeat_graph/main_repeat.cpp"]:::cpp
    end
    RepeatGraphStage --> repeatGraphPy
    repeatGraphPy --> repeatGraphCpp
    repeatGraphCpp -->|uses| libcuckoo

    %% Contigger Stage
    subgraph "Contig Extension (Contigger)"
        direction TB
        contiggerCpp["src/contigger/main_contigger.cpp"]:::cpp
    end
    ContiggerStage --> contiggerCpp

    %% Polishing Stage
    subgraph "Polishing Stage"
        direction TB
        polishPy["flye/polishing/polish.py"]:::python
        polisherCpp["src/polishing/main_polisher.cpp"]:::cpp
    end
    PolishingStage --> polishPy
    polishPy --> polisherCpp

    %% Short Plasmid Recovery
    subgraph "Short Plasmid Recovery"
        direction TB
        shortPlasmids["flye/short_plasmids/*.py"]:::python
    end
    ShortPlasmidsStage --> shortPlasmids

    %% Trestle
    trestle["flye/trestle/trestle.py"]:::python
    TrestleStage --> trestle

    %% Third-Party Engines
    subgraph "Third-Party Engines"
        direction TB
        minimap2["minimap2"]:::lib
        samtools["samtools/htslib"]:::lib
        interval_tree["interval_tree"]:::lib
        lemon["lemon"]:::lib
        libcuckoo["libcuckoo"]:::lib
    end

    %% Data flow
    rawReads["raw_reads.fq"]:::file
    corrected["corrected_reads.fasta"]:::file
    repeatGFA["repeat_graph.gfa"]:::file
    draftContigs["draft_contigs.fasta"]:::file
    polishedContigs["polished_contigs.fasta"]:::file
    plasmidsFile["plasmids.fasta"]:::file

    rawReads -->|input| assemblyPy
    assemblyCpp -->|outputs| corrected
    assemblyCpp -->|outputs| repeatGFA
    repeatGraphPy -->|consumes| repeatGFA
    repeatGraphCpp -->|outputs| draftContigs
    contiggerCpp -->|consumes| draftContigs
    contiggerCpp -->|outputs| draftContigs
    polishPy -->|consumes| draftContigs
    polisherCpp -->|outputs| polishedContigs
    shortPlasmids -->|consumes| polishedContigs
    shortPlasmids -->|outputs| plasmidsFile

    %% Build and Packaging
    buildSystem["src/Makefile"]:::lib
    packaging["setup.py & requirements.txt"]:::lib
    buildSystem -.-> assemblyCpp
    buildSystem -.-> repeatGraphCpp
    buildSystem -.-> contiggerCpp
    buildSystem -.-> polisherCpp
    packaging -.-> pyMain

    %% Click Events
    click binFlye "https://github.com/mikolmogorov/flye/tree/flye/bin/flye"
    click pyMain "https://github.com/mikolmogorov/flye/blob/flye/flye/main.py"
    click configurator "https://github.com/mikolmogorov/flye/blob/flye/flye/config/configurator.py"
    click binCfg "https://github.com/mikolmogorov/flye/tree/flye/flye/config/bin_cfg/"
    click pyCfg "https://github.com/mikolmogorov/flye/blob/flye/flye/config/py_cfg.py"
    click assemblyPy "https://github.com/mikolmogorov/flye/blob/flye/flye/assembly/assemble.py"
    click repeaterInAssembly "https://github.com/mikolmogorov/flye/blob/flye/flye/assembly/repeat_graph.py"
    click scaffolder "https://github.com/mikolmogorov/flye/blob/flye/flye/assembly/scaffolder.py"
    click assemblyCpp "https://github.com/mikolmogorov/flye/blob/flye/src/assemble/main_assemble.cpp"
    click repeatGraphPy "https://github.com/mikolmogorov/flye/blob/flye/flye/repeat_graph/*.py"
    click repeatGraphCpp "https://github.com/mikolmogorov/flye/blob/flye/src/repeat_graph/main_repeat.cpp"
    click contiggerCpp "https://github.com/mikolmogorov/flye/blob/flye/src/contigger/main_contigger.cpp"
    click polishPy "https://github.com/mikolmogorov/flye/blob/flye/flye/polishing/polish.py"
    click polisherCpp "https://github.com/mikolmogorov/flye/blob/flye/src/polishing/main_polisher.cpp"
    click shortPlasmids "https://github.com/mikolmogorov/flye/blob/flye/flye/short_plasmids/*.py"
    click trestle "https://github.com/mikolmogorov/flye/blob/flye/flye/trestle/trestle.py"
    click minimap2 "https://github.com/mikolmogorov/flye/tree/flye/lib/minimap2"
    click samtools "https://github.com/mikolmogorov/flye/blob/flye/lib/samtools-1.9"
    click interval_tree "https://github.com/mikolmogorov/flye/tree/flye/lib/interval_tree"
    click lemon "https://github.com/mikolmogorov/flye/tree/flye/lib/lemon"
    click libcuckoo "https://github.com/mikolmogorov/flye/tree/flye/lib/libcuckoo"
    click buildSystem "https://github.com/mikolmogorov/flye/tree/flye/src/Makefile"
    click packaging "https://github.com/mikolmogorov/flye/blob/flye/setup.py"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#000;
    classDef cpp fill:#90EE90,stroke:#000;
    classDef lib fill:#D3D3D3,stroke:#000;
    classDef file fill:#FFFFFF,stroke:#000;
    classDef python,assemblyPy,configurator,pyMain,binFlye,repeatGraphPy,polishPy,shortPlasmids,trestle python
    class assemblyCpp,repeatGraphCpp,contiggerCpp,polisherCpp cpp
    class minimap2,samtools,interval_tree,lemon,libcuckoo,buildSystem,packaging lib
    class rawReads,corrected,repeatGFA,draftContigs,polishedContigs,plasmidsFile file
```
