# kenichisakai-git/grams-tof architecture

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

- Interactive diagram: https://gitdiagram.com/kenichisakai-git/grams-tof
- Repository: https://github.com/kenichisakai-git/grams-tof

## Overview

1. **Repository shape**
   - This is a monorepo for the GRAMS Time-of-Flight stack, split into three architectural layers: **FlightOps** for DAQ/runtime control, **Analysis** for offline ROOT-based processing, and **GroundOps** for monitoring and operations.
   - `Common` provides shared CMake logic and code-generation helpers used across the project.

2. **Build and integration model**
   - The project is built with **CMake** and produces both libraries and command-line tools.
   - It vendors several dependencies directly under `FlightOps/external`, including **fmt**, **CLI11**, **inih**, **pybind11**, and multiple GRAMS/Tofpet-specific support libraries.
   - ROOT and Boost.Python are important architectural dependencies because they connect the C++ runtime to analysis/serialization and Python integration.

3. **FlightOps: main DAQ runtime**
   - `FlightOps/include` and `FlightOps/src` define the central C++ library, with the `GRAMS_TOF_*` namespace prefix.
   - The core responsibilities are:
     - DAQ orchestration (`GRAMS_TOF_DAQController`, `GRAMS_TOF_DAQManager`)
     - networking/client-server communication (`Client`, `EventClient`, `EventServer`, `CommandClient`, `CommandServer`)
     - protocol encoding/dispatch (`CommandCodec`, `CommandDispatch`, `MonitorCodec`)
     - config/logging/runtime support (`Config`, `Logger`, `RuntimeError`, `FDManager`)
     - data conversion and analysis hooks (`Analyzer`, `RootConverter`, `PythonIntegration`)

4. **FlightOps data path**
   - The runtime ingests detector/DAQ data, moves it through a command/event protocol layer, and exposes it to downstream consumers.
   - Event and command traffic are separated: command paths control hardware and system state, while event paths carry acquisition data.
   - Monitor data is encoded separately from event payloads, which supports telemetry/health reporting without interfering with acquisition flow.

5. **Hardware and low-level DAQ boundary**
   - `FlightOps/external/kernel` contains a kernel driver (`psdaq`) and udev rules, showing that the repository spans both user-space control and low-level device access.
   - `FlightOps/external/daqd` provides a lower-level DAQ server/client implementation and protocol support, acting as a boundary between hardware-facing frame servers and the higher-level GRAMS_TOF runtime.
   - `FlightOps/external/rawdata` handles raw event reading/writing and shared-memory transport, which is the likely handoff point for acquisition data before conversion.

6. **Operational and calibration tooling in FlightOps**
   - `FlightOps/external/scripts` and `FlightOps/external/scripts_c` form a calibration/commissioning toolchain.
   - The Python scripts handle system startup, power, threshold, TDC/QDC calibration, temperature reads, and stress tests.
   - The C++ tools wrap those workflows into compiled executables for threshold, TDC, QDC, and raw conversion processing.
   - These tools are driven by configuration files in TSV/INI form under `FlightOps/external/config`.

7. **Python and native extension boundary**
   - `FlightOps/external/pybind11` and `FlightOps/external/petsys` indicate a mixed-language environment where Python is used for system operations and hardware control, while performance-sensitive paths stay in C++.
   - `GRAMS_TOF_PythonIntegration` is the explicit bridge for invoking or embedding Python from the C++ runtime.

8. **Analysis subsystem: offline ROOT pipeline**
   - `Analysis` is a separate library focused on offline processing of time-of-flight data.
   - It centers on ROOT-friendly data structures and conversions:
     - stage-1 and stage-2 tree models (`TOF_TreeDataStg1`, `TOF_TreeDataStg2`)
     - conversion logic (`TOF_ConvertStg1toStg2`)
     - channel mapping and calibration (`TOF_ChannelConversion`, `TOF_TdcQdcCalibration`, `TOF_DiscriminatorCalibation`)
     - coincidence/event aggregation (`TOF_CoincidenceEvents`, `TOF_CoincidenceChannelInfo`)
     - fitting, parameter scans, and attributes (`TOF_Fitting`, `TOF_ParameterScan`, `TOF_Attributes`)

