# hz-b/seq-quince architecture

> Architecture diagram of the GitHub repository hz-b/seq-quince, 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/seq-quince
- Repository: https://github.com/hz-b/seq-quince

## Overview

seq-quince is an asynchronous, YAML-configured scheduler for EPICS beamline devices. The main workflow loads and merges beamline configuration and presets, constructs devices, converts a selected preset into grouped move steps, then executes them with timeout and optional rollback handling. Snapshot capture and the varied built-in device types are distinct product capabilities. Source excerpts and the index support the principal orchestration; several device implementations and optional integrations are represented from README or index evidence rather than inspected in full.

Main entry points: [`src/seq_quince/device/factory.py`](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device/factory.py) (Device Factory), [`src/seq_quince/runner.py`](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/runner.py) (Run Operations), [`src/seq_quince/config_manager.py`](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/config_manager.py) (Config Manager), [`src/seq_quince/device/device_abs.py`](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device/device_abs.py) (Device Contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_manager["Config Manager<br/>[config_manager.py]"]
  node_yaml_loader["Template YAML Loader<br/>[loader.py]"]
  node_snapshot["Preset Snapshots<br/>[snapshot.py]"]
  node_tools["Config Utilities<br/>[tools.py]"]
end

subgraph group_orchestration["Sequence Execution"]
  node_scheduler_cli["Scheduler CLI"]
  node_device_cli["Device CLI<br/>[device_runner.py]"]
  node_runner["Run Operations<br/>[runner.py]"]
  node_sequence_builder["Sequence Builder<br/>[sequence.py]"]
  node_scheduler["Async Scheduler<br/>[scheduler.py]"]
end

subgraph group_devices["Device Runtime"]
  node_device_factory["Device Factory<br/>[factory.py]"]
  node_device_contract["Device Contract<br/>[device_abs.py]"]
  node_lifecycle["Resource Lifecycle<br/>[lifecycle.py]"]
end

subgraph group_integrations["Hardware Integrations"]
  node_actuator["Actuator Device<br/>[actuator.py]"]
  node_hexapod["Hexapod Device<br/>[hexapod.py]"]
  node_mono["Zero Order Mono<br/>[mono_zero_order.py]"]
  node_ophyd_motor["Ophyd Motor<br/>[ophyd_motor.py]"]
  node_scan["Scan Device<br/>[scan.py]"]
  node_sequence_device["PV Sequence<br/>[sequence.py]"]
  node_sim["Simulation Device<br/>[sim.py]"]
  node_toggle["Toggle Device<br/>[toggle.py]"]
  node_wait_condition["Wait Condition<br/>[wait_condition.py]"]
  node_option_lookup["Option Lookup<br/>[_option_lookup.py]"]
end

node_operator(("Operator"))
node_epics(("EPICS PVs"))
node_kiwi_scan["kiwi-scan"]

node_operator -->|"runs preset"| node_scheduler_cli
node_operator -->|"runs device"| node_device_cli
node_scheduler_cli -->|"dispatches to"| node_runner
node_device_cli -->|"dispatches to"| node_runner
node_runner -->|"loads config"| node_manager
node_manager -->|"renders and parses"| node_yaml_loader
node_manager -->|"merges presets"| node_snapshot
node_manager -->|"resolves config path"| node_tools
node_runner -->|"constructs devices"| node_device_factory
node_manager -->|"builds preset steps"| node_sequence_builder
node_runner -->|"builds single-device step"| node_sequence_builder
node_sequence_builder -->|"targets devices"| node_device_contract
node_runner -->|"executes steps"| node_scheduler
node_scheduler -->|"runs device steps"| node_device_contract
node_device_factory -->|"creates implementations"| node_device_contract
node_device_contract -->|"closes resources"| node_lifecycle
node_device_factory -->|"instantiates type"| node_actuator
node_device_factory -->|"instantiates type"| node_hexapod
node_device_factory -->|"instantiates type"| node_mono
node_device_factory -->|"instantiates type"| node_ophyd_motor
node_device_factory -->|"instantiates type"| node_scan
node_device_factory -->|"instantiates type"| node_sequence_device
node_device_factory -->|"instantiates type"| node_sim
node_device_factory -->|"instantiates type"| node_toggle
node_device_factory -->|"instantiates type"| node_wait_condition
node_mono -->|"uses options"| node_option_lookup
node_wait_condition -->|"uses options"| node_option_lookup
node_sequence_device -->|"reads and writes PVs"| node_epics
node_scan -->|"runs scans"| node_kiwi_scan
node_actuator -.->|"uses actuators"| node_kiwi_scan
node_hexapod -.->|"uses actuators"| node_kiwi_scan

click node_scheduler_cli "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/scheduler_runner.py"
click node_device_cli "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_runner.py"
click node_manager "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/config_manager.py"
click node_yaml_loader "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/loader.py"
click node_snapshot "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/snapshot.py"
click node_tools "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/tools.py"
click node_runner "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/runner.py"
click node_sequence_builder "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/sequence.py"
click node_scheduler "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/scheduler.py"
click node_device_factory "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device/factory.py"
click node_device_contract "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device/device_abs.py"
click node_lifecycle "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device/lifecycle.py"
click node_actuator "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/actuator.py"
click node_hexapod "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/hexapod.py"
click node_mono "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/mono_zero_order.py"
click node_ophyd_motor "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/ophyd_motor.py"
click node_scan "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/scan.py"
click node_sequence_device "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/sequence.py"
click node_sim "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/sim.py"
click node_toggle "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/toggle.py"
click node_wait_condition "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/wait_condition.py"
click node_option_lookup "https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/_option_lookup.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_manager,node_yaml_loader,node_snapshot,node_tools toneBlue
class node_scheduler_cli,node_device_cli,node_runner,node_sequence_builder,node_scheduler toneAmber
class node_device_factory,node_device_contract,node_lifecycle toneMint
class node_actuator,node_hexapod,node_mono,node_ophyd_motor,node_scan,node_sequence_device,node_sim,node_toggle,node_wait_condition,node_option_lookup toneRose
class node_operator,node_epics,node_kiwi_scan toneIndigo
```

## Components

### Configuration

- [Config Manager](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/config_manager.py): `src/seq_quince/config_manager.py`
- [Template YAML Loader](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/loader.py): `src/seq_quince/loader.py`
- [Preset Snapshots](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/snapshot.py): `src/seq_quince/snapshot.py`
- [Config Utilities](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/tools.py): `src/seq_quince/tools.py`

### Sequence Execution

- [Scheduler CLI](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/scheduler_runner.py): `src/seq_quince/scheduler_runner.py`
- [Device CLI](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_runner.py): `src/seq_quince/device_runner.py`
- [Run Operations](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/runner.py): `src/seq_quince/runner.py`
- [Sequence Builder](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/sequence.py): `src/seq_quince/sequence.py`
- [Async Scheduler](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/scheduler.py): `src/seq_quince/scheduler.py`

### Device Runtime

- [Device Factory](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device/factory.py): `src/seq_quince/device/factory.py`
- [Device Contract](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device/device_abs.py): `src/seq_quince/device/device_abs.py`
- [Resource Lifecycle](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device/lifecycle.py): `src/seq_quince/device/lifecycle.py`

### Hardware Integrations

- [Actuator Device](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/actuator.py): `src/seq_quince/device_concrete/actuator.py`
- [Hexapod Device](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/hexapod.py): `src/seq_quince/device_concrete/hexapod.py`
- [Zero Order Mono](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/mono_zero_order.py): `src/seq_quince/device_concrete/mono_zero_order.py`
- [Ophyd Motor](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/ophyd_motor.py): `src/seq_quince/device_concrete/ophyd_motor.py`
- [Scan Device](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/scan.py): `src/seq_quince/device_concrete/scan.py`
- [PV Sequence](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/sequence.py): `src/seq_quince/device_concrete/sequence.py`
- [Simulation Device](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/sim.py): `src/seq_quince/device_concrete/sim.py`
- [Toggle Device](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/toggle.py): `src/seq_quince/device_concrete/toggle.py`
- [Wait Condition](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/wait_condition.py): `src/seq_quince/device_concrete/wait_condition.py`
- [Option Lookup](https://github.com/hz-b/seq-quince/blob/master/src/seq_quince/device_concrete/_option_lookup.py): `src/seq_quince/device_concrete/_option_lookup.py`

### Other components

- **Operator**
- **EPICS PVs**
- **kiwi-scan**

## Connections

- Operator → Scheduler CLI: runs preset (evidence: `README.md`)
- Operator → Device CLI: runs device (evidence: `README.md`)
- Scheduler CLI → Run Operations: dispatches to (evidence: `src/seq_quince/scheduler_runner.py`)
- Device CLI → Run Operations: dispatches to (evidence: `src/seq_quince/device_runner.py`)
- Run Operations → Config Manager: loads config (evidence: `src/seq_quince/runner.py`)
- Config Manager → Template YAML Loader: renders and parses (evidence: `src/seq_quince/config_manager.py`)
- Config Manager → Preset Snapshots: merges presets (evidence: `src/seq_quince/config_manager.py`)
- Config Manager → Config Utilities: resolves config path (evidence: `src/seq_quince/config_manager.py`)
- Run Operations → Device Factory: constructs devices (evidence: `src/seq_quince/runner.py`)
- Config Manager → Sequence Builder: builds preset steps (evidence: `src/seq_quince/config_manager.py`)
- Run Operations → Sequence Builder: builds single-device step (evidence: `src/seq_quince/runner.py`)
- Sequence Builder → Device Contract: targets devices (evidence: `src/seq_quince/sequence.py`)
- Run Operations → Async Scheduler: executes steps (evidence: `src/seq_quince/runner.py`)
- Async Scheduler → Device Contract: runs device steps (evidence: `src/seq_quince/scheduler.py`)
- Device Factory → Device Contract: creates implementations (evidence: `src/seq_quince/device/factory.py`)
- Device Contract → Resource Lifecycle: closes resources (evidence: `src/seq_quince/device/device_abs.py`)
- Device Factory → Actuator Device: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Device Factory → Hexapod Device: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Device Factory → Zero Order Mono: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Device Factory → Ophyd Motor: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Device Factory → Scan Device: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Device Factory → PV Sequence: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Device Factory → Simulation Device: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Device Factory → Toggle Device: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Device Factory → Wait Condition: instantiates type (evidence: `src/seq_quince/device/factory.py`)
- Zero Order Mono → Option Lookup: uses options (evidence: `src/seq_quince/device_concrete/mono_zero_order.py`)
- Wait Condition → Option Lookup: uses options (evidence: `src/seq_quince/device_concrete/wait_condition.py`)
- PV Sequence → EPICS PVs: reads and writes PVs (evidence: `src/seq_quince/device_concrete/sequence.py`)
- Scan Device → kiwi-scan: runs scans (evidence: `src/seq_quince/device_concrete/scan.py`)
- Actuator Device → kiwi-scan: uses actuators (evidence: `README.md`)
- Hexapod Device → kiwi-scan: uses actuators (evidence: `README.md`)
