# gstt-csc/hazen architecture

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

- Interactive diagram: https://gitdiagram.com/gstt-csc/hazen
- Repository: https://github.com/gstt-csc/hazen

## Overview

hazen is a Python CLI for automated MRI phantom quality assurance. A user supplies DICOM data and selects a measurement task (or a batch/protocol); the application analyzes the images and emits structured numerical results, with optional report visualizations. The map preserves ACR, MagNET, and Caliber relaxometry capabilities documented in the README. Source excerpts show the CLI, discovery, orchestration, and shared analysis layers; some task-level links are documented rather than demonstrated in the excerpts.

Main entry points: [`hazenlib/types.py`](https://github.com/gstt-csc/hazen/blob/main/hazenlib/types.py) (Result types), [`hazenlib/__init__.py`](https://github.com/gstt-csc/hazen/blob/main/hazenlib/__init__.py) (CLI entry), [`hazenlib/tasks`](https://github.com/gstt-csc/hazen/tree/main/hazenlib/tasks) (ACR measurements), [`hazenlib/HazenTask.py`](https://github.com/gstt-csc/hazen/blob/main/hazenlib/HazenTask.py) (Task base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_cli["CLI entry<br/>[__init__.py]"]
  node_version["Version resolution<br/>[_version.py]"]
end

subgraph group_coord["Workflow coordination"]
  node_discovery["Data discovery<br/>[discovery.py]"]
  node_orchestrator["Task orchestration<br/>[orchestration.py]"]
  node_acr_protocol["ACR protocol<br/>[orchestration.py]"]
  node_execution["Execution timing<br/>[execution.py]"]
end

subgraph group_analysis["Phantom analysis"]
  node_acr_measurements["ACR measurements"]
  node_magnet_measurements["MagNET measurements"]
  node_relaxometry["Caliber relaxometry<br/>[relaxometry.py]"]
  node_relax_params["Relaxometry parameters"]
end

subgraph group_shared["Analysis infrastructure"]
  node_base_task["Task base<br/>[HazenTask.py]"]
  node_acr_object["ACR image model<br/>[ACRObject.py]"]
  node_utils["DICOM utilities<br/>[utils.py]"]
  node_logger["Logging<br/>[logger.py]"]
  node_exceptions["Domain errors<br/>[exceptions.py]"]
end

subgraph group_results["Results and reporting"]
  node_types["Result types<br/>[types.py]"]
  node_formatters["Output formatting<br/>[formatters.py]"]
  node_constants["Measurement constants<br/>[constants.py]"]
end

node_user(("QA analyst"))
node_terminal(("Terminal output"))
node_report["Report images"]

node_user -->|"selects task"| node_cli
node_cli -->|"runs batch"| node_orchestrator
node_cli -->|"starts protocol"| node_acr_protocol
node_cli -->|"times execution"| node_execution
node_cli -->|"reads version"| node_version
node_orchestrator -->|"discovers jobs"| node_discovery
node_discovery -->|"classifies images"| node_acr_object
node_discovery -->|"reads metadata"| node_utils
node_acr_protocol -->|"dispatches tasks"| node_acr_measurements
node_orchestrator -->|"aggregates results"| node_types
node_acr_measurements -.->|"uses base"| node_base_task
node_magnet_measurements -.->|"uses base"| node_base_task
node_relaxometry -->|"uses base"| node_base_task
node_relaxometry -->|"uses parameters"| node_relax_params
node_acr_measurements -.->|"analyzes phantom"| node_acr_object
node_acr_measurements -.->|"processes images"| node_utils
node_magnet_measurements -.->|"processes images"| node_utils
node_relaxometry -.->|"processes images"| node_utils
node_base_task -->|"creates results"| node_types
node_acr_measurements -.->|"records measurements"| node_types
node_magnet_measurements -.->|"records measurements"| node_types
node_relaxometry -->|"records measurements"| node_types
node_types -->|"formats results"| node_formatters
node_formatters -->|"writes output"| node_terminal
node_types -->|"includes visuals"| node_report
node_cli -->|"configures logging"| node_logger
node_base_task -->|"logs input"| node_logger
node_types -->|"validates fields"| node_constants
node_types -->|"raises errors"| node_exceptions

click node_cli "https://github.com/gstt-csc/hazen/blob/main/hazenlib/__init__.py"
click node_discovery "https://github.com/gstt-csc/hazen/blob/main/hazenlib/discovery.py"
click node_orchestrator "https://github.com/gstt-csc/hazen/blob/main/hazenlib/orchestration.py"
click node_acr_protocol "https://github.com/gstt-csc/hazen/blob/main/hazenlib/orchestration.py"
click node_base_task "https://github.com/gstt-csc/hazen/blob/main/hazenlib/HazenTask.py"
click node_acr_object "https://github.com/gstt-csc/hazen/blob/main/hazenlib/ACRObject.py"
click node_acr_measurements "https://github.com/gstt-csc/hazen/tree/main/hazenlib/tasks"
click node_magnet_measurements "https://github.com/gstt-csc/hazen/tree/main/hazenlib/tasks"
click node_relaxometry "https://github.com/gstt-csc/hazen/blob/main/hazenlib/tasks/relaxometry.py"
click node_relax_params "https://github.com/gstt-csc/hazen/blob/main/hazenlib/data/relaxometry_params.py"
click node_utils "https://github.com/gstt-csc/hazen/blob/main/hazenlib/utils.py"
click node_types "https://github.com/gstt-csc/hazen/blob/main/hazenlib/types.py"
click node_formatters "https://github.com/gstt-csc/hazen/blob/main/hazenlib/formatters.py"
click node_execution "https://github.com/gstt-csc/hazen/blob/main/hazenlib/execution.py"
click node_logger "https://github.com/gstt-csc/hazen/blob/main/hazenlib/logger.py"
click node_exceptions "https://github.com/gstt-csc/hazen/blob/main/hazenlib/exceptions.py"
click node_version "https://github.com/gstt-csc/hazen/blob/main/hazenlib/_version.py"
click node_constants "https://github.com/gstt-csc/hazen/blob/main/hazenlib/constants.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_cli,node_version toneBlue
class node_discovery,node_orchestrator,node_acr_protocol,node_execution toneAmber
class node_acr_measurements,node_magnet_measurements,node_relaxometry,node_relax_params toneMint
class node_base_task,node_acr_object,node_utils,node_logger,node_exceptions toneRose
class node_types,node_formatters,node_constants,node_user,node_terminal,node_report toneIndigo
```

## Components

### Command entry

- [CLI entry](https://github.com/gstt-csc/hazen/blob/main/hazenlib/__init__.py): `hazenlib/__init__.py`
- [Version resolution](https://github.com/gstt-csc/hazen/blob/main/hazenlib/_version.py): `hazenlib/_version.py`

### Workflow coordination

- [Data discovery](https://github.com/gstt-csc/hazen/blob/main/hazenlib/discovery.py): `hazenlib/discovery.py`
- [Task orchestration](https://github.com/gstt-csc/hazen/blob/main/hazenlib/orchestration.py): `hazenlib/orchestration.py`
- [ACR protocol](https://github.com/gstt-csc/hazen/blob/main/hazenlib/orchestration.py): `hazenlib/orchestration.py`
- [Execution timing](https://github.com/gstt-csc/hazen/blob/main/hazenlib/execution.py): `hazenlib/execution.py`

### Phantom analysis

- [ACR measurements](https://github.com/gstt-csc/hazen/tree/main/hazenlib/tasks): `hazenlib/tasks`
- [MagNET measurements](https://github.com/gstt-csc/hazen/tree/main/hazenlib/tasks): `hazenlib/tasks`
- [Caliber relaxometry](https://github.com/gstt-csc/hazen/blob/main/hazenlib/tasks/relaxometry.py): `hazenlib/tasks/relaxometry.py`
- [Relaxometry parameters](https://github.com/gstt-csc/hazen/blob/main/hazenlib/data/relaxometry_params.py): `hazenlib/data/relaxometry_params.py`

### Analysis infrastructure

- [Task base](https://github.com/gstt-csc/hazen/blob/main/hazenlib/HazenTask.py): `hazenlib/HazenTask.py`
- [ACR image model](https://github.com/gstt-csc/hazen/blob/main/hazenlib/ACRObject.py): `hazenlib/ACRObject.py`
- [DICOM utilities](https://github.com/gstt-csc/hazen/blob/main/hazenlib/utils.py): `hazenlib/utils.py`
- [Logging](https://github.com/gstt-csc/hazen/blob/main/hazenlib/logger.py): `hazenlib/logger.py`
- [Domain errors](https://github.com/gstt-csc/hazen/blob/main/hazenlib/exceptions.py): `hazenlib/exceptions.py`

### Results and reporting

- [Result types](https://github.com/gstt-csc/hazen/blob/main/hazenlib/types.py): `hazenlib/types.py`
- [Output formatting](https://github.com/gstt-csc/hazen/blob/main/hazenlib/formatters.py): `hazenlib/formatters.py`
- [Measurement constants](https://github.com/gstt-csc/hazen/blob/main/hazenlib/constants.py): `hazenlib/constants.py`

### Other components

- **QA analyst**
- **Terminal output**
- **Report images**

## Connections

- QA analyst → CLI entry: selects task (evidence: `README.md`)
- CLI entry → Task orchestration: runs batch (evidence: `hazenlib/__init__.py`)
- CLI entry → ACR protocol: starts protocol (evidence: `hazenlib/__init__.py`)
- CLI entry → Execution timing: times execution (evidence: `hazenlib/__init__.py`)
- CLI entry → Version resolution: reads version (evidence: `hazenlib/__init__.py`)
- Task orchestration → Data discovery: discovers jobs (evidence: `hazenlib/discovery.py`)
- Data discovery → ACR image model: classifies images (evidence: `hazenlib/discovery.py`)
- Data discovery → DICOM utilities: reads metadata (evidence: `hazenlib/discovery.py`)
- ACR protocol → ACR measurements: dispatches tasks (evidence: `hazenlib/orchestration.py`)
- Task orchestration → Result types: aggregates results (evidence: `hazenlib/orchestration.py`)
- ACR measurements → Task base: uses base (evidence: `hazenlib/tasks/acr_geometric_accuracy.py`)
- MagNET measurements → Task base: uses base (evidence: `hazenlib/tasks/ghosting.py`)
- Caliber relaxometry → Task base: uses base (evidence: `hazenlib/tasks/relaxometry.py`)
- Caliber relaxometry → Relaxometry parameters: uses parameters (evidence: `hazenlib/tasks/relaxometry.py`)
- ACR measurements → ACR image model: analyzes phantom (evidence: `hazenlib/tasks/acr_geometric_accuracy.py`)
- ACR measurements → DICOM utilities: processes images (evidence: `hazenlib/tasks/acr_slice_thickness.py`)
- MagNET measurements → DICOM utilities: processes images (evidence: `hazenlib/tasks/ghosting.py`)
- Caliber relaxometry → DICOM utilities: processes images (evidence: `hazenlib/tasks/relaxometry.py`)
- Task base → Result types: creates results (evidence: `hazenlib/HazenTask.py`)
- ACR measurements → Result types: records measurements (evidence: `hazenlib/tasks/acr_geometric_accuracy.py`)
- MagNET measurements → Result types: records measurements (evidence: `hazenlib/tasks/ghosting.py`)
- Caliber relaxometry → Result types: records measurements (evidence: `hazenlib/tasks/relaxometry.py`)
- Result types → Output formatting: formats results (evidence: `hazenlib/formatters.py`)
- Output formatting → Terminal output: writes output (evidence: `README.md`)
- Result types → Report images: includes visuals (evidence: `README.md`)
- CLI entry → Logging: configures logging (evidence: `hazenlib/__init__.py`)
- Task base → Logging: logs input (evidence: `hazenlib/HazenTask.py`)
- Result types → Measurement constants: validates fields (evidence: `hazenlib/types.py`)
- Result types → Domain errors: raises errors (evidence: `hazenlib/types.py`)
