# mobiusklein/glycresoft architecture

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

- Interactive diagram: https://gitdiagram.com/mobiusklein/glycresoft
- Repository: https://github.com/mobiusklein/glycresoft

## Overview

##### Project Type and Purpose
- GlycReSoft is an open-source, command-line tool for analyzing glycomics and glycoproteomics LC-MS/MS data.
- It is not a web or full-stack app but a monolithic CLI application/library with native (Cython/C) extensions for performance, data-processing pipelines, and reporting modules.
- Key features: building glycan/glycopeptide search spaces, preprocessing MS data, scoring and matching spectra, serializing and exporting results, and generating reports/plots.

##### File-Structure Analysis
- Top direct­ories:
- src/glycresoft/cli — CLI entrypoints & command dispatch
- src/glycresoft/_c — Cython modules compiled to C for performance (core algorithms: chromatogram, scoring, structure)
- src/glycresoft/database & src/glycresoft/database/builder — Search-space and SQLite/disk-backed DB construction
- src/glycresoft/tandem,-scoring,-structure,-composition_* — Core processing logic: fragmentation modeling, scoring, network modeling
- src/glycresoft/serialize — ORM-style serialization of results to/from DB
- src/glycresoft/output & ‑plotting — Reporting layer: CSV, XML, HTML/templating and plotting utilities
- pyinstaller/ — Packaging scripts to bundle the tool as a standalone executable
- docs/ — Sphinx documentation, custom directives, tutorials, CLI reference
- Configuration/environment: pyproject.toml, setup.py, requirements.txt, external-requirements.txt
- Workflows: GitHub Actions YAML files automate tests, Docker builds, and Python publishing.

##### Key Components
a. CLI Layer
- `glycresoft` entrypoint
- Subcommands: analyze, build-hypothesis, mzml preprocess, export, config, tools
b. Core Pipeline Engine
- Task dispatcher (src/glycresoft/task.py)
- Workflow modules: tandem/workflow, scoring pipelines, elution-time grouping
c. Cython Performance Modules
- src/glycresoft/_c/... for computationally intensive routines (graph algorithms, scoring, structure loading)
d. Database Layer
- Builder classes → populate disk-backed/SQLite DB
- Query interfaces to search spaces (glycan, glycopeptide)
e. Serialization & Configuration
- config module reads/writes user settings
- serialize module bridges Python objects ↔ DB records
f. Reporting & Output
- CSV, XML, text exporters
- HTML templating + JS/CSS for interactive glycan/glycopeptide LC-MS reports
- Plotting utilities for charts and diagnostic figures
g. Packaging & Distribution
- PyInstaller hook scripts → standalone executables
- Dockerfile for containerized usage
h. External Inputs and Outputs
- mzML files, FASTA, mzID, JSON indexes → preprocessed data → analysis → result exports

##### Relationships and Data Flow
- User invokes CLI → CLI parser dispatches to a command module
- Command module invokes the Core Pipeline Engine
- Engine orchestrates:
1. Data ingestion (mzML, FASTA, prebuilt DB files)
2. Search-space building (glycan/glycopeptide DB builder modules)
3. Spectrum matching (tandem & scoring modules leveraging Cython extensions)
4. Elution/time grouping, recalibration
5. Hypothesis generation
6. Serialization of results to DB or in-memory objects
- Reporting layer pulls serialized results → writes CSV/XML/text or renders HTML + JS/CSS
- Plotting layer may be invoked to generate figures
- Config & logging operate throughout

