# zamboni-lab/masster-dist architecture

> Architecture diagram of the GitHub repository zamboni-lab/masster-dist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zamboni-lab/masster-dist
- Repository: https://github.com/zamboni-lab/masster-dist

## Overview

1. **What this repository is**
   - The repo is primarily a public distribution and documentation wrapper for MASSter, not a full source tree in this checkout.
   - The visible files are license and notices; the README describes the product architecture and release model.

2. **Overall shape: local, file-based LC–MS/MS analysis**
   - MASSter is a Python package for processing metabolomics LC–MS/MS studies on a single machine or workstation cluster.
   - The central unit of work is a **Study**, which contains multiple **Samples**; processing produces persistent result files rather than relying on a server or database.

3. **Primary user entry points**
   - The package is intended to be driven by **scripts** for reproducible batch processing.
   - There is an integrated **Wizard** that automates a typical end-to-end run from raw files to a study workflow.
   - For post-processing exploration, users open the saved study in **Jupyter** or **Marimo**, and there is also a browser **dashboard** for interactive review after processing.

4. **Data ingestion boundary**
   - MASSter can read either vendor raw formats or open formats like **mzML/mz5**.
   - Vendor-format access depends on **.NET via pythonnet** and is therefore limited to **Windows** in the full version.
   - On Linux/macOS, the practical input boundary is mzML/mz5; the README recommends mz5 for large DIA data.

5. **Core analytical pipeline**
   - The product covers the stages that follow raw ingestion: **centroiding, feature detection, RT alignment, adduct/isotopomer detection, sample merging, gap filling, quantification, MS2 spectrum selection, visualization, and export**.
   - The README states feature detection still relies on **OpenMS**, while MASSter redesigns the rest of the pipeline around it.

6. **Processing model and reuse of intermediate results**
   - Samples are processed individually and cached as reusable artifacts, then assembled into a study-level result.
   - This two-level model suggests a boundary between **sample processing** and **study assembly**, which is important for both scalability and troubleshooting.

7. **Performance and scaling architecture**
   - The implementation is optimized for large studies using **Polars**, **NumPy vectorization**, **multiprocessing**, and **chunking**.
   - MASSter avoids loading all data at once; it reads only the relevant fractions of raw data, which is especially important for DIA/ZTScan files and large studies.

8. **Persistence and portability**
   - Results are stored in MASSter’s own **HDF5-based formats**: `.sample5` and `.study5`.
   - This format is designed to be portable across operating systems and Python versions, making analysis outputs the durable handoff between processing and interactive review.

9. **Outputs and downstream exchange**
   - The tool exports to standard metabolomics formats such as **mzTab-M**, **MGF**, and **parquet**.
   - This makes MASSter both a processing engine and a conversion layer for downstream tools and reporting workflows.

10. **Runtime and platform constraints**
   - The supported Python range is **3.11–3.13**.
   - The full version is Windows-only for proprietary raw access; the light version is cross-platform and focuses on reading, visualizing, filtering, and exporting existing MASSter results.

11. **Distribution model**
   - The project publishes a **PEP 503-compatible package index** for installation via `uv` or `pip`.
   - The repository therefore acts partly as a release channel, not just a code repository, and installation is expected to happen from the hosted package index.

12. **System boundaries to draw in an architecture diagram**
   - A good diagram would show: raw/vendor or mzML/mz5 files in, sample-level processing, study assembly, persisted HDF5 result files, and then notebook/dashboard/export consumers.
   - External boundaries to annotate: OpenMS for feature detection, .NET/pythonnet for vendor raw access, and the GitHub-hosted package index/wiki for distribution and documentation.

