# broadinstitute/delphy architecture

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

- Interactive diagram: https://gitdiagram.com/broadinstitute/delphy
- Repository: https://github.com/broadinstitute/delphy

## Overview

##### Main System Components

a) Core Engine Layer:
- Subdivide into these key modules (based on the core/ directory):
- Phylogenetic Tree Management (phylo_tree.h, tree.h)
- Evolution Models (evo_model.h, evo_hky.h)
- Coalescent Processing (coalescent.h, scalable_coalescent.h)
- Input/Output Handling (io.h, api.h)

b) Interface Layer:
- Multiple entry points:
- Command-line interface (tools/delphy.cpp)
- UI interface (tools/delphy_ui.cpp)
- WebAssembly interface (tools/delphy_wasm.cpp)

c) External Dependencies:
- Third-party components (from third-party/):
- abseil-cpp
- cppcoro
- flatbuffers
- cxxopts

##### Data Flow and Interactions

- Input flow: Show how data enters through different interfaces
- Processing flow: Illustrate how data moves through the core engine
- Output flow: Show how results are returned to users

##### Specific Components to Highlight

a) EMAT (Explicit Mutation-Annotated Trees) Processing:
- Mutation annotation handling (mutations.h)
- Tree probing mechanisms (tree_prober.h)
- Site state management (site_states_tree_prober.h)

b) Algorithmic Components:
- Relationship between:
- SPR (Subtree Pruning and Regrafting) operations (spr_move.h, spr_study.h)
- Coalescent calculations (scalable_coalescent.h, very_scalable_coalescent.h)
- Phylogenetic tree calculations (phylo_tree_calc.h)

##### Technical Details

Annotations for:
- File formats supported
- Key algorithms implemented
- Performance optimization points
- Scaling capabilities

- The modular nature of the core engine
- The multiple interface options
- The separation between computational and I/O components
- The relationship with external tools like UShER

Keep the abstraction level focused on the architectural components while providing enough detail to understand the unique aspects of Delphy's EMAT-based approach and its scaling capabilities for genomic epidemiology datasets.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Core_Engine
        direction TB
        subgraph PhyloTreeMgmt["Phylogenetic Tree Management"]
            direction TB
            PTM1["Tree Management"]:::core
            PTM2["Tree Editing"]:::core
        end
        
        subgraph EvoModels["Evolution Models"]
            direction TB
            EVO1["Evolution Model Base"]:::core
            EVO2["HKY Model"]:::core
        end
        
        subgraph Coalescent["Coalescent Processing"]
            direction TB
            COA1["Base Coalescent"]:::core
            COA2["Scalable Coalescent"]:::core
            COA3["Very Scalable Coalescent"]:::core
        end
        
        subgraph IO["Input/Output Handling"]
            direction TB
            IO1["I/O Core"]:::io
            IO2["API Handler"]:::io
            IO3["BEAST Input"]:::io
            IO4["BEAST Output"]:::io
        end
        
        subgraph EMAT["EMAT Processing"]
            direction TB
            EMAT1["Mutation Annotation"]:::core
            EMAT2["Tree Probing"]:::core
            EMAT3["Site State Management"]:::core
        end
        
        subgraph SPR["SPR Operations"]
            direction TB
            SPR1["SPR Move"]:::core
            SPR2["SPR Study"]:::core
        end
        
        subgraph PhyloCalc["Phylogenetic Calculations"]
            direction TB
            PC1["Tree Calculations"]:::core
        end
        
        subgraph TreeAnalysis["Tree Analysis"]
            direction TB
            TA1["Ancestral Probing"]:::core
            TA2["MCC Tree"]:::core
            TA3["Incremental MCC"]:::core
        end
    end
    
    subgraph Interface
        direction TB
        CLI["Command Line Interface"]:::interface
        UI["UI Interface"]:::interface
        WASM["WebAssembly Interface"]:::interface
    end
    
    subgraph Dependencies
        direction TB
        DEP1["abseil-cpp"]:::external
        DEP2["cppcoro"]:::external
        DEP3["flatbuffers"]:::external
        DEP4["cxxopts"]:::external
    end
    
    %% Connections
    Interface --> IO
    IO --> PhyloTreeMgmt
    PhyloTreeMgmt --> EvoModels
    PhyloTreeMgmt --> Coalescent
    PhyloTreeMgmt --> EMAT
    EMAT --> SPR
    SPR --> PhyloCalc
    PhyloCalc --> TreeAnalysis
    
    %% Click events
    click PTM1 "https://github.com/broadinstitute/delphy/blob/main/core/phylo_tree.h"
    click PTM2 "https://github.com/broadinstitute/delphy/blob/main/core/tree_editing.h"
    click EVO1 "https://github.com/broadinstitute/delphy/blob/main/core/evo_model.h"
    click EVO2 "https://github.com/broadinstitute/delphy/blob/main/core/evo_hky.h"
    click COA1 "https://github.com/broadinstitute/delphy/blob/main/core/coalescent.h"
    click COA2 "https://github.com/broadinstitute/delphy/blob/main/core/scalable_coalescent.h"
    click COA3 "https://github.com/broadinstitute/delphy/blob/main/core/very_scalable_coalescent.h"
    click IO1 "https://github.com/broadinstitute/delphy/blob/main/core/io.h"
    click IO2 "https://github.com/broadinstitute/delphy/blob/main/core/api.h"
    click IO3 "https://github.com/broadinstitute/delphy/blob/main/core/beasty_input.h"
    click IO4 "https://github.com/broadinstitute/delphy/blob/main/core/beasty_output.h"
    click EMAT1 "https://github.com/broadinstitute/delphy/blob/main/core/mutations.h"
    click EMAT2 "https://github.com/broadinstitute/delphy/blob/main/core/tree_prober.h"
    click EMAT3 "https://github.com/broadinstitute/delphy/blob/main/core/site_states_tree_prober.h"
    click SPR1 "https://github.com/broadinstitute/delphy/blob/main/core/spr_move.h"
    click SPR2 "https://github.com/broadinstitute/delphy/blob/main/core/spr_study.h"
    click PC1 "https://github.com/broadinstitute/delphy/blob/main/core/phylo_tree_calc.h"
    click TA1 "https://github.com/broadinstitute/delphy/blob/main/core/ancestral_tree_prober.h"
    click TA2 "https://github.com/broadinstitute/delphy/blob/main/core/mcc_tree.h"
    click TA3 "https://github.com/broadinstitute/delphy/blob/main/core/incremental_mcc_tree.h"
    click CLI "https://github.com/broadinstitute/delphy/blob/main/tools/delphy.cpp"
    click UI "https://github.com/broadinstitute/delphy/blob/main/tools/delphy_ui.cpp"
    click WASM "https://github.com/broadinstitute/delphy/blob/main/tools/delphy_wasm.cpp"
    click DEP1 "https://github.com/broadinstitute/delphy/tree/main/third-party/abseil-cpp"
    click DEP2 "https://github.com/broadinstitute/delphy/tree/main/third-party/cppcoro"
    click DEP3 "https://github.com/broadinstitute/delphy/tree/main/third-party/flatbuffers"
    click DEP4 "https://github.com/broadinstitute/delphy/tree/main/third-party/cxxopts"
    
    %% Styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef interface fill:#4CAF50,stroke:#2E7D32,color:white
    classDef external fill:#FFC107,stroke:#FFA000,color:black
    classDef io fill:#FF5722,stroke:#E64A19,color:white
```