9. **Analysis execution modes**
   - `Analysis/macro` contains ROOT macros for interactive or batch study: plotting raw data, coincidence plots, bias scans, and event-building scripts.
   - `Analysis/scripts_c` wraps key analysis pipelines into compiled tools, mirroring the macro functionality but with a more structured CLI build path.
   - This layer consumes data produced by FlightOps/raw readers and emits derived ROOT trees, QA outputs, and calibration results.

10. **GroundOps: monitoring and service integration**
   - `GroundOps` is the ops-facing subsystem.
   - `scripts/setup_db.py` and `sql/create_tof_monitor.sql` define the monitoring database schema and bootstrap path.
   - `scripts/tof_bridge.py` plus the `systemd/tof-bridge.service` file indicate a persistent bridge process that ingests telemetry and publishes it into the monitor stack.
   - `grafana/TOF_metric-*.json` shows a prebuilt Grafana dashboard for visualization.

11. **Operational flow across the repo**
   - The overall flow is: detector/hardware input → FlightOps DAQ/runtime → raw event capture and protocol handling → Analysis for calibration/QA and ROOT-based studies → GroundOps for telemetry storage and dashboarding.
   - FlightOps is the live control plane; Analysis is the offline science/QA plane; GroundOps is the observability plane.

12. **Key architectural boundaries to show in a diagram**
   - User-space control vs kernel/device access
   - Acquisition/event transport vs command/control transport
   - Online DAQ vs offline analysis
   - Data processing vs monitoring/ops
   - C++ performance code vs Python orchestration scripts

13. **Repo-specific implementation style**
   - The codebase is heavily modular, with each subsystem split into `include`, `src`, and `tools` or `scripts` directories.
   - This suggests reusable libraries with thin executable front-ends, rather than a monolithic application.
   - The repeated use of generated linkage/linkdef files and ROOT macros reinforces that serialization and analysis are first-class concerns, not add-ons.

