# mwang87/massquerylanguage architecture

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

- Interactive diagram: https://gitdiagram.com/mwang87/massquerylanguage
- Repository: https://github.com/mwang87/massquerylanguage

## Overview

#### Purpose and Entry Points
MassQL is a Python reference implementation of a mass-spectrometry query DSL: it parses MassQL statements and evaluates them against MS1/MS2 spectral data. Primary entry points are the Python API, notably `massql/msql_engine.py`, and the installed `massql` CLI implemented by `massql/msql_cmd.py`. Package exposure begins at `massql/__init__.py`.

#### Language Definition and Parsing
The language contract is defined by the EBNF grammar in `massql/msql.ebnf`. `massql/msql_parser.py` converts query text into an intermediate structured representation; this is the boundary between user-provided DSL syntax and execution logic. Parsed forms are also supported as JSON-oriented output, consistent with the documented parse API.

#### Query Translation and Execution
`massql/msql_engine.py` orchestrates query processing: accept query text plus an input filename or supplied MS1/MS2 data frames, parse the query, dispatch filtering, and return result data. `massql/msql_translator.py` translates parsed query structures into executable query/filter semantics. The central control flow is:
query string → parser → translated/interpreted clauses → engine evaluation → tabular results.

#### Spectral Data Boundary
`massql/msql_fileloading.py` is the ingestion boundary for mass-spectrometry files and produces separate MS1 and MS2 data frames. The engine can alternatively receive preloaded frames, separating file-format concerns from query evaluation. Representative fixture formats include `tests/test_data/top_down.mgf` and `tests/test_data/top_down.txt`; CLI examples document mzML input.

#### Filter Evaluation
`massql/msql_engine_filters.py` contains the domain-specific predicate layer used during evaluation. It applies MassQL constraints over precursor/product masses, neutral loss, tolerance, intensity, retention time, scan metadata, polarity, charge, and mobility. This layer is the key semantic boundary between generic data-frame operations and mass-spectrometry-aware matching.

#### Extraction and Visualization Outputs
`massql/msql_extract.py` supports extracting query-relevant spectral information from results/data. `massql/msql_visualizer.py` produces MS1/MS2 query visualizations, supporting the documented visualization endpoints. These are downstream consumers of parsed queries and loaded/evaluated spectral data rather than primary execution entry points.

#### Runtime, Packaging, and Integration
The implementation runs on Python (README states Python 3.9 is tested), with dependencies declared in `requirements.txt` and packaging in `setup.py`. GitHub Actions publish and validate the package through `.github/workflows/publish.yml` and test workflows. The README describes Nextflow/ProteoSAFe and hosted web API integration, but the tree contains only Nextflow runtime/cache artifacts under `workflow/.nextflow`; no workflow source or web-server implementation is present here.

