kenichisakai-git/grams-tof

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.