Main entry points: [`README.md`](https://github.com/zamboni-lab/masster-dist/blob/main/README.md) (README), [`LICENSE`](https://github.com/zamboni-lab/masster-dist/tree/main/LICENSE) (License), [`THIRD_PARTY_NOTICES.md`](https://github.com/zamboni-lab/masster-dist/blob/main/THIRD_PARTY_NOTICES.md) (Notices)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_distribution["Distribution & docs"]
  node_repo["masster-dist<br/>release wrapper"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_license["License<br/>legal"]
  node_notices["Notices"]
  node_pkgindex[("Package index<br/>distribution channel")]
end

subgraph group_runtime["Processing runtime"]
  node_scripts["Scripts<br/>batch entrypoints"]
  node_wizard["Wizard<br/>guided workflow"]
  node_rawin[("Raw files<br/>input data")]
  node_openfmt[("mzML/mz5<br/>open input")]
  node_sample["Sample processing<br/>per-sample pipeline"]
  node_study["Study assembly<br/>study-level aggregation"]
  node_persist[("HDF5 results<br/>persistent artifacts")]
end

subgraph group_consumers["Review & exchange"]
  node_notebook["Notebooks<br/>interactive review"]
  node_dashboard["Dashboard<br/>browser review"]
  node_exports["Exports<br/>exchange formats"]
end

subgraph group_externals["External dependencies"]
  node_vendor["Vendor access<br/>.NET/pythonnet boundary"]
  node_openms["OpenMS<br/>feature detection engine"]
  node_stack{{"Polars stack<br/>performance layer"}}
end

node_repo -->|"documents"| node_readme
node_repo -->|"includes"| node_license
node_repo -->|"includes"| node_notices
node_repo -->|"publishes"| node_pkgindex
node_scripts -->|"orchestrates"| node_wizard
node_wizard -->|"starts from"| node_rawin
node_rawin -->|"via"| node_vendor
node_rawin -->|"or"| node_openfmt
node_openfmt -->|"feeds"| node_sample
node_vendor -->|"feeds"| node_sample
node_sample -->|"uses"| node_openms
node_sample -->|"accelerated by"| node_stack
node_sample -->|"writes"| node_persist
node_persist -->|"assembled into"| node_study
node_study -->|"saved as"| node_persist
node_study -->|"opened in"| node_notebook
node_study -->|"viewed in"| node_dashboard
node_study -->|"exported to"| node_exports

click node_readme "https://github.com/zamboni-lab/masster-dist/blob/main/README.md"
click node_license "https://github.com/zamboni-lab/masster-dist/tree/main/LICENSE"
click node_notices "https://github.com/zamboni-lab/masster-dist/blob/main/THIRD_PARTY_NOTICES.md"

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_repo,node_readme,node_license,node_notices,node_pkgindex toneBlue
class node_scripts,node_wizard,node_rawin,node_openfmt,node_sample,node_study,node_persist toneAmber
class node_notebook,node_dashboard,node_exports toneMint
class node_vendor,node_openms,node_stack toneRose
```

## Components

### Distribution & docs

Public release wrapper, documentation, and notices in this checkout.

- **masster-dist**: release wrapper · This checkout is primarily a public distribution and documentation wrapper for MASSter.
- [README](https://github.com/zamboni-lab/masster-dist/blob/main/README.md): docs · Explains the product architecture, release model, supported platforms, and workflows. · `README.md`
- [License](https://github.com/zamboni-lab/masster-dist/tree/main/LICENSE): legal · Repository license text. · `LICENSE`
- [Notices](https://github.com/zamboni-lab/masster-dist/blob/main/THIRD_PARTY_NOTICES.md): third-party notices · Third-party licensing and attribution information. · `THIRD_PARTY_NOTICES.md`
- **Package index**: distribution channel · PEP 503-compatible package index used for installation via pip or uv.

### Processing runtime

Core analytical flow from raw input to persisted study results.

- **Scripts**: batch entrypoints · Reproducible script-driven runs for automated processing.
- **Wizard**: guided workflow · Automates a typical end-to-end run from raw files to a study workflow.
- **Raw files**: input data · Vendor raw formats or open mzML/mz5 inputs.
- **mzML/mz5**: open input · Cross-platform input path for open formats; mz5 is recommended for large DIA data.
- **Sample processing**: per-sample pipeline · Cached sample-level processing that extracts reusable intermediate artifacts.
- **Study assembly**: study-level aggregation · Combines processed samples into a study-level result and coordinates downstream analysis.
- **HDF5 results**: persistent artifacts · Portable .sample5 and .study5 outputs used as durable handoff files.

### Review & exchange

Interactive and export consumers of persisted MASSter results.

- **Notebooks**: interactive review · Jupyter or Marimo exploration of saved studies after processing.
- **Dashboard**: browser review · Interactive browser-based review of processed results.
- **Exports**: exchange formats · mzTab-M, MGF, and parquet export targets for downstream tools and reporting.

### External dependencies

Key third-party and platform boundaries called out by the repository.

- **Vendor access**: .NET/pythonnet boundary · Vendor-format access path that depends on .NET via pythonnet and is Windows-only in the full version.
- **OpenMS**: feature detection engine · Third-party feature detection dependency used within the pipeline.
- **Polars stack**: performance layer · Vectorized, chunked, multiprocessing-heavy execution model for large studies.

## Connections

- masster-dist → README: documents · The wrapper repository is primarily explained through the README.
- masster-dist → License: includes · License is part of the public distribution.
- masster-dist → Notices: includes · Third-party attributions accompany the distribution.
- masster-dist → Package index: publishes · The repo acts partly as a release channel for installation.
- Scripts → Wizard: orchestrates · Scripted runs and the wizard are the main entry points.
- Wizard → Raw files: starts from · Wizard drives processing from raw input files.
- Raw files → Vendor access: via · Vendor raw access routes through the .NET/pythonnet boundary.
- Raw files → mzML/mz5: or · Open formats are the cross-platform input path.
- mzML/mz5 → Sample processing: feeds · Open input data enters sample-level processing.
- Vendor access → Sample processing: feeds · Vendor raw data enters the same processing pipeline when supported.
- Sample processing → OpenMS: uses · Feature detection relies on OpenMS.
- Sample processing → Polars stack: accelerated by · Processing is optimized with Polars, vectorization, chunking, and multiprocessing.
- Sample processing → HDF5 results: writes · Per-sample outputs are cached as reusable HDF5 artifacts.
- HDF5 results → Study assembly: assembled into · Cached samples are combined into a study-level result.
- Study assembly → HDF5 results: saved as · The study result is persisted as a durable .study5 artifact.
- Study assembly → Notebooks: opened in · Saved studies are explored interactively in notebooks.
- Study assembly → Dashboard: viewed in · Processed results can be reviewed in a browser dashboard.
- Study assembly → Exports: exported to · Study outputs are converted to standard exchange formats.
