# hz-b/kiwi-scan architecture

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

- Interactive diagram: https://gitdiagram.com/hz-b/kiwi-scan
- Repository: https://github.com/hz-b/kiwi-scan

## Overview

kiwi-scan is a configurable EPICS scan framework. Its principal workflow loads YAML and scan dimensions, constructs a selected scan engine, coordinates actuator motion or observation with synchronized detector acquisition, assembles point data, and writes timestamped results and optional metadata. Separate capabilities cover plugins, event-driven triggers and subscriptions, monitoring, export, manifests, and IOC/PVA integration. The README and source index establish the broad feature map; several subsystem connections below are documented rather than verified from complete implementation excerpts.

Main entry points: [`src/kiwi_scan/scan/common.py`](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/common.py) (Scan coordination), [`src/kiwi_scan/scan/tools.py`](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/tools.py) (Scan construction API), [`src/kiwi_scan/cli/scan_runner.py`](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/cli/scan_runner.py) (Scan runner), [`src/kiwi_scan/ioc/controller.py`](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/ioc/controller.py) (Generic scan IOC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Scan execution"]
  node_config["YAML configuration<br/>[yaml_loader.py]"]
  node_models["Scan configuration models<br/>[datamodels.py]"]
  node_scan_cli["Scan runner<br/>[scan_runner.py]"]
  node_scan_api["Scan construction API<br/>[tools.py]"]
  node_registry["Scan type registry<br/>[registry.py]"]
  node_engines["Scan engines"]
  node_base_scan["Scan coordination<br/>[common.py]"]
  node_pipeline["Point data pipeline<br/>[point_pipeline.py]"]
end

subgraph group_hardware["Devices and acquisition"]
  node_sync["Acquisition synchronization<br/>[sync_controller.py]"]
  node_actuator_factory["Actuator factory<br/>[factory.py]"]
  node_actuators["Actuator backends"]
  node_epics["EPICS PV access<br/>[epics_wrapper.py]"]
  node_subscriptions["Subscriptions and event routing"]
  node_triggers["Scan triggers<br/>[trigger_manager.py]"]
end

subgraph group_extensions["Runtime extensions"]
  node_plugins["Plugin framework<br/>[base.py]"]
  node_plugin_registry["Plugin registry<br/>[registry.py]"]
  node_plugin_impl["Built-in plugins"]
end

subgraph group_results["Results and insight"]
  node_output["Scan file output<br/>[output_manager.py]"]
  node_manifest[("Manifest file management<br/>[manifestwriter.py]")]
  node_data_load["Scan data loading<br/>[loader.py]"]
  node_export["SPEC and data export<br/>[spec.py]"]
  node_monitor["Live monitors and plots<br/>[queue_plotter.py]"]
  node_stats["Statistics and diagnostics<br/>[stats_collector.py]"]
end

subgraph group_control["Control-system interfaces"]
  node_ioc["Generic scan IOC<br/>[controller.py]"]
  node_pva["PVA table server<br/>[pva_table.py]"]
end

node_user(("Engineer / API caller"))

node_user -->|"runs scan"| node_scan_cli
node_user -->|"calls API"| node_scan_api
node_config -->|"parses into"| node_models
node_scan_cli -->|"loads"| node_config
node_scan_cli -->|"constructs scan"| node_scan_api
node_scan_api -->|"selects type"| node_registry
node_registry -->|"registers built-ins"| node_engines
node_scan_api -->|"creates scan"| node_base_scan
node_engines -->|"uses coordination"| node_base_scan
node_base_scan -->|"assembles points"| node_pipeline
node_base_scan -->|"creates actuators"| node_actuator_factory
node_actuator_factory -->|"builds backend"| node_actuators
node_actuators -->|"uses PV access"| node_epics
node_base_scan -.->|"synchronizes acquisition"| node_sync
node_base_scan -->|"routes events"| node_subscriptions
node_base_scan -.->|"fires triggers"| node_triggers
node_base_scan -->|"loads plugins"| node_plugin_registry
node_plugin_registry -->|"registers plugins"| node_plugin_impl
node_plugins -->|"accesses scan context"| node_base_scan
node_pipeline -.->|"provides point rows"| node_output
node_output -.->|"records scan files"| node_manifest
node_scan_cli -->|"manages manifest"| node_manifest
node_data_load -.->|"supplies scan data"| node_export
node_base_scan -.->|"publishes monitor data"| node_monitor
node_base_scan -.->|"collects statistics"| node_stats
node_user -->|"controls scans"| node_ioc
node_ioc -->|"creates scan"| node_scan_api
node_ioc -->|"creates manifest"| node_manifest
node_pva -.->|"publishes scan data"| node_base_scan

click node_config "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/yaml_loader.py"
click node_models "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/datamodels.py"
click node_scan_cli "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/cli/scan_runner.py"
click node_scan_api "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/tools.py"
click node_registry "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/registry.py"
click node_engines "https://github.com/hz-b/kiwi-scan/tree/master/src/kiwi_scan/scan_concrete"
click node_base_scan "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/common.py"
click node_pipeline "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/point_pipeline.py"
click node_sync "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/sync_controller.py"
click node_actuator_factory "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/actuator/factory.py"
click node_actuators "https://github.com/hz-b/kiwi-scan/tree/master/src/kiwi_scan/actuator_concrete"
click node_epics "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/epics_wrapper.py"
click node_subscriptions "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/subscription_manager.py"
click node_triggers "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/trigger_manager.py"
click node_plugins "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/plugin/base.py"
click node_plugin_registry "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/plugin/registry.py"
click node_plugin_impl "https://github.com/hz-b/kiwi-scan/tree/master/src/kiwi_scan/plugin_concrete"
click node_output "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/output_manager.py"
click node_manifest "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/data/manifestwriter.py"
click node_data_load "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/data/loader.py"
click node_export "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/export/spec.py"
click node_monitor "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/monitor_concrete/queue_plotter.py"
click node_stats "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/stats_collector.py"
click node_ioc "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/ioc/controller.py"
click node_pva "https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/ioc/pva_table.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_config,node_models,node_scan_cli,node_scan_api,node_registry,node_engines,node_base_scan,node_pipeline toneBlue
class node_sync,node_actuator_factory,node_actuators,node_epics,node_subscriptions,node_triggers toneAmber
class node_plugins,node_plugin_registry,node_plugin_impl,node_user toneMint
class node_output,node_manifest,node_data_load,node_export,node_monitor,node_stats toneRose
class node_ioc,node_pva toneIndigo
```

## Components

### Scan execution

- [YAML configuration](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/yaml_loader.py): `src/kiwi_scan/yaml_loader.py`
- [Scan configuration models](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/datamodels.py): `src/kiwi_scan/datamodels.py`
- [Scan runner](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/cli/scan_runner.py): `src/kiwi_scan/cli/scan_runner.py`
- [Scan construction API](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/tools.py): `src/kiwi_scan/scan/tools.py`
- [Scan type registry](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/registry.py): `src/kiwi_scan/scan/registry.py`
- [Scan engines](https://github.com/hz-b/kiwi-scan/tree/master/src/kiwi_scan/scan_concrete): `src/kiwi_scan/scan_concrete`
- [Scan coordination](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/common.py): `src/kiwi_scan/scan/common.py`
- [Point data pipeline](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/point_pipeline.py): `src/kiwi_scan/scan/point_pipeline.py`

### Devices and acquisition

- [Acquisition synchronization](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/sync_controller.py): `src/kiwi_scan/scan/sync_controller.py`
- [Actuator factory](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/actuator/factory.py): `src/kiwi_scan/actuator/factory.py`
- [Actuator backends](https://github.com/hz-b/kiwi-scan/tree/master/src/kiwi_scan/actuator_concrete): `src/kiwi_scan/actuator_concrete`
- [EPICS PV access](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/epics_wrapper.py): `src/kiwi_scan/epics_wrapper.py`
- [Subscriptions and event routing](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/subscription_manager.py): `src/kiwi_scan/scan/subscription_manager.py`
- [Scan triggers](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/trigger_manager.py): `src/kiwi_scan/scan/trigger_manager.py`

### Runtime extensions

- [Plugin framework](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/plugin/base.py): `src/kiwi_scan/plugin/base.py`
- [Plugin registry](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/plugin/registry.py): `src/kiwi_scan/plugin/registry.py`
- [Built-in plugins](https://github.com/hz-b/kiwi-scan/tree/master/src/kiwi_scan/plugin_concrete): `src/kiwi_scan/plugin_concrete`

### Results and insight

- [Scan file output](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/output_manager.py): `src/kiwi_scan/scan/output_manager.py`
- [Manifest file management](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/data/manifestwriter.py): `src/kiwi_scan/data/manifestwriter.py`
- [Scan data loading](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/data/loader.py): `src/kiwi_scan/data/loader.py`
- [SPEC and data export](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/export/spec.py): `src/kiwi_scan/export/spec.py`
- [Live monitors and plots](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/monitor_concrete/queue_plotter.py): `src/kiwi_scan/monitor_concrete/queue_plotter.py`
- [Statistics and diagnostics](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/scan/stats_collector.py): `src/kiwi_scan/scan/stats_collector.py`

### Control-system interfaces

- [Generic scan IOC](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/ioc/controller.py): `src/kiwi_scan/ioc/controller.py`
- [PVA table server](https://github.com/hz-b/kiwi-scan/blob/master/src/kiwi_scan/ioc/pva_table.py): `src/kiwi_scan/ioc/pva_table.py`

### Other components

- **Engineer / API caller**

## Connections

- Engineer / API caller → Scan runner: runs scan
- Engineer / API caller → Scan construction API: calls API
- YAML configuration → Scan configuration models: parses into (evidence: `src/kiwi_scan/yaml_loader.py`)
- Scan runner → YAML configuration: loads (evidence: `src/kiwi_scan/cli/scan_runner.py`)
- Scan runner → Scan construction API: constructs scan (evidence: `src/kiwi_scan/cli/scan_runner.py`)
- Scan construction API → Scan type registry: selects type (evidence: `src/kiwi_scan/scan/tools.py`)
- Scan type registry → Scan engines: registers built-ins (evidence: `src/kiwi_scan/scan/registry.py`)
- Scan construction API → Scan coordination: creates scan (evidence: `src/kiwi_scan/scan/tools.py`)
- Scan engines → Scan coordination: uses coordination (evidence: `src/kiwi_scan/scan_concrete/para.py`)
- Scan coordination → Point data pipeline: assembles points (evidence: `src/kiwi_scan/scan/common.py`)
- Scan coordination → Actuator factory: creates actuators (evidence: `src/kiwi_scan/scan/common.py`)
- Actuator factory → Actuator backends: builds backend (evidence: `src/kiwi_scan/actuator/factory.py`)
- Actuator backends → EPICS PV access: uses PV access (evidence: `src/kiwi_scan/actuator_concrete/single_epics.py`)
- Scan coordination → Acquisition synchronization: synchronizes acquisition (evidence: `src/kiwi_scan/scan/common.py`)
- Scan coordination → Subscriptions and event routing: routes events (evidence: `src/kiwi_scan/scan/common.py`)
- Scan coordination → Scan triggers: fires triggers (evidence: `src/kiwi_scan/scan/common.py`)
- Scan coordination → Plugin registry: loads plugins (evidence: `src/kiwi_scan/scan/common.py`)
- Plugin registry → Built-in plugins: registers plugins (evidence: `src/kiwi_scan/plugin/registry.py`)
- Plugin framework → Scan coordination: accesses scan context
- Point data pipeline → Scan file output: provides point rows
- Scan file output → Manifest file management: records scan files
- Scan runner → Manifest file management: manages manifest (evidence: `src/kiwi_scan/cli/scan_runner.py`)
- Scan data loading → SPEC and data export: supplies scan data
- Scan coordination → Live monitors and plots: publishes monitor data
- Scan coordination → Statistics and diagnostics: collects statistics
- Engineer / API caller → Generic scan IOC: controls scans
- Generic scan IOC → Scan construction API: creates scan (evidence: `src/kiwi_scan/ioc/controller.py`)
- Generic scan IOC → Manifest file management: creates manifest (evidence: `src/kiwi_scan/ioc/controller.py`)
- PVA table server → Scan coordination: publishes scan data
