# dune-daq/drunc architecture

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

- Interactive diagram: https://gitdiagram.com/dune-daq/drunc
- Repository: https://github.com/dune-daq/drunc

## Overview

1. **Overall shape**
   - `drunc` is a Python-based run-control framework for DUNE DAQ.
   - Its architecture is split into a **controller plane**, a **process-management plane**, a **session-management layer**, and a set of **shared runtime services** like FSM, broadcasting, authorization, and connectivity helpers.
   - The system is highly **configuration-driven**: runtime behavior is defined by config files and FSM/action definitions rather than hard-coded application logic.

2. **Primary user entry points**
   - The main executable apps live under `src/drunc/apps/`.
   - Key front ends are `controller.py`, `pm.py`, `session_manager.py`, and `unified_shell.py`.
   - There are also admin/utility tools for SSH config validation/diagnostics and a `fake_daqapp_rest.py` for testing REST-based child interactions.

3. **Controller subsystem**
   - `src/drunc/controller/` is the orchestration core.
   - It manages a tree of child nodes through `children_interface/`, with support for both **gRPC children** and **REST API children**.
   - The controller owns stateful behavior (`stateful_node.py`) and exposes an interface layer for commands, shell integration, and driver logic.
   - This is the main place where run-control commands are translated into coordinated actions on downstream nodes.

4. **Process manager subsystem**
   - `src/drunc/process_manager/` is responsible for starting, stopping, and supervising DAQ processes.
   - It supports multiple backends: **SSH-based execution** and **Kubernetes-based execution**.
   - The interface layer mirrors the controller’s structure: CLI/shell command objects, context, and a driver-facing implementation.
   - This subsystem is the boundary between run-control intent and actual process lifecycle management.

5. **Session management**
   - `src/drunc/session_manager/` tracks and coordinates run sessions.
   - It provides its own service, driver, and interface layer, indicating it is an independently addressable control service rather than just an internal helper.
   - In the architecture, session management sits alongside controller and process manager as a first-class operational service.

6. **Finite state machine as the run-control model**
   - `src/drunc/fsm/` encodes the operational lifecycle of the DAQ.
   - It contains the FSM core, transitions, action factory, and a collection of actions that plug in run-specific behavior.
   - Actions include run registry and logbook integrations, thread pinning, timing/trigger-related behavior, and user-provided run-number sources.
   - This FSM layer is the canonical source of truth for allowed state transitions and run phases.

7. **Broadcast/notification path**
   - `src/drunc/broadcast/` provides a separate publish/notify path from command execution.
   - It has both **server-side senders** and **client-side handlers**, with support for **gRPC** and **Kafka**-style stdout broadcast handlers.
   - This is the outward-facing feedback channel used to propagate status and events to operators or monitoring consumers.

8. **Security and access control**
   - `src/drunc/authoriser/` implements authorization hooks and decorators.
   - The presence of a dummy authorizer suggests the authorization layer is pluggable and can be swapped or disabled in some deployments.
   - In the architecture diagram, this sits as a cross-cutting gate in front of command endpoints rather than as a standalone service.

9. **Connectivity and child-process plumbing**
   - `src/drunc/connectivity_service/` and `src/drunc/processes/` handle lower-level connectivity and process lifetime concerns.
   - These packages support the controller/process-manager interaction with managed children and SSH-launched processes.
   - They form the glue between higher-level orchestration and the actual transport/process mechanics.

10. **Protocols and service boundaries**
   - The repository is centered on **gRPC** for service communication, with some **REST** support for child nodes and test doubles.
   - Shell-facing interfaces exist for controller, process manager, and unified shell, which implies the operator workflow is interactive as well as service-driven.
   - `src/drunc/grpc_testing_tools/` includes test servers, proto definitions, and connection helpers, reinforcing that gRPC is a core architectural boundary.

11. **Configuration and deployment inputs**
   - The repo contains many config artifacts under `src/drunc/data/` and `config/tests/`.
   - There are JSON schemas and canned deployment configs for SSH and K8s process-manager setups, plus XML configs used in tests.
   - This suggests deployments are assembled from config rather than compiled into a fixed topology.

