# mrmma2004/pharma-ml-toolkit architecture

> Architecture diagram of the GitHub repository mrmma2004/pharma-ml-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrmma2004/pharma-ml-toolkit
- Repository: https://github.com/mrmma2004/pharma-ml-toolkit

## Overview

PharmaML is a local-first toolkit for cheminformatics, QSAR, docking, PK/PD, biological-response analysis and visualization, with Python, desktop and web interfaces. The documented research workflow runs from data review and split design through training, independent evaluation and reporting. The graph also includes the separate web console’s sampled ML API/model layer and the Python Studio pipeline/server. README claims establish broad product capabilities; unsampled implementations are represented only at supported directory paths, and their internal connections are not inferred.

Main entry points: [`pharma-ml-toolkit/src/pharmaml`](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml) (Python API and CLI), [`pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/studio/pipelines.py) (Sequential workflow pipelines), [`src/app/api/ml`](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/src/app/api/ml) (ML API routes), [`pharma-ml-toolkit/src/pharmaml/api/server.py`](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/server.py) (Loopback API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_python["Python API and CLI"]
  node_desktop["Studio desktop<br/>[studio.py]"]
  node_web["Web console"]
end

subgraph group_data["Data and chemistry"]
  node_dataset["Data loading and splitting<br/>[data.py]"]
  node_descriptors["Descriptors and fingerprints<br/>[descriptors.py]"]
end

subgraph group_research["Research workflows"]
  node_qsar["QSAR training and evaluation"]
  node_biology["Biological response"]
  node_docking["Docking preparation and campaigns"]
  node_pkpd["PK and PD"]
  node_generative["Molecule generation<br/>[genetic.py]"]
  node_md["Molecular dynamics analysis"]
  node_visualization["Visualization and reports"]
  node_pipelines["Sequential workflow pipelines<br/>[pipelines.py]"]
end

subgraph group_platform["API and persistence"]
  node_api["Loopback API server<br/>[server.py]"]
  node_events["Events and jobs<br/>[events.py]"]
  node_persistence["Run persistence<br/>[persistence.py]"]
  node_stores[("API stores<br/>[stores.py]")]
  node_exceptions["Toolkit errors<br/>[exceptions.py]"]
end

subgraph group_webml["Web ML"]
  node_web_routes["ML API routes"]
  node_csv["CSV parsing and resolution<br/>[csv.ts]"]
  node_models["Model registry<br/>[ml-models.ts]"]
  node_math["ML algorithms and metrics<br/>[ml-math.ts]"]
  node_types["Shared API types<br/>[toolkit-types.ts]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs analyses"| node_python
node_researcher -->|"uses workflows"| node_desktop
node_researcher -->|"explores projects"| node_web
node_python -->|"inspects data"| node_dataset
node_python -->|"models compounds"| node_qsar
node_python -->|"computes features"| node_descriptors
node_python -->|"analyzes response"| node_biology
node_python -->|"runs docking"| node_docking
node_python -->|"calculates PK/PD"| node_pkpd
node_python -->|"explores generation"| node_generative
node_python -->|"analyzes trajectories"| node_md
node_python -->|"plots and reports"| node_visualization
node_dataset -->|"loads dataset"| node_pipelines
node_pipelines -->|"computes descriptors"| node_descriptors
node_pipelines -->|"trains models"| node_qsar
node_pipelines -->|"runs analysis"| node_biology
node_pipelines -->|"runs generation"| node_generative
node_pipelines -->|"prepares ligands"| node_docking
node_pipelines -->|"runs PK analysis"| node_pkpd
node_pipelines -->|"analyzes trajectory"| node_md
node_pipelines -->|"creates reports"| node_visualization
node_desktop -.->|"starts server"| node_api
node_api -->|"publishes events"| node_events
node_api -->|"gets data directory"| node_persistence
node_persistence -->|"uses stores"| node_stores
node_api -->|"exposes errors"| node_exceptions
node_web -.->|"requests ML tools"| node_web_routes
node_web_routes -->|"parses CSV"| node_csv
node_web_routes -->|"resolves models"| node_models
node_web_routes -->|"fits and scores"| node_math
node_models -->|"calls algorithms"| node_math
node_web_routes -->|"uses API types"| node_types

click node_python "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml"
click node_desktop "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/studio.py"
click node_web "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/frontend/src"
click node_dataset "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/data.py"
click node_descriptors "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/chem/descriptors.py"
click node_qsar "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/ml"
click node_biology "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/biology"
click node_docking "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/docking"
click node_pkpd "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/pharma"
click node_generative "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/generative/genetic.py"
click node_md "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/md"
click node_visualization "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/viz"
click node_pipelines "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/studio/pipelines.py"
click node_api "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/server.py"
click node_events "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/events.py"
click node_persistence "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/persistence.py"
click node_stores "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/stores.py"
click node_exceptions "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/exceptions.py"
click node_web_routes "https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/src/app/api/ml"
click node_csv "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/src/lib/csv.ts"
click node_models "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/src/lib/ml-models.ts"
click node_math "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/src/lib/ml-math.ts"
click node_types "https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/src/lib/toolkit-types.ts"

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_python,node_desktop,node_web toneBlue
class node_dataset,node_descriptors toneAmber
class node_qsar,node_biology,node_docking,node_pkpd,node_generative,node_md,node_visualization,node_pipelines toneMint
class node_api,node_events,node_persistence,node_stores,node_exceptions toneRose
class node_web_routes,node_csv,node_models,node_math,node_types,node_researcher toneIndigo
```

## Components

### User interfaces

- [Python API and CLI](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml): `pharma-ml-toolkit/src/pharmaml`
- [Studio desktop](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/studio.py): `pharma-ml-toolkit/studio.py`
- [Web console](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/frontend/src): `pharma-ml-toolkit/frontend/src`

### Data and chemistry

- [Data loading and splitting](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/data.py): `pharma-ml-toolkit/src/pharmaml/data.py`
- [Descriptors and fingerprints](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/chem/descriptors.py): `pharma-ml-toolkit/src/pharmaml/chem/descriptors.py`

### Research workflows

- [QSAR training and evaluation](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/ml): `pharma-ml-toolkit/src/pharmaml/ml`
- [Biological response](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/biology): `pharma-ml-toolkit/src/pharmaml/biology`
- [Docking preparation and campaigns](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/docking): `pharma-ml-toolkit/src/pharmaml/docking`
- [PK and PD](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/pharma): `pharma-ml-toolkit/src/pharmaml/pharma`
- [Molecule generation](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/generative/genetic.py): `pharma-ml-toolkit/src/pharmaml/generative/genetic.py`
- [Molecular dynamics analysis](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/md): `pharma-ml-toolkit/src/pharmaml/md`
- [Visualization and reports](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/pharma-ml-toolkit/src/pharmaml/viz): `pharma-ml-toolkit/src/pharmaml/viz`
- [Sequential workflow pipelines](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/studio/pipelines.py): `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`

### API and persistence

- [Loopback API server](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/server.py): `pharma-ml-toolkit/src/pharmaml/api/server.py`
- [Events and jobs](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/events.py): `pharma-ml-toolkit/src/pharmaml/api/events.py`
- [Run persistence](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/persistence.py): `pharma-ml-toolkit/src/pharmaml/api/persistence.py`
- [API stores](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/api/stores.py): `pharma-ml-toolkit/src/pharmaml/api/stores.py`
- [Toolkit errors](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/pharma-ml-toolkit/src/pharmaml/exceptions.py): `pharma-ml-toolkit/src/pharmaml/exceptions.py`

### Web ML

- [ML API routes](https://github.com/mrmma2004/pharma-ml-toolkit/tree/main/src/app/api/ml): `src/app/api/ml`
- [CSV parsing and resolution](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/src/lib/csv.ts): `src/lib/csv.ts`
- [Model registry](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/src/lib/ml-models.ts): `src/lib/ml-models.ts`
- [ML algorithms and metrics](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/src/lib/ml-math.ts): `src/lib/ml-math.ts`
- [Shared API types](https://github.com/mrmma2004/pharma-ml-toolkit/blob/main/src/lib/toolkit-types.ts): `src/lib/toolkit-types.ts`

### Other components

- **Researcher**

## Connections

- Researcher → Python API and CLI: runs analyses (evidence: `README.md`)
- Researcher → Studio desktop: uses workflows (evidence: `README.md`)
- Researcher → Web console: explores projects (evidence: `README.md`)
- Python API and CLI → Data loading and splitting: inspects data (evidence: `README.md`)
- Python API and CLI → QSAR training and evaluation: models compounds (evidence: `README.md`)
- Python API and CLI → Descriptors and fingerprints: computes features (evidence: `README.md`)
- Python API and CLI → Biological response: analyzes response (evidence: `README.md`)
- Python API and CLI → Docking preparation and campaigns: runs docking (evidence: `README.md`)
- Python API and CLI → PK and PD: calculates PK/PD (evidence: `README.md`)
- Python API and CLI → Molecule generation: explores generation (evidence: `README.md`)
- Python API and CLI → Molecular dynamics analysis: analyzes trajectories (evidence: `README.md`)
- Python API and CLI → Visualization and reports: plots and reports (evidence: `README.md`)
- Data loading and splitting → Sequential workflow pipelines: loads dataset (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Sequential workflow pipelines → Descriptors and fingerprints: computes descriptors (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Sequential workflow pipelines → QSAR training and evaluation: trains models (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Sequential workflow pipelines → Biological response: runs analysis (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Sequential workflow pipelines → Molecule generation: runs generation (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Sequential workflow pipelines → Docking preparation and campaigns: prepares ligands (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Sequential workflow pipelines → PK and PD: runs PK analysis (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Sequential workflow pipelines → Molecular dynamics analysis: analyzes trajectory (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Sequential workflow pipelines → Visualization and reports: creates reports (evidence: `pharma-ml-toolkit/src/pharmaml/studio/pipelines.py`)
- Studio desktop → Loopback API server: starts server
- Loopback API server → Events and jobs: publishes events (evidence: `pharma-ml-toolkit/src/pharmaml/api/server.py`)
- Loopback API server → Run persistence: gets data directory (evidence: `pharma-ml-toolkit/src/pharmaml/api/server.py`)
- Run persistence → API stores: uses stores (evidence: `pharma-ml-toolkit/src/pharmaml/api/persistence.py`)
- Loopback API server → Toolkit errors: exposes errors (evidence: `pharma-ml-toolkit/src/pharmaml/api/server.py`)
- Web console → ML API routes: requests ML tools
- ML API routes → CSV parsing and resolution: parses CSV (evidence: `src/app/api/ml/train/route.ts`)
- ML API routes → Model registry: resolves models (evidence: `src/app/api/ml/train/route.ts`)
- ML API routes → ML algorithms and metrics: fits and scores (evidence: `src/app/api/ml/tune/route.ts`)
- Model registry → ML algorithms and metrics: calls algorithms (evidence: `src/lib/ml-models.ts`)
- ML API routes → Shared API types: uses API types (evidence: `src/app/api/ml/train/route.ts`)
