# whitews/flowkit architecture

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

- Interactive diagram: https://gitdiagram.com/whitews/flowkit
- Repository: https://github.com/whitews/flowkit

## Overview

##### File structure
- Top-level:
- src/flowkit – the entire library code, organized into subpackages
- tests – unit tests covering every module
- docs – Sphinx documentation and tutorial notebooks
- data – example datasets and reference files for testing
- CI/CD config (.github/workflows/*.yml, .readthedocs.yaml)
- In src/flowkit:
- _models – core domain objects (Sample, Session, Workspace, GatingStrategy, GatingResults, dimension, gate_node)
- _models/transforms – transform implementations (logicle, asinh, linear, ratio, etc.)
- _models/gates – gate definitions and parsers (GatingML, WSP)
- _utils – helper functions for gating, XML, plotting, sample I/O
- _resources – XSD schemas for validation and GatingML standard
- exceptions.py – error classes
- _version.py – version metadata

##### README
- Describes features: reading/writing FCS, compensation, transformation, gating, visualization
- Lists external dependencies (flowio, flowutils, numpy, pandas, bokeh, etc.)
- Mentions tutorial notebooks showcasing API usage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        ExternalFlowIO["flowio & flowutils"]:::external
        Sample["Sample Loader"]:::core
        SampleUtils["Sample Utils"]:::utils
        WSPUtils["WSP Utils"]:::utils
    end
    ExternalFlowIO -->|ingest| Sample
    SampleUtils -->|helper| Sample
    WSPUtils -->|helper| Sample
    click Sample "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/sample.py"
    click SampleUtils "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/sample_utils.py"
    click WSPUtils "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/wsp_utils.py"

    %% Core Domain Model
    subgraph "Core Domain Model"
        Session["Session"]:::core
        Workspace["Workspace"]:::core
        GStrategy["GatingStrategy"]:::core
        GateNode["GateNode"]:::core
        GResults["GatingResults"]:::core
        Dimension["Dimension"]:::core
    end
    Sample -->|provides data| Session
    Session --> Workspace
    Workspace --> GStrategy
    GStrategy --> GateNode
    GateNode --> GResults
    Dimension --> GStrategy
    click Session "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/session.py"
    click Workspace "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/workspace.py"
    click GStrategy "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/gating_strategy.py"
    click GateNode "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/gate_node.py"
    click GResults "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/gating_results.py"
    click Dimension "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/dimension.py"

    %% Transforms Module
    subgraph "Transforms Module"
        BaseTransform["BaseTransform"]:::core
        TransformsImpl["Transforms"]:::core
        Matrix["Matrix"]:::core
        WSPTransforms["WSPTransforms"]:::core
    end
    Sample -->|raw events| BaseTransform
    BaseTransform --> TransformsImpl
    TransformsImpl --> Matrix
    TransformsImpl --> WSPTransforms
    BaseTransform --> GStrategy
    click BaseTransform "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/transforms/_base_transform.py"
    click TransformsImpl "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/transforms/_transforms.py"
    click Matrix "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/transforms/_matrix.py"
    click WSPTransforms "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/transforms/_wsp_transforms.py"

    %% Gates Module
    subgraph "Gates Module"
        BaseGate["BaseGate"]:::core
        GatesImpl["Gates"]:::core
        GMLGates["GMLParser"]:::core
        WSPGates["WSPParser"]:::core
    end
    GStrategy --> BaseGate
    BaseGate --> GatesImpl
    GatesImpl --> GMLGates
    GatesImpl --> WSPGates
    GMLGates --> GResults
    WSPGates --> GResults
    click BaseGate "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/gates/_base_gate.py"
    click GatesImpl "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/gates/_gates.py"
    click GMLGates "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/gates/_gml_gates.py"
    click WSPGates "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/gates/_wsp_gates.py"

    %% Export & Persistence
    subgraph "Export & Persistence"
        GMLWriter["GML/XML Writer"]:::utils
        FCSExporter["FCS Exporter"]:::utils
        CSVExporter["CSV/NumPy Export"]:::utils
    end
    GResults --> GMLWriter
    GResults --> FCSExporter
    GResults --> CSVExporter
    Sample --> FCSExporter
    click GMLWriter "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/gml_write.py"
    click FCSExporter "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/sample_utils.py"
    click GResults "https://github.com/whitews/flowkit/blob/master/src/flowkit/_models/gating_results.py"

    %% Visualization
    subgraph "Visualization"
        PlotUtils["Plot Utils (Bokeh)"]:::utils
    end
    Sample --> PlotUtils
    GResults --> PlotUtils
    click PlotUtils "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/plot_utils.py"

    %% Utilities & Resources
    subgraph "Utilities & Resources"
        GatingUtils["gating_utils"]:::utils
        TransformUtils["transform_utils"]:::utils
        XMLUtils["xml_utils"]:::utils
        XMLCommon["xml_common"]:::utils
        XSD1["DataTypes.v2.0.xsd"]:::resources
        XSD2["Gating-ML.v2.0.xsd"]:::resources
        XSD3["Transformations.v2.0.xsd"]:::resources
    end
    click GatingUtils "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/gating_utils.py"
    click TransformUtils "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/transform_utils.py"
    click XMLUtils "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/xml_utils.py"
    click XMLCommon "https://github.com/whitews/flowkit/blob/master/src/flowkit/_utils/xml_common.py"
    click XSD1 "https://github.com/whitews/flowkit/blob/master/src/flowkit/_resources/DataTypes.v2.0.xsd"
    click XSD2 "https://github.com/whitews/flowkit/blob/master/src/flowkit/_resources/Gating-ML.v2.0.xsd"
    click XSD3 "https://github.com/whitews/flowkit/blob/master/src/flowkit/_resources/Transformations.v2.0.xsd"

    %% Exceptions & Metadata
    Exceptions["Exceptions"]:::utils
    Version["Version Metadata"]:::utils
    click Exceptions "https://github.com/whitews/flowkit/blob/master/src/flowkit/exceptions.py"
    click Version "https://github.com/whitews/flowkit/blob/master/src/flowkit/_version.py"

    %% Infra: Tests, CI/CD, Docs
    subgraph "Infrastructure"
        Tests["Tests/ Unit Tests"]:::infra
        CI["CI/CD Pipelines"]:::infra
        Docs["Documentation & Tutorials"]:::infra
    end
    click Tests "https://github.com/whitews/flowkit/tree/master/tests/"
    click CI "https://github.com/whitews/flowkit/tree/master/.github/workflows/"
    click Docs "https://github.com/whitews/flowkit/tree/master/docs/"

    %% Data Flows
    Sample --> BaseTransform
    BaseTransform --> GResults
    GResults --> CSVExporter
    GResults --> PlotUtils

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9,color:#1B4F72;
    classDef utils fill:#D5F5E3,stroke:#27AE60,color:#1E8449;
    classDef external fill:#FAD7A0,stroke:#EB984E,color:#935116;
    classDef resources fill:#E8DAEF,stroke:#A569BD,color:#4A235A;
    classDef infra fill:#F2F3F4,stroke:#ABB2B9,color:#2C3E50;
```