Main entry points: [`FlightOps/include`](https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/include) (FlightOps core), [`Analysis/include`](https://github.com/kenichisakai-git/grams-tof/tree/main/Analysis/include) (Analysis core), [`GroundOps/scripts/tof_bridge.py`](https://github.com/kenichisakai-git/grams-tof/blob/main/GroundOps/scripts/tof_bridge.py) (Telemetry bridge), [`Common/cmake`](https://github.com/kenichisakai-git/grams-tof/tree/main/Common/cmake) (Common CMake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_common["Common"]
  node_common_cmake["Common CMake<br/>build helpers"]
  node_common_utils["LinkDef tools<br/>codegen tools"]
end

subgraph group_grp_flightops["FlightOps"]
  node_flightops_lib["FlightOps core<br/>daq runtime"]
  node_flightops_controller["DAQ control<br/>orchestration"]
  node_flightops_comm["Protocols<br/>transport/protocol"]
  node_flightops_clients["Clients/servers<br/>network io"]
  node_flightops_runtime["Runtime support<br/>support libs"]
  node_flightops_bridge["Python bridge<br/>language bridge"]
  node_flightops_conversion["Data convert<br/>data path"]
  node_flightops_tools["DAQ tools<br/>cli tools"]
end

subgraph group_grp_analysis["Analysis"]
  node_analysis_lib["Analysis core<br/>offline analysis"]
  node_analysis_trees["Tree models<br/>root models"]
  node_analysis_calib["Calibration<br/>analysis calib"]
  node_analysis_events["Coincidence QA<br/>event aggregation"]
  node_analysis_macros["ROOT macros<br/>study scripts"]
  node_analysis_tools["Analysis tools<br/>cli tools"]
end

subgraph group_grp_groundops["GroundOps"]
  node_groundops_stack["GroundOps<br/>ops stack"]
  node_groundops_bridge["Telemetry bridge<br/>[tof_bridge.py]"]
  node_groundops_db[("Monitor DB<br/>sql/schema")]
  node_groundops_dashboard["Grafana dashboard<br/>ops visualization"]
end

subgraph group_grp_vendor["Vendored deps"]
  node_flightops_external_raw[("Raw data<br/>raw io")]
  node_flightops_external_daqd["daqd<br/>device server"]
  node_flightops_external_kernel["psdaq driver<br/>kernel device"]
  node_deps_root_boost(("ROOT/Boost.Python<br/>external deps"))
  node_deps_fmt_cli11(("fmt/CLI11<br/>external deps<br/>[fmt-7.1.3]"))
end

node_repo["grams-tof<br/>monorepo"]

node_repo -->|"build logic"| node_common_cmake
node_repo -->|"runtime layer"| node_flightops_lib
node_repo -->|"offline layer"| node_analysis_lib
node_repo -->|"ops layer"| node_groundops_stack
node_common_cmake -->|"cmake support"| node_flightops_lib
node_common_cmake -->|"cmake support"| node_analysis_lib
node_common_utils -.->|"linkdefs"| node_analysis_macros
node_flightops_lib -->|"orchestrates"| node_flightops_controller
node_flightops_lib -->|"defines"| node_flightops_comm
node_flightops_lib -->|"provides"| node_flightops_clients
node_flightops_lib -->|"supports"| node_flightops_runtime
node_flightops_lib -->|"embeds python"| node_flightops_bridge
node_flightops_lib -->|"exports data"| node_flightops_conversion
node_flightops_tools -->|"fronts"| node_flightops_lib
node_flightops_clients -->|"connects to"| node_flightops_external_daqd
node_flightops_external_daqd -->|"drives hardware"| node_flightops_external_kernel
node_flightops_external_raw -->|"hand-off"| node_flightops_conversion
node_flightops_external_raw -->|"feeds"| node_analysis_lib
node_analysis_lib -->|"models"| node_analysis_trees
node_analysis_lib -->|"calibrates"| node_analysis_calib
node_analysis_lib -->|"aggregates"| node_analysis_events
node_analysis_macros -->|"uses"| node_analysis_lib
node_analysis_tools -->|"wraps"| node_analysis_lib
node_analysis_lib -->|"depends on"| node_deps_root_boost
node_flightops_bridge -->|"depends on"| node_deps_root_boost
node_flightops_lib -->|"depends on"| node_deps_fmt_cli11
node_groundops_stack -->|"runs"| node_groundops_bridge
node_groundops_bridge -->|"writes"| node_groundops_db
node_groundops_bridge -->|"visualized by"| node_groundops_dashboard
node_flightops_lib -.->|"emits telemetry"| node_groundops_bridge
node_analysis_lib -.->|"qa results"| node_groundops_db

click node_common_cmake "https://github.com/kenichisakai-git/grams-tof/tree/main/Common/cmake"
click node_common_utils "https://github.com/kenichisakai-git/grams-tof/tree/main/Common/utils"
click node_flightops_lib "https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/include"
click node_flightops_controller "https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_DAQController.cpp"
click node_flightops_comm "https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_CommandCodec.cpp"
click node_flightops_clients "https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_Client.cpp"
click node_flightops_runtime "https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_Config.cpp"
click node_flightops_bridge "https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_PythonIntegration.cpp"
click node_flightops_conversion "https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_RootConverter.cpp"
click node_flightops_tools "https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/tools"
click node_flightops_external_raw "https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/external/rawdata"
click node_flightops_external_daqd "https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/external/daqd"
click node_flightops_external_kernel "https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/external/kernel"
click node_analysis_lib "https://github.com/kenichisakai-git/grams-tof/tree/main/Analysis/include"
click node_analysis_trees "https://github.com/kenichisakai-git/grams-tof/blob/main/Analysis/src/TOF_TreeDataStg1.cpp"
click node_analysis_calib "https://github.com/kenichisakai-git/grams-tof/blob/main/Analysis/src/TOF_TdcQdcCalibration.cpp"
click node_analysis_events "https://github.com/kenichisakai-git/grams-tof/blob/main/Analysis/src/TOF_CoincidenceEvents.cpp"
click node_analysis_macros "https://github.com/kenichisakai-git/grams-tof/tree/main/Analysis/macro"
click node_analysis_tools "https://github.com/kenichisakai-git/grams-tof/tree/main/Analysis/scripts_c"
click node_groundops_stack "https://github.com/kenichisakai-git/grams-tof/tree/main/GroundOps"
click node_groundops_bridge "https://github.com/kenichisakai-git/grams-tof/blob/main/GroundOps/scripts/tof_bridge.py"
click node_groundops_db "https://github.com/kenichisakai-git/grams-tof/blob/main/GroundOps/sql/create_tof_monitor.sql"
click node_groundops_dashboard "https://github.com/kenichisakai-git/grams-tof/blob/main/GroundOps/grafana/TOF_metric-1772838555610.json"
click node_deps_fmt_cli11 "https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/external/fmt-7.1.3"

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_common_cmake,node_common_utils toneBlue
class node_flightops_lib,node_flightops_controller,node_flightops_comm,node_flightops_clients,node_flightops_runtime,node_flightops_bridge,node_flightops_conversion,node_flightops_tools toneAmber
class node_analysis_lib,node_analysis_trees,node_analysis_calib,node_analysis_events,node_analysis_macros,node_analysis_tools toneMint
class node_groundops_stack,node_groundops_bridge,node_groundops_db,node_groundops_dashboard toneRose
class node_flightops_external_raw,node_flightops_external_daqd,node_flightops_external_kernel,node_deps_root_boost,node_deps_fmt_cli11 toneIndigo
class node_repo toneNeutral
```

## Components

### Common

Shared CMake and generation helpers

- [Common CMake](https://github.com/kenichisakai-git/grams-tof/tree/main/Common/cmake): build helpers · Shared CMake configuration and package support · `Common/cmake`
- [LinkDef tools](https://github.com/kenichisakai-git/grams-tof/tree/main/Common/utils): codegen tools · Helpers for ROOT linkdef generation · `Common/utils`

### FlightOps

Live DAQ runtime and device boundary

- [FlightOps core](https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/include): daq runtime · Central C++ runtime library for control and data flow · `FlightOps/include`
- [DAQ control](https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_DAQController.cpp): orchestration · Coordinates acquisition lifecycle and system state · `FlightOps/src/GRAMS_TOF_DAQController.cpp`
- [Protocols](https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_CommandCodec.cpp): transport/protocol · Command, event, and monitor codecs plus dispatch · `FlightOps/src/GRAMS_TOF_CommandCodec.cpp`
- [Clients/servers](https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_Client.cpp): network io · Command and event endpoints for runtime communication · `FlightOps/src/GRAMS_TOF_Client.cpp`
- [Runtime support](https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_Config.cpp): support libs · Config, logging, file descriptor, and error handling · `FlightOps/src/GRAMS_TOF_Config.cpp`
- [Python bridge](https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_PythonIntegration.cpp): language bridge · Embedding and integration boundary for Python in C++ · `FlightOps/src/GRAMS_TOF_PythonIntegration.cpp`
- [Data convert](https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/src/GRAMS_TOF_RootConverter.cpp): data path · Raw data conversion and ROOT-facing serialization · `FlightOps/src/GRAMS_TOF_RootConverter.cpp`
- [DAQ tools](https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/tools): cli tools · Thin executables for server, client, and command execution · `FlightOps/tools`

### Analysis

Offline ROOT-based processing

- [Analysis core](https://github.com/kenichisakai-git/grams-tof/tree/main/Analysis/include): offline analysis · ROOT-oriented time-of-flight analysis library · `Analysis/include`
- [Tree models](https://github.com/kenichisakai-git/grams-tof/blob/main/Analysis/src/TOF_TreeDataStg1.cpp): root models · Stage-1 and stage-2 tree structures and conversions · `Analysis/src/TOF_TreeDataStg1.cpp`
- [Calibration](https://github.com/kenichisakai-git/grams-tof/blob/main/Analysis/src/TOF_TdcQdcCalibration.cpp): analysis calib · Channel mapping, TDC/QDC, and discriminator calibration · `Analysis/src/TOF_TdcQdcCalibration.cpp`
- [Coincidence QA](https://github.com/kenichisakai-git/grams-tof/blob/main/Analysis/src/TOF_CoincidenceEvents.cpp): event aggregation · Coincidence event building, fitting, and parameter scans · `Analysis/src/TOF_CoincidenceEvents.cpp`
- [ROOT macros](https://github.com/kenichisakai-git/grams-tof/tree/main/Analysis/macro): study scripts · Interactive and batch ROOT study macros · `Analysis/macro`
- [Analysis tools](https://github.com/kenichisakai-git/grams-tof/tree/main/Analysis/scripts_c): cli tools · Compiled wrappers around analysis workflows · `Analysis/scripts_c`

### GroundOps

Monitoring and operations

- [GroundOps](https://github.com/kenichisakai-git/grams-tof/tree/main/GroundOps): ops stack · Monitoring database, bridge, and dashboard layer · `GroundOps`
- [Telemetry bridge](https://github.com/kenichisakai-git/grams-tof/blob/main/GroundOps/scripts/tof_bridge.py): service · Persistent ingestion service for monitor telemetry · `GroundOps/scripts/tof_bridge.py`
- [Monitor DB](https://github.com/kenichisakai-git/grams-tof/blob/main/GroundOps/sql/create_tof_monitor.sql): sql/schema · Database bootstrap and monitoring schema · `GroundOps/sql/create_tof_monitor.sql`
- [Grafana dashboard](https://github.com/kenichisakai-git/grams-tof/blob/main/GroundOps/grafana/TOF_metric-1772838555610.json): ops visualization · Prebuilt monitoring dashboard for TOF metrics · `GroundOps/grafana/TOF_metric-1772838555610.json`

### Vendored deps

Embedded third-party and support libraries

- [Raw data](https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/external/rawdata): raw io · Raw event reading, writing, and shared-memory transport · `FlightOps/external/rawdata`
- [daqd](https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/external/daqd): device server · Lower-level DAQ server/client and frame server boundary · `FlightOps/external/daqd`
- [psdaq driver](https://github.com/kenichisakai-git/grams-tof/tree/main/FlightOps/external/kernel): kernel device · Kernel driver and udev rules for hardware access · `FlightOps/external/kernel`
- **ROOT/Boost.Python**: external deps · Analysis and Python integration dependencies
- [fmt/CLI11](https://github.com/kenichisakai-git/grams-tof/blob/main/FlightOps/external/fmt-7.1.3): external deps · Formatting and CLI support libraries · `FlightOps/external/fmt-7.1.3`

### Other components

- **grams-tof**: monorepo · Top-level GRAMS Time-of-Flight stack

## Connections

- grams-tof → Common CMake: build logic · Shared build and packaging rules
- grams-tof → FlightOps core: runtime layer · Live DAQ and control plane
- grams-tof → Analysis core: offline layer · ROOT-based analysis plane
- grams-tof → GroundOps: ops layer · Monitoring and service integration
- Common CMake → FlightOps core: cmake support · Common CMake helpers used by FlightOps
- Common CMake → Analysis core: cmake support · Common CMake helpers used by Analysis
- LinkDef tools → ROOT macros: linkdefs · ROOT linkdef generation support
- FlightOps core → DAQ control: orchestrates · Coordinates DAQ lifecycle
- FlightOps core → Protocols: defines · Protocol codecs and dispatch
- FlightOps core → Clients/servers: provides · Network endpoints for command and event traffic
- FlightOps core → Runtime support: supports · Configuration, logging, and error handling
- FlightOps core → Python bridge: embeds python · Python runtime integration boundary
- FlightOps core → Data convert: exports data · Converts runtime data toward ROOT and downstream consumers
- DAQ tools → FlightOps core: fronts · Thin CLI entry points over the core library
- Clients/servers → daqd: connects to · Higher-level runtime speaks to lower-level DAQ boundary
- daqd → psdaq driver: drives hardware · Device-facing DAQ boundary reaches kernel access
- Raw data → Data convert: hand-off · Raw event transport feeds conversion and analysis hooks
- Raw data → Analysis core: feeds · Raw data is consumed by offline analysis
- Analysis core → Tree models: models · Stage tree structures and conversion path
- Analysis core → Calibration: calibrates · Calibration and channel mapping logic
- Analysis core → Coincidence QA: aggregates · Coincidence building and QA workflows
- ROOT macros → Analysis core: uses · Macros operate on the analysis library
- Analysis tools → Analysis core: wraps · Compiled CLI wrappers over analysis workflows
- Analysis core → ROOT/Boost.Python: depends on · ROOT and Boost.Python integration
- Python bridge → ROOT/Boost.Python: depends on · Python embedding and analysis serialization support
- FlightOps core → fmt/CLI11: depends on · Formatting and command-line parsing support
- GroundOps → Telemetry bridge: runs · Persistent telemetry bridge service
- Telemetry bridge → Monitor DB: writes · Telemetry is stored in monitoring schema
- Telemetry bridge → Grafana dashboard: visualized by · Dashboard consumes monitor data
- FlightOps core → Telemetry bridge: emits telemetry · Ops-facing metrics originate in the live runtime
- Analysis core → Monitor DB: qa results · Derived outputs can feed monitoring and reporting