12. **Support tooling and verification**
   - The extensive `tests/` tree mirrors the main subsystems almost one-for-one, which shows the architecture is decomposed into independently testable modules.
   - GitHub Actions cover linting, pytest, docs checks, and docs deployment.
   - Documentation is a first-class part of the repo structure, with subsystem-specific docs for controller, process manager, FSM, messaging format, and unified shell.

Main entry points: [`src/drunc/controller/controller.py`](https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/controller.py) (Controller core), [`src/drunc/process_manager/process_manager.py`](https://github.com/dune-daq/drunc/blob/develop/src/drunc/process_manager/process_manager.py) (PM core), [`src/drunc/apps/unified_shell.py`](https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/unified_shell.py) (Unified shell), [`src/drunc/session_manager/session_manager.py`](https://github.com/dune-daq/drunc/blob/develop/src/drunc/session_manager/session_manager.py) (Session core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Entry points"]
  node_src_drunc_apps_controller_py["Controller app<br/>entrypoint<br/>[controller.py]"]
  node_src_drunc_apps_pm_py["PM app<br/>entrypoint<br/>[pm.py]"]
  node_src_drunc_apps_session_manager_py["Session app<br/>entrypoint<br/>[session_manager.py]"]
  node_src_drunc_apps_unified_shell_py["Unified shell<br/>entrypoint<br/>[unified_shell.py]"]
end

subgraph group_controller["Controller plane"]
  node_src_drunc_controller_controller_py["Controller core<br/>orchestrator<br/>[controller.py]"]
  node_src_drunc_controller_stateful_node_py["State node<br/>state machine host<br/>[stateful_node.py]"]
  node_src_drunc_controller_children_interface_grpc_child_py["gRPC child<br/>child adapter<br/>[grpc_child.py]"]
  node_src_drunc_controller_children_interface_rest_api_child_py["REST child<br/>child adapter<br/>[rest_api_child.py]"]
end

subgraph group_pm["Process manager"]
  node_src_drunc_process_manager_process_manager_py["PM core<br/>lifecycle manager<br/>[process_manager.py]"]
  node_src_drunc_process_manager_ssh_process_manager_py["SSH backend"]
  node_src_drunc_process_manager_k8s_process_manager_py["K8s backend"]
end

subgraph group_session["Session management"]
  node_src_drunc_session_manager_session_manager_py["Session core<br/>session service<br/>[session_manager.py]"]
  node_src_drunc_session_manager_interface_session_manager_py["Session API<br/>service interface<br/>[session_manager.py]"]
end

subgraph group_fsm["FSM runtime"]
  node_src_drunc_fsm_core_py["FSM core<br/>state machine<br/>[core.py]"]
  node_src_drunc_fsm_transition_py["Transitions<br/>transition model<br/>[transition.py]"]
  node_src_drunc_fsm_action_factory_py["Action factory<br/>action wiring<br/>[action_factory.py]"]
  node_src_drunc_fsm_actions_db_run_registry_py["Run registry<br/>fsm action<br/>[db_run_registry.py]"]
end

subgraph group_broadcast["Broadcasting"]
  node_src_drunc_broadcast_server_grpc_servicer_py["Broadcast server<br/>notify service<br/>[grpc_servicer.py]"]
  node_src_drunc_broadcast_client_broadcast_handler_py["Broadcast client<br/>notify client"]
end

subgraph group_security["Security"]
  node_src_drunc_authoriser_decorators_py["Auth decorators<br/>policy gate<br/>[decorators.py]"]
end

subgraph group_plumbing["Plumbing"]
  node_src_drunc_connectivity_service_client_py["Connectivity client<br/>link helper<br/>[client.py]"]
  node_src_drunc_processes_ssh_process_lifetime_manager_py["Process lifetime<br/>lifecycle plumbing"]
end

subgraph group_grpc["gRPC tools"]
  node_src_drunc_grpc_testing_tools_test_services_proto["Test proto<br/>grpc schema"]
end

node_src_drunc_apps_controller_py -->|"starts"| node_src_drunc_controller_controller_py
node_src_drunc_apps_pm_py -->|"starts"| node_src_drunc_process_manager_process_manager_py
node_src_drunc_apps_session_manager_py -->|"starts"| node_src_drunc_session_manager_session_manager_py
node_src_drunc_apps_unified_shell_py -->|"connects"| node_src_drunc_controller_controller_py
node_src_drunc_apps_unified_shell_py -->|"connects"| node_src_drunc_process_manager_process_manager_py
node_src_drunc_apps_unified_shell_py -->|"connects"| node_src_drunc_session_manager_session_manager_py
node_src_drunc_controller_controller_py -->|"tracks state"| node_src_drunc_controller_stateful_node_py
node_src_drunc_controller_controller_py -->|"drives"| node_src_drunc_controller_children_interface_grpc_child_py
node_src_drunc_controller_controller_py -->|"drives"| node_src_drunc_controller_children_interface_rest_api_child_py
node_src_drunc_controller_controller_py -->|"gated by"| node_src_drunc_authoriser_decorators_py
node_src_drunc_controller_controller_py -->|"uses"| node_src_drunc_connectivity_service_client_py
node_src_drunc_process_manager_process_manager_py -->|"backend"| node_src_drunc_process_manager_ssh_process_manager_py
node_src_drunc_process_manager_process_manager_py -->|"backend"| node_src_drunc_process_manager_k8s_process_manager_py
node_src_drunc_process_manager_process_manager_py -->|"uses"| node_src_drunc_processes_ssh_process_lifetime_manager_py
node_src_drunc_process_manager_process_manager_py -->|"gated by"| node_src_drunc_authoriser_decorators_py
node_src_drunc_session_manager_session_manager_py -->|"exposes"| node_src_drunc_session_manager_interface_session_manager_py
node_src_drunc_fsm_core_py -->|"defines"| node_src_drunc_fsm_transition_py
node_src_drunc_fsm_core_py -->|"invokes"| node_src_drunc_fsm_action_factory_py
node_src_drunc_fsm_action_factory_py -->|"creates"| node_src_drunc_fsm_actions_db_run_registry_py
node_src_drunc_broadcast_server_grpc_servicer_py -->|"delivers to"| node_src_drunc_broadcast_client_broadcast_handler_py
node_src_drunc_grpc_testing_tools_test_services_proto -.->|"tests"| node_src_drunc_controller_controller_py
node_src_drunc_grpc_testing_tools_test_services_proto -.->|"tests"| node_src_drunc_process_manager_process_manager_py

click node_src_drunc_apps_controller_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/controller.py"
click node_src_drunc_apps_pm_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/pm.py"
click node_src_drunc_apps_session_manager_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/session_manager.py"
click node_src_drunc_apps_unified_shell_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/unified_shell.py"
click node_src_drunc_controller_controller_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/controller.py"
click node_src_drunc_controller_stateful_node_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/stateful_node.py"
click node_src_drunc_controller_children_interface_grpc_child_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/children_interface/grpc_child.py"
click node_src_drunc_controller_children_interface_rest_api_child_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/children_interface/rest_api_child.py"
click node_src_drunc_process_manager_process_manager_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/process_manager/process_manager.py"
click node_src_drunc_process_manager_ssh_process_manager_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/process_manager/ssh_process_manager.py"
click node_src_drunc_process_manager_k8s_process_manager_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/process_manager/k8s_process_manager.py"
click node_src_drunc_session_manager_session_manager_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/session_manager/session_manager.py"
click node_src_drunc_session_manager_interface_session_manager_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/session_manager/interface/session_manager.py"
click node_src_drunc_fsm_core_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/fsm/core.py"
click node_src_drunc_fsm_transition_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/fsm/transition.py"
click node_src_drunc_fsm_action_factory_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/fsm/action_factory.py"
click node_src_drunc_fsm_actions_db_run_registry_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/fsm/actions/db_run_registry.py"
click node_src_drunc_broadcast_server_grpc_servicer_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/broadcast/server/grpc_servicer.py"
click node_src_drunc_broadcast_client_broadcast_handler_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/broadcast/client/broadcast_handler.py"
click node_src_drunc_authoriser_decorators_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/authoriser/decorators.py"
click node_src_drunc_connectivity_service_client_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/connectivity_service/client.py"
click node_src_drunc_processes_ssh_process_lifetime_manager_py "https://github.com/dune-daq/drunc/blob/develop/src/drunc/processes/ssh_process_lifetime_manager.py"
click node_src_drunc_grpc_testing_tools_test_services_proto "https://github.com/dune-daq/drunc/blob/develop/src/drunc/grpc_testing_tools/test_services.proto"

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_src_drunc_apps_controller_py,node_src_drunc_apps_pm_py,node_src_drunc_apps_session_manager_py,node_src_drunc_apps_unified_shell_py,node_src_drunc_authoriser_decorators_py toneBlue
class node_src_drunc_controller_controller_py,node_src_drunc_controller_stateful_node_py,node_src_drunc_controller_children_interface_grpc_child_py,node_src_drunc_controller_children_interface_rest_api_child_py,node_src_drunc_connectivity_service_client_py,node_src_drunc_processes_ssh_process_lifetime_manager_py toneAmber
class node_src_drunc_process_manager_process_manager_py,node_src_drunc_process_manager_ssh_process_manager_py,node_src_drunc_process_manager_k8s_process_manager_py,node_src_drunc_grpc_testing_tools_test_services_proto toneMint
class node_src_drunc_session_manager_session_manager_py,node_src_drunc_session_manager_interface_session_manager_py toneRose
class node_src_drunc_fsm_core_py,node_src_drunc_fsm_transition_py,node_src_drunc_fsm_action_factory_py,node_src_drunc_fsm_actions_db_run_registry_py toneIndigo
class node_src_drunc_broadcast_server_grpc_servicer_py,node_src_drunc_broadcast_client_broadcast_handler_py toneTeal
```

## Components

### Entry points

Operator-facing executables and shell front ends.

- [Controller app](https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/controller.py): entrypoint · Main controller executable. · `src/drunc/apps/controller.py`
- [PM app](https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/pm.py): entrypoint · Process-manager executable. · `src/drunc/apps/pm.py`
- [Session app](https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/session_manager.py): entrypoint · Session-manager executable. · `src/drunc/apps/session_manager.py`
- [Unified shell](https://github.com/dune-daq/drunc/blob/develop/src/drunc/apps/unified_shell.py): entrypoint · Operator shell combining major services. · `src/drunc/apps/unified_shell.py`

### Controller plane

Orchestrates child nodes and command execution.

- [Controller core](https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/controller.py): orchestrator · Coordinates commands and downstream state. · `src/drunc/controller/controller.py`
- [State node](https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/stateful_node.py): state machine host · Holds controller state and transitions. · `src/drunc/controller/stateful_node.py`
- [gRPC child](https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/children_interface/grpc_child.py): child adapter · Child-node adapter over gRPC. · `src/drunc/controller/children_interface/grpc_child.py`
- [REST child](https://github.com/dune-daq/drunc/blob/develop/src/drunc/controller/children_interface/rest_api_child.py): child adapter · Child-node adapter over REST. · `src/drunc/controller/children_interface/rest_api_child.py`

### Process manager

Starts, stops, and supervises DAQ processes.

- [PM core](https://github.com/dune-daq/drunc/blob/develop/src/drunc/process_manager/process_manager.py): lifecycle manager · Coordinates process lifecycle operations. · `src/drunc/process_manager/process_manager.py`
- [SSH backend](https://github.com/dune-daq/drunc/blob/develop/src/drunc/process_manager/ssh_process_manager.py): backend · Launches and supervises processes over SSH. · `src/drunc/process_manager/ssh_process_manager.py`
- [K8s backend](https://github.com/dune-daq/drunc/blob/develop/src/drunc/process_manager/k8s_process_manager.py): backend · Launches and supervises processes in Kubernetes. · `src/drunc/process_manager/k8s_process_manager.py`

### Session management

Tracks and coordinates operational sessions.

- [Session core](https://github.com/dune-daq/drunc/blob/develop/src/drunc/session_manager/session_manager.py): session service · Owns session lifecycle and coordination. · `src/drunc/session_manager/session_manager.py`
- [Session API](https://github.com/dune-daq/drunc/blob/develop/src/drunc/session_manager/interface/session_manager.py): service interface · Session-manager interface layer. · `src/drunc/session_manager/interface/session_manager.py`

### FSM runtime

Defines lifecycle states, transitions, and actions.

- [FSM core](https://github.com/dune-daq/drunc/blob/develop/src/drunc/fsm/core.py): state machine · Defines legal run-control states. · `src/drunc/fsm/core.py`
- [Transitions](https://github.com/dune-daq/drunc/blob/develop/src/drunc/fsm/transition.py): transition model · Encodes allowed lifecycle transitions. · `src/drunc/fsm/transition.py`
- [Action factory](https://github.com/dune-daq/drunc/blob/develop/src/drunc/fsm/action_factory.py): action wiring · Instantiates FSM actions from configuration. · `src/drunc/fsm/action_factory.py`
- [Run registry](https://github.com/dune-daq/drunc/blob/develop/src/drunc/fsm/actions/db_run_registry.py): fsm action · Example action for run registration. · `src/drunc/fsm/actions/db_run_registry.py`

### Broadcasting

Notification and status dissemination channels.

- [Broadcast server](https://github.com/dune-daq/drunc/blob/develop/src/drunc/broadcast/server/grpc_servicer.py): notify service · Publishes runtime events to clients. · `src/drunc/broadcast/server/grpc_servicer.py`
- [Broadcast client](https://github.com/dune-daq/drunc/blob/develop/src/drunc/broadcast/client/broadcast_handler.py): notify client · Consumes broadcast events on the client side. · `src/drunc/broadcast/client/broadcast_handler.py`

### Security

Authorization hooks and policy plumbing.

- [Auth decorators](https://github.com/dune-daq/drunc/blob/develop/src/drunc/authoriser/decorators.py): policy gate · Authorization hooks around protected operations. · `src/drunc/authoriser/decorators.py`

### Plumbing

Connectivity and process lifetime support.

- [Connectivity client](https://github.com/dune-daq/drunc/blob/develop/src/drunc/connectivity_service/client.py): link helper · Connectivity helper for controller/process links. · `src/drunc/connectivity_service/client.py`
- [Process lifetime](https://github.com/dune-daq/drunc/blob/develop/src/drunc/processes/ssh_process_lifetime_manager.py): lifecycle plumbing · Manages SSH-launched process lifetime. · `src/drunc/processes/ssh_process_lifetime_manager.py`

### gRPC tools

Service testing and connection scaffolding.

- [Test proto](https://github.com/dune-daq/drunc/blob/develop/src/drunc/grpc_testing_tools/test_services.proto): grpc schema · Shared test service definitions and stubs. · `src/drunc/grpc_testing_tools/test_services.proto`

## Connections

- Controller app → Controller core: starts · Controller executable boots the orchestration core.
- PM app → PM core: starts · Process-manager executable boots the lifecycle service.
- Session app → Session core: starts · Session executable boots the session service.
- Unified shell → Controller core: connects · Unified shell can target controller operations.
- Unified shell → PM core: connects · Unified shell can target process-manager operations.
- Unified shell → Session core: connects · Unified shell can target session operations.
- Controller core → State node: tracks state · Controller behavior is anchored in node state.
- Controller core → gRPC child: drives · Controller issues commands to gRPC children.
- Controller core → REST child: drives · Controller issues commands to REST children.
- Controller core → Auth decorators: gated by · Controller endpoints are authorization-protected.
- Controller core → Connectivity client: uses · Controller relies on connectivity helpers.
- PM core → SSH backend: backend · SSH is one process-management implementation.
- PM core → K8s backend: backend · Kubernetes is another process-management implementation.
- PM core → Process lifetime: uses · Process manager delegates lifecycle mechanics.
- PM core → Auth decorators: gated by · Process-manager endpoints are authorization-protected.
- Session core → Session API: exposes · Session core is surfaced through an interface layer.
- FSM core → Transitions: defines · FSM core depends on transition definitions.
- FSM core → Action factory: invokes · State changes trigger configured actions.
- Action factory → Run registry: creates · Representative run-specific action is wired in.
- Broadcast server → Broadcast client: delivers to · Server-side broadcast is consumed by clients.
- Test proto → Controller core: tests · gRPC test services exercise controller-style boundaries.
- Test proto → PM core: tests · gRPC test services exercise process-manager boundaries.
