# elsci-io/peaksel-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/elsci-io/peaksel-sdk
- Repository: https://github.com/elsci-io/peaksel-sdk

## Overview

Peaksel SDK is a Python client for uploading and managing chromatography data and retrieving parsed signals and spectra from the Peaksel service. The principal workflow is for an application to use the SDK to upload raw injection files, retrieve injection and chromatogram data, and fetch binary trace or spectrum data for custom processing. Other client modules cover batches, substances, peaks, organizations, and users; optional integrations support matchms and mocca. The sampled clients call the shared HTTP wrapper, while the blob client also uses a cache and decodes binary responses. The tree and excerpts do not establish all facade wiring or the details of unsampled clients, so those links are omitted.

Main entry points: [`python/src/peakselsdk/HttpClient.py`](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/HttpClient.py) (HTTP client), [`python/src/peakselsdk/blob/BlobClient.py`](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/blob/BlobClient.py) (Blob client), [`python/src/peakselsdk/injection/InjectionClient.py`](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/injection/InjectionClient.py) (Injection client), [`python/src/peakselsdk/chromatogram/ChromClient.py`](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/chromatogram/ChromClient.py) (Chromatogram client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["SDK entry"]
  node_facade["Peaksel facade<br/>[Peaksel.py]"]
end

subgraph group_transport["Transport and data"]
  node_http["HTTP client<br/>[HttpClient.py]"]
  node_cache["Blob cache<br/>[CacheManager.py]"]
  node_blob["Blob client<br/>[BlobClient.py]"]
  node_binary["Binary decoding<br/>[blobs.py]"]
  node_spectrum["Spectrum models<br/>[Spectrum.py]"]
end

subgraph group_chrom["Chromatography data"]
  node_injections["Injection client<br/>[InjectionClient.py]"]
  node_injection_models["Injection models<br/>[Injection.py]"]
  node_chromatograms["Chromatogram client<br/>[ChromClient.py]"]
  node_detector_runs["Detector run models<br/>[DetectorRun.py]"]
end

subgraph group_management["Data management"]
  node_batches["Batch client<br/>[BatchClient.py]"]
  node_substances["Substance client<br/>[SubstanceClient.py]"]
  node_peaks["Peak client<br/>[PeakClient.py]"]
  node_organizations["Organization client<br/>[OrgClient.py]"]
  node_users["User client<br/>[UserClient.py]"]
end

subgraph group_integrations["Integrations"]
  node_integrations["Analysis integrations<br/>[matchms.py]"]
end

node_application(("Client application"))
node_peaksel_service{{"Peaksel service"}}

node_application -->|"uses SDK"| node_facade
node_injections -->|"uploads and queries"| node_http
node_chromatograms -->|"posts chromatograms"| node_http
node_batches -->|"queries and reassigns"| node_http
node_substances -->|"posts substances"| node_http
node_peaks -->|"posts peaks"| node_http
node_organizations -->|"queries and creates"| node_http
node_users -->|"fetches user"| node_http
node_blob -->|"reads and writes"| node_cache
node_blob -->|"fetches blobs"| node_http
node_blob -->|"decodes signals"| node_binary
node_blob -->|"parses spectra"| node_spectrum
node_http -->|"sends requests"| node_peaksel_service
node_integrations -.->|"optional analysis"| node_application

click node_facade "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/Peaksel.py"
click node_http "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/HttpClient.py"
click node_cache "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/util/CacheManager.py"
click node_blob "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/blob/BlobClient.py"
click node_binary "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/blob/blobs.py"
click node_spectrum "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/blob/Spectrum.py"
click node_injections "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/injection/InjectionClient.py"
click node_injection_models "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/injection/Injection.py"
click node_chromatograms "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/chromatogram/ChromClient.py"
click node_detector_runs "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/dr/DetectorRun.py"
click node_batches "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/batch/BatchClient.py"
click node_substances "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/substance/SubstanceClient.py"
click node_peaks "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/chromatogram/peak/PeakClient.py"
click node_organizations "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/org/OrgClient.py"
click node_users "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/user/UserClient.py"
click node_integrations "https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/integrations/matchms.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_facade,node_application toneBlue
class node_http,node_cache,node_blob,node_binary,node_spectrum toneAmber
class node_injections,node_injection_models,node_chromatograms,node_detector_runs toneMint
class node_batches,node_substances,node_peaks,node_organizations,node_users toneRose
class node_integrations,node_peaksel_service toneIndigo
```

## Components

### SDK entry

- [Peaksel facade](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/Peaksel.py): `python/src/peakselsdk/Peaksel.py`

### Transport and data

- [HTTP client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/HttpClient.py): `python/src/peakselsdk/HttpClient.py`
- [Blob cache](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/util/CacheManager.py): `python/src/peakselsdk/util/CacheManager.py`
- [Blob client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/blob/BlobClient.py): `python/src/peakselsdk/blob/BlobClient.py`
- [Binary decoding](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/blob/blobs.py): `python/src/peakselsdk/blob/blobs.py`
- [Spectrum models](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/blob/Spectrum.py): `python/src/peakselsdk/blob/Spectrum.py`

### Chromatography data

- [Injection client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/injection/InjectionClient.py): `python/src/peakselsdk/injection/InjectionClient.py`
- [Injection models](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/injection/Injection.py): `python/src/peakselsdk/injection/Injection.py`
- [Chromatogram client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/chromatogram/ChromClient.py): `python/src/peakselsdk/chromatogram/ChromClient.py`
- [Detector run models](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/dr/DetectorRun.py): `python/src/peakselsdk/dr/DetectorRun.py`

### Data management

- [Batch client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/batch/BatchClient.py): `python/src/peakselsdk/batch/BatchClient.py`
- [Substance client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/substance/SubstanceClient.py): `python/src/peakselsdk/substance/SubstanceClient.py`
- [Peak client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/chromatogram/peak/PeakClient.py): `python/src/peakselsdk/chromatogram/peak/PeakClient.py`
- [Organization client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/org/OrgClient.py): `python/src/peakselsdk/org/OrgClient.py`
- [User client](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/user/UserClient.py): `python/src/peakselsdk/user/UserClient.py`

### Integrations

- [Analysis integrations](https://github.com/elsci-io/peaksel-sdk/blob/master/python/src/peakselsdk/integrations/matchms.py): `python/src/peakselsdk/integrations/matchms.py`

### Other components

- **Client application**
- **Peaksel service**

## Connections

- Client application → Peaksel facade: uses SDK
- Injection client → HTTP client: uploads and queries
- Chromatogram client → HTTP client: posts chromatograms
- Batch client → HTTP client: queries and reassigns
- Substance client → HTTP client: posts substances
- Peak client → HTTP client: posts peaks
- Organization client → HTTP client: queries and creates
- User client → HTTP client: fetches user
- Blob client → Blob cache: reads and writes
- Blob client → HTTP client: fetches blobs
- Blob client → Binary decoding: decodes signals
- Blob client → Spectrum models: parses spectra
- HTTP client → Peaksel service: sends requests
- Analysis integrations → Client application: optional analysis