##### Architectural Patterns & Design Principles
- Modular layering: CLI → Orchestration → Core logic → Data layer → Reporting
- Performance offload: Cython modules for hotspots
- Separation of concerns: Database builder separate from scoring, serialization separate from output
- Extensibility: plugin-style hooks in Cython, Sphinx extensions for docs
- Single executable packaging (PyInstaller) vs. library installation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs
    subgraph "External Inputs"
        direction TB
        mzML["mzML, FASTA, mzID, JSON Index"]:::ext
    end

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI["CLI Parser & Entry Point"]:::cli
        Analyze["analyze.py"]:::cli
        BuildDBCLI["build_db.py"]:::cli
        MzMLCLI["mzml.py"]:::cli
        ExportCLI["export.py"]:::cli
        ConfigCLI["config.py"]:::cli
        ToolsCLI["tools.py"]:::cli
    end

    %% Core Pipeline Engine
    subgraph "Core Pipeline Engine"
        direction TB
        Dispatcher["Task Dispatcher"]:::core
        Workflow["Workflow Orchestration"]:::core
    end

    %% Cython Performance Modules
    subgraph "Cython Extensions (Performance)"
        direction TB
        Chromatogram["Chromatogram Algorithms"]:::perf
        Scoring["Scoring & Elution Grouping"]:::perf
        Structure["Structure & Tandem Search"]:::perf
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        Builder["DB Builder Classes"]:::io
        DiskDB["Disk-backed SQLite DB"]:::storage
    end

    %% Serialization & Configuration
    subgraph "Serialization & Configuration"
        direction TB
        Serializer["Serializer (ORM-style)"]:::io
        Config["Configuration Module"]:::io
    end

    %% Reporting & Output
    subgraph "Reporting & Output"
        direction TB
        ReportGen["Report Generators"]:::report
        Exporters["CSV/XML/Text Exporters"]:::report
        Plotting["Plotting Utilities"]:::report
        HTML["HTML/CSS/JS Templates"]:::report
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        direction TB
        PyInstaller["PyInstaller Hooks & Scripts"]:::dist
        Docker["Docker Container"]:::dist
    end

    %% Relationships
    mzML -->|inputs to| CLI
    CLI -->|dispatches to| Dispatcher
    Dispatcher -->|invokes| Workflow
    Workflow -->|calls| Chromatogram
    Workflow -->|calls| Scoring
    Workflow -->|calls| Structure
    Workflow -->|uses| Builder
    Builder -->|populates| DiskDB
    Workflow -->|serializes to| Serializer
    Serializer -->|feeds| ReportGen
    ReportGen -->|uses| Exporters
    ReportGen -->|uses| HTML
    ReportGen -->|invokes| Plotting
    CLI -->|configures via| Config
    CLI -->|packaging| PyInstaller
    CLI -->|container build| Docker

    %% Click Events
    click CLI "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/cli/__main__.py"
    click Analyze "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/cli/analyze.py"
    click BuildDBCLI "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/cli/build_db.py"
    click MzMLCLI "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/cli/mzml.py"
    click ExportCLI "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/cli/export.py"
    click ConfigCLI "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/cli/config.py"
    click ToolsCLI "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/cli/tools.py"
    click Dispatcher "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/task.py"
    click Workflow "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/tandem/workflow.py"
    click Chromatogram "https://github.com/mobiusklein/glycresoft/tree/master/src/glycresoft/_c/chromatogram_tree/"
    click Scoring "https://github.com/mobiusklein/glycresoft/tree/master/src/glycresoft/_c/scoring/"
    click Structure "https://github.com/mobiusklein/glycresoft/tree/master/src/glycresoft/_c/structure/"
    click Builder "https://github.com/mobiusklein/glycresoft/tree/master/src/glycresoft/database/builder/"
    click DiskDB "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/database/disk_backed_database.py"
    click Serializer "https://github.com/mobiusklein/glycresoft/tree/master/src/glycresoft/serialize/"
    click Config "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/config/config_file.py"
    click ReportGen "https://github.com/mobiusklein/glycresoft/tree/master/src/glycresoft/output/report/"
    click Exporters "https://github.com/mobiusklein/glycresoft/blob/master/src/glycresoft/output/csv_format.py"
    click Plotting "https://github.com/mobiusklein/glycresoft/tree/master/src/glycresoft/plotting/"
    click PyInstaller "https://github.com/mobiusklein/glycresoft/tree/master/pyinstaller/"
    click Docker "https://github.com/mobiusklein/glycresoft/tree/master/docker/Dockerfile"

    %% Styles
    classDef cli fill:#e0f7e9,stroke:#2e7d32,stroke-width:2px
    classDef core fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef perf fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef io fill:#f1f8e9,stroke:#558b2f,stroke-width:2px
    classDef storage fill:#ffecb3,stroke:#ffa000,stroke-width:2px
    classDef report fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
    classDef dist fill:#eceff1,stroke:#607d8b,stroke-width:2px
    classDef ext fill:#eeeeee,stroke:#9e9e9e,stroke-width:2px
```