Main entry points: [`massql/msql_engine.py`](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_engine.py) (Query engine), [`massql/msql_parser.py`](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_parser.py) (Query parser), [`massql/msql_fileloading.py`](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_fileloading.py) (Spectral file loader), [`massql/msql_engine_filters.py`](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_engine_filters.py) (Mass-spec filters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_package["Package exports<br/>Python package<br/>[__init__.py]"]
  node_python_api["Python API<br/>library entry point<br/>[msql_engine.py]"]
  node_cli["massql CLI<br/>command-line entry point<br/>[msql_cmd.py]"]
end

subgraph group_query["Query Processing"]
  node_grammar["MassQL grammar<br/>EBNF language contract<br/>[msql.ebnf]"]
  node_parser["Query parser<br/>DSL parser<br/>[msql_parser.py]"]
  node_translator["Query translator<br/>query semantics<br/>[msql_translator.py]"]
  node_engine["Query engine<br/>evaluation orchestrator<br/>[msql_engine.py]"]
  node_filters["Mass-spec filters<br/>predicate evaluation"]
end

subgraph group_data["Spectral Data"]
  node_file_loader["Spectral file loader<br/>data ingestion"]
  node_ms1[("MS1 data frame<br/>spectral data")]
  node_ms2[("MS2 data frame<br/>spectral data")]
  node_fixtures["Example spectral files<br/>test fixtures<br/>[top_down.mgf]"]
end

subgraph group_outputs["Outputs"]
  node_results[("Tabular results<br/>query output")]
  node_extract["Spectral extraction<br/>downstream analysis<br/>[msql_extract.py]"]
  node_visualizer["Query visualization<br/>visual output<br/>[msql_visualizer.py]"]
end

node_packaging["Package build<br/>Python packaging<br/>[setup.py]"]
node_dependencies["Dependencies<br/>Python requirements<br/>[requirements.txt]"]

node_package -->|"exposes"| node_python_api
node_packaging -->|"installs"| node_cli
node_dependencies -.->|"runtime dependencies"| node_python_api
node_cli -->|"invokes"| node_engine
node_python_api -->|"evaluates through"| node_engine
node_grammar -->|"defines syntax"| node_parser
node_parser -->|"structured query"| node_translator
node_translator -->|"executable clauses"| node_engine
node_engine -->|"dispatches predicates"| node_filters
node_file_loader -->|"loads"| node_ms1
node_file_loader -->|"loads"| node_ms2
node_fixtures -.->|"example inputs"| node_file_loader
node_ms1 -->|"preloaded input"| node_engine
node_ms2 -->|"preloaded input"| node_engine
node_engine -->|"MS1/MS2 data"| node_filters
node_filters -->|"matched scans"| node_results
node_engine -->|"returns"| node_results
node_parser -.->|"query structure"| node_extract
node_results -->|"matched data"| node_extract
node_parser -.->|"query structure"| node_visualizer
node_results -->|"evaluated spectra"| node_visualizer

click node_package "https://github.com/mwang87/massquerylanguage/blob/master/massql/__init__.py"
click node_python_api "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_engine.py"
click node_cli "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_cmd.py"
click node_grammar "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql.ebnf"
click node_parser "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_parser.py"
click node_translator "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_translator.py"
click node_engine "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_engine.py"
click node_file_loader "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_fileloading.py"
click node_filters "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_engine_filters.py"
click node_extract "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_extract.py"
click node_visualizer "https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_visualizer.py"
click node_packaging "https://github.com/mwang87/massquerylanguage/blob/master/setup.py"
click node_dependencies "https://github.com/mwang87/massquerylanguage/blob/master/requirements.txt"
click node_fixtures "https://github.com/mwang87/massquerylanguage/blob/master/tests/test_data/top_down.mgf"

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_package,node_python_api,node_cli toneBlue
class node_grammar,node_parser,node_translator,node_engine,node_filters toneAmber
class node_file_loader,node_ms1,node_ms2,node_fixtures toneMint
class node_results,node_extract,node_visualizer toneRose
class node_packaging,node_dependencies toneNeutral
```

## Components

### Interfaces

- [Package exports](https://github.com/mwang87/massquerylanguage/blob/master/massql/__init__.py): Python package · Exposes the MassQL library. · `massql/__init__.py`
- [Python API](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_engine.py): library entry point · Programmatic query evaluation interface. · `massql/msql_engine.py`
- [massql CLI](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_cmd.py): command-line entry point · `massql/msql_cmd.py`

### Query Processing

- [MassQL grammar](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql.ebnf): EBNF language contract · `massql/msql.ebnf`
- [Query parser](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_parser.py): DSL parser · Converts query text into structured query forms. · `massql/msql_parser.py`
- [Query translator](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_translator.py): query semantics · Turns parsed clauses into executable filter semantics. · `massql/msql_translator.py`
- [Query engine](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_engine.py): evaluation orchestrator · Coordinates parsing, filtering, and tabular results. · `massql/msql_engine.py`
- [Mass-spec filters](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_engine_filters.py): predicate evaluation · Applies mass, tolerance, intensity, metadata, polarity, charge, and mobility constraints. · `massql/msql_engine_filters.py`

### Spectral Data

- [Spectral file loader](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_fileloading.py): data ingestion · Loads files into separate MS1 and MS2 data frames. · `massql/msql_fileloading.py`
- **MS1 data frame**: spectral data
- **MS2 data frame**: spectral data
- [Example spectral files](https://github.com/mwang87/massquerylanguage/blob/master/tests/test_data/top_down.mgf): test fixtures · Representative MGF and text spectral inputs. · `tests/test_data/top_down.mgf`

### Outputs

- **Tabular results**: query output
- [Spectral extraction](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_extract.py): downstream analysis · `massql/msql_extract.py`
- [Query visualization](https://github.com/mwang87/massquerylanguage/blob/master/massql/msql_visualizer.py): visual output · Produces MS1/MS2 query visualizations. · `massql/msql_visualizer.py`

### Other components

- [Package build](https://github.com/mwang87/massquerylanguage/blob/master/setup.py): Python packaging · Defines installation and CLI distribution. · `setup.py`
- [Dependencies](https://github.com/mwang87/massquerylanguage/blob/master/requirements.txt): Python requirements · `requirements.txt`

## Connections

- Package exports → Python API: exposes
- Package build → massql CLI: installs
- Dependencies → Python API: runtime dependencies
- massql CLI → Query engine: invokes
- Python API → Query engine: evaluates through
- MassQL grammar → Query parser: defines syntax
- Query parser → Query translator: structured query
- Query translator → Query engine: executable clauses
- Query engine → Mass-spec filters: dispatches predicates
- Spectral file loader → MS1 data frame: loads
- Spectral file loader → MS2 data frame: loads
- Example spectral files → Spectral file loader: example inputs
- MS1 data frame → Query engine: preloaded input
- MS2 data frame → Query engine: preloaded input
- Query engine → Mass-spec filters: MS1/MS2 data
- Mass-spec filters → Tabular results: matched scans
- Query engine → Tabular results: returns
- Query parser → Spectral extraction: query structure
- Tabular results → Spectral extraction: matched data
- Query parser → Query visualization: query structure
- Tabular results → Query visualization: evaluated spectra