# hpc2n/softwareaccounting architecture

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

- Interactive diagram: https://gitdiagram.com/hpc2n/softwareaccounting
- Repository: https://github.com/hpc2n/softwareaccounting

## Overview

SAMS collects software-accounting data, processes and aggregates it, then submits or exposes results. The main stages are job/process sampling, file-based ingestion and aggregation, software-metadata database maintenance, and output formatting or metrics exposure. The graph includes the central runtime abstractions and documented capability branches. Several implementation excerpts are incomplete, so links between dynamically configured stages are omitted unless supported by the shown source references.

Main entry points: [`sams/base.py`](https://github.com/hpc2n/softwareaccounting/blob/master/sams/base.py) (Runtime abstractions), [`sams/core.py`](https://github.com/hpc2n/softwareaccounting/blob/master/sams/core.py) (Config and dispatch), [`sams/backend/SoftwareAccountingPW.py`](https://github.com/hpc2n/softwareaccounting/blob/master/sams/backend/SoftwareAccountingPW.py) (Software database), [`sams/sampler/Software.py`](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/Software.py) (Process accounting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime core"]
  node_collector["Collector CLI<br/>[sams-collector.py]"]
  node_core["Config and dispatch<br/>[core.py]"]
  node_base["Runtime abstractions<br/>[base.py]"]
end

subgraph group_collection["Data collection"]
  node_sampler["Process accounting<br/>[Software.py]"]
  node_gpu["GPU sampling<br/>[NvidiaSMI.py]"]
  node_jobmetrics["Job metrics<br/>[SlurmInfo.py]"]
  node_cgroup["Slurm cgroups<br/>[SlurmCGroup.py]"]
  node_fsstats["Filesystem stats<br/>[FSStats.py]"]
  node_iostats["I/O statistics<br/>[IOStats.py]"]
  node_pressure["Pressure stats<br/>[Pressure.py]"]
  node_zfs["ZFS statistics<br/>[ZFSStats.py]"]
end

subgraph group_accounting["Accounting data"]
  node_loader["File ingestion<br/>[File.py]"]
  node_aggregator["Job aggregation"]
  node_softwaredb[("Software database")]
  node_softwareagg["Software aggregation"]
  node_updater["Software updater"]
  node_extractor["Software extractor"]
end

subgraph group_delivery["Output and integration"]
  node_xml["XML records<br/>[File.py]"]
  node_promout["Prometheus files<br/>[Prometheus.py]"]
  node_promlisten["Prometheus listener<br/>[Prometheus.py]"]
  node_otheroutputs["Metric outputs"]
end

node_user(("Operator"))
node_prometheus(("Prometheus"))

node_collector -->|"imports"| node_core
node_sampler -->|"inherits from"| node_base
node_sampler -->|"uses"| node_core
node_gpu -->|"inherits from"| node_base
node_jobmetrics -->|"inherits from"| node_base
node_cgroup -->|"inherits from"| node_base
node_fsstats -->|"inherits from"| node_base
node_iostats -->|"inherits from"| node_base
node_pressure -->|"inherits from"| node_base
node_zfs -->|"inherits from"| node_base
node_loader -->|"inherits from"| node_base
node_aggregator -->|"inherits from"| node_base
node_softwareagg -->|"uses backend"| node_softwaredb
node_softwaredb -->|"inherits from"| node_base
node_softwaredb -->|"uses"| node_core
node_updater -->|"imports"| node_core
node_extractor -.->|"extracts metadata"| node_softwaredb
node_xml -->|"inherits from"| node_base
node_promout -->|"inherits from"| node_base
node_promlisten -->|"inherits from"| node_base
node_promlisten -->|"uses config"| node_core
node_user -.->|"runs"| node_collector
node_prometheus -.->|"scrapes metrics"| node_promout

click node_collector "https://github.com/hpc2n/softwareaccounting/blob/master/scripts/sams-collector.py"
click node_core "https://github.com/hpc2n/softwareaccounting/blob/master/sams/core.py"
click node_base "https://github.com/hpc2n/softwareaccounting/blob/master/sams/base.py"
click node_sampler "https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/Software.py"
click node_gpu "https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/NvidiaSMI.py"
click node_jobmetrics "https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/SlurmInfo.py"
click node_cgroup "https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/SlurmCGroup.py"
click node_fsstats "https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/FSStats.py"
click node_iostats "https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/IOStats.py"
click node_pressure "https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/Pressure.py"
click node_zfs "https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/ZFSStats.py"
click node_loader "https://github.com/hpc2n/softwareaccounting/blob/master/sams/loader/File.py"
click node_aggregator "https://github.com/hpc2n/softwareaccounting/blob/master/sams/aggregator/SoftwareAccounting.py"
click node_softwaredb "https://github.com/hpc2n/softwareaccounting/blob/master/sams/backend/SoftwareAccountingPW.py"
click node_softwareagg "https://github.com/hpc2n/softwareaccounting/blob/master/sams/aggregator/SoftwareAccountingPW.py"
click node_updater "https://github.com/hpc2n/softwareaccounting/blob/master/scripts/sams-software-updater.py"
click node_extractor "https://github.com/hpc2n/softwareaccounting/blob/master/scripts/sams-software-extractor.py"
click node_xml "https://github.com/hpc2n/softwareaccounting/blob/master/sams/xmlwriter/File.py"
click node_promout "https://github.com/hpc2n/softwareaccounting/blob/master/sams/output/Prometheus.py"
click node_promlisten "https://github.com/hpc2n/softwareaccounting/blob/master/sams/listener/Prometheus.py"
click node_otheroutputs "https://github.com/hpc2n/softwareaccounting/tree/master/sams/output"

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_collector,node_core,node_base toneBlue
class node_sampler,node_gpu,node_jobmetrics,node_cgroup,node_fsstats,node_iostats,node_pressure,node_zfs toneAmber
class node_loader,node_aggregator,node_softwaredb,node_softwareagg,node_updater,node_extractor toneMint
class node_xml,node_promout,node_promlisten,node_otheroutputs toneRose
class node_user,node_prometheus toneIndigo
```

## Components

### Runtime core

- [Collector CLI](https://github.com/hpc2n/softwareaccounting/blob/master/scripts/sams-collector.py): `scripts/sams-collector.py`
- [Config and dispatch](https://github.com/hpc2n/softwareaccounting/blob/master/sams/core.py): `sams/core.py`
- [Runtime abstractions](https://github.com/hpc2n/softwareaccounting/blob/master/sams/base.py): `sams/base.py`

### Data collection

- [Process accounting](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/Software.py): `sams/sampler/Software.py`
- [GPU sampling](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/NvidiaSMI.py): `sams/sampler/NvidiaSMI.py`
- [Job metrics](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/SlurmInfo.py): `sams/sampler/SlurmInfo.py`
- [Slurm cgroups](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/SlurmCGroup.py): `sams/sampler/SlurmCGroup.py`
- [Filesystem stats](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/FSStats.py): `sams/sampler/FSStats.py`
- [I/O statistics](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/IOStats.py): `sams/sampler/IOStats.py`
- [Pressure stats](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/Pressure.py): `sams/sampler/Pressure.py`
- [ZFS statistics](https://github.com/hpc2n/softwareaccounting/blob/master/sams/sampler/ZFSStats.py): `sams/sampler/ZFSStats.py`

### Accounting data

- [File ingestion](https://github.com/hpc2n/softwareaccounting/blob/master/sams/loader/File.py): `sams/loader/File.py`
- [Job aggregation](https://github.com/hpc2n/softwareaccounting/blob/master/sams/aggregator/SoftwareAccounting.py): `sams/aggregator/SoftwareAccounting.py`
- [Software database](https://github.com/hpc2n/softwareaccounting/blob/master/sams/backend/SoftwareAccountingPW.py): `sams/backend/SoftwareAccountingPW.py`
- [Software aggregation](https://github.com/hpc2n/softwareaccounting/blob/master/sams/aggregator/SoftwareAccountingPW.py): `sams/aggregator/SoftwareAccountingPW.py`
- [Software updater](https://github.com/hpc2n/softwareaccounting/blob/master/scripts/sams-software-updater.py): `scripts/sams-software-updater.py`
- [Software extractor](https://github.com/hpc2n/softwareaccounting/blob/master/scripts/sams-software-extractor.py): `scripts/sams-software-extractor.py`

### Output and integration

- [XML records](https://github.com/hpc2n/softwareaccounting/blob/master/sams/xmlwriter/File.py): `sams/xmlwriter/File.py`
- [Prometheus files](https://github.com/hpc2n/softwareaccounting/blob/master/sams/output/Prometheus.py): `sams/output/Prometheus.py`
- [Prometheus listener](https://github.com/hpc2n/softwareaccounting/blob/master/sams/listener/Prometheus.py): `sams/listener/Prometheus.py`
- [Metric outputs](https://github.com/hpc2n/softwareaccounting/tree/master/sams/output): `sams/output`

### Other components

- **Operator**
- **Prometheus**

## Connections

- Collector CLI → Config and dispatch: imports (evidence: `scripts/sams-collector.py`)
- Process accounting → Runtime abstractions: inherits from (evidence: `sams/sampler/Software.py`)
- Process accounting → Config and dispatch: uses (evidence: `sams/sampler/Software.py`)
- GPU sampling → Runtime abstractions: inherits from (evidence: `sams/sampler/NvidiaSMI.py`)
- Job metrics → Runtime abstractions: inherits from (evidence: `sams/sampler/SlurmInfo.py`)
- Slurm cgroups → Runtime abstractions: inherits from (evidence: `sams/sampler/SlurmCGroup.py`)
- Filesystem stats → Runtime abstractions: inherits from (evidence: `sams/sampler/FSStats.py`)
- I/O statistics → Runtime abstractions: inherits from (evidence: `sams/sampler/IOStats.py`)
- Pressure stats → Runtime abstractions: inherits from (evidence: `sams/sampler/Pressure.py`)
- ZFS statistics → Runtime abstractions: inherits from (evidence: `sams/sampler/ZFSStats.py`)
- File ingestion → Runtime abstractions: inherits from (evidence: `sams/loader/File.py`)
- Job aggregation → Runtime abstractions: inherits from (evidence: `sams/aggregator/SoftwareAccounting.py`)
- Software aggregation → Software database: uses backend (evidence: `sams/aggregator/SoftwareAccountingPW.py`)
- Software database → Runtime abstractions: inherits from (evidence: `sams/backend/SoftwareAccountingPW.py`)
- Software database → Config and dispatch: uses (evidence: `sams/backend/SoftwareAccountingPW.py`)
- Software updater → Config and dispatch: imports (evidence: `scripts/sams-software-updater.py`)
- Software extractor → Software database: extracts metadata
- XML records → Runtime abstractions: inherits from (evidence: `sams/xmlwriter/File.py`)
- Prometheus files → Runtime abstractions: inherits from (evidence: `sams/output/Prometheus.py`)
- Prometheus listener → Runtime abstractions: inherits from (evidence: `sams/listener/Prometheus.py`)
- Prometheus listener → Config and dispatch: uses config (evidence: `sams/listener/Prometheus.py`)
- Operator → Collector CLI: runs
- Prometheus → Prometheus files: scrapes metrics