# plutzer/proximate architecture

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

- Interactive diagram: https://gitdiagram.com/plutzer/proximate
- Repository: https://github.com/plutzer/proximate

## Overview

ProxiMate is a GUI and command-line toolkit for analyzing proximity-labeling experiments. Users provide experimental-design and quantitative files (or SAINT-format inputs); parsing and preprocessing feed interaction scoring, annotation, and result artifacts. The GUI and MCP endpoint share a server process and dataset/session state, letting users inspect datasets, quality-control plots, enrichment, and networks; Cytoscape is an optional desktop integration. The README documents additional input formats, imputation methods, provenance, and network-analysis capabilities. Pipeline links reflect README-documented stages; unsampled implementation details are not inferred.

Main entry points: [`GUI/backend.py`](https://github.com/plutzer/proximate/blob/main/GUI/backend.py) (Analysis Backend), [`GUI/app.py`](https://github.com/plutzer/proximate/blob/main/GUI/app.py) (Shiny App), [`GUI/mcp_tools.py`](https://github.com/plutzer/proximate/blob/main/GUI/mcp_tools.py) (MCP Tools), [`GUI/server.py`](https://github.com/plutzer/proximate/blob/main/GUI/server.py) (Web GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_gui_server["Web GUI<br/>[server.py]"]
  node_gui_app["Shiny App<br/>[app.py]"]
  node_mcp_tools["MCP Tools<br/>[mcp_tools.py]"]
  node_mcp_registry["MCP Operations<br/>[mcp_registry.py]"]
end

subgraph group_analysis["Analysis Pipeline"]
  node_backend["Analysis Backend<br/>[backend.py]"]
  node_parse["Input Parsing<br/>[parse.py]"]
  node_preprocess["Preprocessing<br/>[protein_groups.py]"]
  node_experimental_design["Design Validation"]
  node_imputation["AFT Imputation<br/>[refactored_aft.py]"]
  node_score["Interaction Scoring<br/>[score.py]"]
  node_saint["SAINT Model<br/>[main.cpp]"]
  node_annotate["Score Annotation<br/>[annotator.py]"]
end

subgraph group_results["Results and Exploration"]
  node_qc["QC Plots<br/>[QC_plots.py]"]
  node_enrichment["Feature Enrichment<br/>[Ann_Enrichment.py]"]
  node_network["Network Comparison"]
end

subgraph group_integrations["External Integrations"]
  node_cytoscape_ctl["Cytoscape Controller<br/>[cytoscape_ctl.py]"]
  node_cytoscape_api["Cytoscape Client<br/>[cytoscape_p4c.py]"]
end

subgraph group_operations["Session Operations"]
  node_datasets[("Dataset Store<br/>[dataset_store.py]")]
  node_provenance["Run Provenance<br/>[provenance.py]"]
  node_archive["Session Archive<br/>[session_archive.py]"]
  node_outputs["Run Artifacts"]
end

node_user(("Researcher"))
node_agent(("MCP Agent"))
node_input_data["Experiment Files"]
node_cytoscape(("Cytoscape Desktop"))

node_user -->|"opens GUI"| node_gui_server
node_agent -->|"calls MCP"| node_gui_server
node_gui_server -->|"starts GUI"| node_gui_app
node_gui_server -->|"registers tools"| node_mcp_tools
node_gui_app -->|"uses backend"| node_backend
node_mcp_tools -->|"dispatches requests"| node_backend
node_mcp_tools -->|"queries operations"| node_mcp_registry
node_gui_app -->|"reads and updates"| node_datasets
node_mcp_tools -->|"reads datasets"| node_datasets
node_user -->|"provides"| node_input_data
node_input_data -->|"selects for analysis"| node_backend
node_backend -->|"validates design"| node_experimental_design
node_backend -->|"runs parsing"| node_parse
node_backend -->|"runs preprocessing"| node_preprocess
node_backend -->|"runs imputation"| node_imputation
node_backend -->|"runs scoring"| node_score
node_backend -.->|"runs SAINT"| node_saint
node_backend -->|"runs annotation"| node_annotate
node_backend -->|"records run"| node_provenance
node_parse -->|"writes parsed data"| node_outputs
node_score -->|"writes scores"| node_outputs
node_annotate -->|"writes annotations"| node_outputs
node_provenance -->|"writes manifest"| node_outputs
node_gui_app -->|"renders QC"| node_qc
node_gui_app -->|"renders enrichment"| node_enrichment
node_gui_app -->|"compares networks"| node_network
node_gui_app -->|"controls network tab"| node_cytoscape_ctl
node_mcp_tools -->|"dispatches network tools"| node_cytoscape_ctl
node_cytoscape_ctl -->|"sends CyREST requests"| node_cytoscape_api
node_cytoscape_api -->|"updates and queries"| node_cytoscape
node_gui_app -->|"manages archives"| node_archive
node_archive -->|"archives session data"| node_datasets

click node_gui_server "https://github.com/plutzer/proximate/blob/main/GUI/server.py"
click node_gui_app "https://github.com/plutzer/proximate/blob/main/GUI/app.py"
click node_mcp_tools "https://github.com/plutzer/proximate/blob/main/GUI/mcp_tools.py"
click node_mcp_registry "https://github.com/plutzer/proximate/blob/main/GUI/mcp_registry.py"
click node_backend "https://github.com/plutzer/proximate/blob/main/GUI/backend.py"
click node_datasets "https://github.com/plutzer/proximate/blob/main/GUI/dataset_store.py"
click node_parse "https://github.com/plutzer/proximate/blob/main/Scripts/parse.py"
click node_preprocess "https://github.com/plutzer/proximate/blob/main/Scripts/protein_groups.py"
click node_experimental_design "https://github.com/plutzer/proximate/blob/main/Scripts/experimental_design.py"
click node_imputation "https://github.com/plutzer/proximate/blob/main/Scripts/refactored_aft.py"
click node_score "https://github.com/plutzer/proximate/blob/main/Scripts/score.py"
click node_saint "https://github.com/plutzer/proximate/blob/main/saint/patches/SAINT-MRF-int/main.cpp"
click node_annotate "https://github.com/plutzer/proximate/blob/main/Scripts/annotator.py"
click node_provenance "https://github.com/plutzer/proximate/blob/main/Scripts/provenance.py"
click node_qc "https://github.com/plutzer/proximate/blob/main/GUI/QC_plots.py"
click node_enrichment "https://github.com/plutzer/proximate/blob/main/GUI/Ann_Enrichment.py"
click node_network "https://github.com/plutzer/proximate/blob/main/GUI/network_comparison.py"
click node_cytoscape_ctl "https://github.com/plutzer/proximate/blob/main/GUI/cytoscape_ctl.py"
click node_cytoscape_api "https://github.com/plutzer/proximate/blob/main/GUI/cytoscape_p4c.py"
click node_archive "https://github.com/plutzer/proximate/blob/main/GUI/session_archive.py"

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_gui_server,node_gui_app,node_mcp_tools,node_mcp_registry toneBlue
class node_backend,node_parse,node_preprocess,node_experimental_design,node_imputation,node_score,node_saint,node_annotate toneAmber
class node_qc,node_enrichment,node_network toneMint
class node_cytoscape_ctl,node_cytoscape_api toneRose
class node_datasets,node_provenance,node_archive,node_outputs,node_user,node_agent,node_input_data,node_cytoscape toneIndigo
```

## Components

### User Interfaces

- [Web GUI](https://github.com/plutzer/proximate/blob/main/GUI/server.py): `GUI/server.py`
- [Shiny App](https://github.com/plutzer/proximate/blob/main/GUI/app.py): `GUI/app.py`
- [MCP Tools](https://github.com/plutzer/proximate/blob/main/GUI/mcp_tools.py): `GUI/mcp_tools.py`
- [MCP Operations](https://github.com/plutzer/proximate/blob/main/GUI/mcp_registry.py): `GUI/mcp_registry.py`

### Analysis Pipeline

- [Analysis Backend](https://github.com/plutzer/proximate/blob/main/GUI/backend.py): `GUI/backend.py`
- [Input Parsing](https://github.com/plutzer/proximate/blob/main/Scripts/parse.py): `Scripts/parse.py`
- [Preprocessing](https://github.com/plutzer/proximate/blob/main/Scripts/protein_groups.py): `Scripts/protein_groups.py`
- [Design Validation](https://github.com/plutzer/proximate/blob/main/Scripts/experimental_design.py): `Scripts/experimental_design.py`
- [AFT Imputation](https://github.com/plutzer/proximate/blob/main/Scripts/refactored_aft.py): `Scripts/refactored_aft.py`
- [Interaction Scoring](https://github.com/plutzer/proximate/blob/main/Scripts/score.py): `Scripts/score.py`
- [SAINT Model](https://github.com/plutzer/proximate/blob/main/saint/patches/SAINT-MRF-int/main.cpp): `saint/patches/SAINT-MRF-int/main.cpp`
- [Score Annotation](https://github.com/plutzer/proximate/blob/main/Scripts/annotator.py): `Scripts/annotator.py`

### Results and Exploration

- [QC Plots](https://github.com/plutzer/proximate/blob/main/GUI/QC_plots.py): `GUI/QC_plots.py`
- [Feature Enrichment](https://github.com/plutzer/proximate/blob/main/GUI/Ann_Enrichment.py): `GUI/Ann_Enrichment.py`
- [Network Comparison](https://github.com/plutzer/proximate/blob/main/GUI/network_comparison.py): `GUI/network_comparison.py`

### External Integrations

- [Cytoscape Controller](https://github.com/plutzer/proximate/blob/main/GUI/cytoscape_ctl.py): `GUI/cytoscape_ctl.py`
- [Cytoscape Client](https://github.com/plutzer/proximate/blob/main/GUI/cytoscape_p4c.py): `GUI/cytoscape_p4c.py`

### Session Operations

- [Dataset Store](https://github.com/plutzer/proximate/blob/main/GUI/dataset_store.py): `GUI/dataset_store.py`
- [Run Provenance](https://github.com/plutzer/proximate/blob/main/Scripts/provenance.py): `Scripts/provenance.py`
- [Session Archive](https://github.com/plutzer/proximate/blob/main/GUI/session_archive.py): `GUI/session_archive.py`
- **Run Artifacts**

### Other components

- **Researcher**
- **MCP Agent**
- **Experiment Files**
- **Cytoscape Desktop**

## Connections

- Researcher → Web GUI: opens GUI
- MCP Agent → Web GUI: calls MCP
- Web GUI → Shiny App: starts GUI
- Web GUI → MCP Tools: registers tools
- Shiny App → Analysis Backend: uses backend
- MCP Tools → Analysis Backend: dispatches requests
- MCP Tools → MCP Operations: queries operations
- Shiny App → Dataset Store: reads and updates
- MCP Tools → Dataset Store: reads datasets
- Researcher → Experiment Files: provides
- Experiment Files → Analysis Backend: selects for analysis
- Analysis Backend → Design Validation: validates design
- Analysis Backend → Input Parsing: runs parsing
- Analysis Backend → Preprocessing: runs preprocessing
- Analysis Backend → AFT Imputation: runs imputation
- Analysis Backend → Interaction Scoring: runs scoring
- Analysis Backend → SAINT Model: runs SAINT
- Analysis Backend → Score Annotation: runs annotation
- Analysis Backend → Run Provenance: records run
- Input Parsing → Run Artifacts: writes parsed data
- Interaction Scoring → Run Artifacts: writes scores
- Score Annotation → Run Artifacts: writes annotations
- Run Provenance → Run Artifacts: writes manifest
- Shiny App → QC Plots: renders QC
- Shiny App → Feature Enrichment: renders enrichment
- Shiny App → Network Comparison: compares networks
- Shiny App → Cytoscape Controller: controls network tab
- MCP Tools → Cytoscape Controller: dispatches network tools
- Cytoscape Controller → Cytoscape Client: sends CyREST requests
- Cytoscape Client → Cytoscape Desktop: updates and queries
- Shiny App → Session Archive: manages archives
- Session Archive → Dataset Store: archives session data