# slac-lcls/lcls2 architecture

> Architecture diagram of the GitHub repository slac-lcls/lcls2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/slac-lcls/lcls2
- Repository: https://github.com/slac-lcls/lcls2

## Overview

##### Major components
- Data Acquisition and Hardware Interface – Represented by the “psdaq” directory and its submodules (such as drp, epicsArch, and others). This layer interacts directly with the detector hardware, digitizers, and external interfaces (EPICS, ZeroMQ, libfabric).
- Event Building and Data Formatting – This includes the “evtbuild” and “xtcdata” packages. They are responsible for converting raw detector signals into structured event data (xtc format) and supporting conversion utilities.
- Data Analysis and Processing – The “psana” package is the central framework for assembling, processing, and analyzing acquired data. It includes client applications, event builders, and test utilities.
- Signal Processing/Algorithmic Modules – “psalg” provides underlying algorithms, calibration, and geometry support necessary for data interpretation.
- Calibration, Configuration, and Utilities – Directories like “pscalib,” “configdb,” “pyalgos,” and others that manage experiment-specific calibrations and configurations.
- Control and Monitoring – Components like the “psdaq/control” and “psdaq/control_gui” directories that provide interfaces for monitoring the system, running timed experiments, and interfacing with high-level control layers.
- Build and Environment Management – Scripts such as build_all.sh, setup_env.sh, and related conda/Spack recipes that coordinate building and deployment across different modules.

##### Relationships and interactions
- The event building/formatting components (evtbuild, xtcdata) then convert raw data into structured event formats used by analysis software.
- The analysis framework (psana) receives events, interfaces with processing algorithms (psalg), performs calibrations (pscalib), and delivers data for visualization and further processing.
- Control and configuration modules (configdb, control_gui, EPICS tools in psdaq/epicsArch and psdaq/cas) send commands upstream (control signals) and share status information downstream (monitoring and logging).
- Test suites and utilities (e.g., those in psana/tests) help verify components in each layer but are depicted as peripheral verification tools.

##### Architectural patterns and design principles
- Modularity: Each “package” (psdaq, psana, psalg, xtcdata, etc.) is a self-contained module that is built independently and then integrated via the build system.
- Layered Architecture: A clear separation between low-level hardware/control (psdaq and EPICS integrations), mid-level event construction (xtcdata, evtbuild), and high-level analysis (psana, psalg).

## Diagram (Mermaid)

```mermaid
flowchart TB

    %% Data Acquisition & Hardware Interface
    subgraph "Data Acquisition & Hardware Interface"
        PSDAQ["psdaq (Acquisition)"]:::acquisition
        DRP["drp (Data Routing)"]:::acquisition
        EPICS["epicsArch (EPICS Interface)"]:::acquisition
        CONTROL["control (Control Interface)"]:::control
        CTRL_GUI["control GUI (Control GUI)"]:::control
    end

    %% Event Building & Data Formatting
    subgraph "Event Building & Data Formatting"
        EVTBUILD["evtbuild"]:::cpp
        XTC["xtcdata"]:::cpp
    end

    %% Data Analysis & Processing
    subgraph "Data Analysis & Processing"
        PSANA["psana"]:::python
    end

    %% Signal Processing Modules
    subgraph "Signal Processing Modules"
        PSALG["psalg"]:::python
    end

    %% Calibration & Configuration
    subgraph "Calibration & Configuration"
        PSCALIB["pscalib"]:::calibration
        CONFIGDB["configdb"]:::calibration
    end

    %% Build & Environment Management
    subgraph "Build & Environment Management"
        BUILD_ALL["build_all.sh"]:::build
        SETUP_ENV["setup_env.sh"]:::build
        SETUP_SPACK["setup_env_spack.sh"]:::build
    end

    %% Data Flow Connections
    PSDAQ -->|"raw_data"| EVTBUILD
    PSDAQ -->|"raw_data"| XTC
    EVTBUILD -->|"formatted_events"| PSANA
    XTC -->|"structured_events"| PSANA
    PSALG -->|"algorithm_support"| PSANA
    PSCALIB -->|"calibration_data"| PSANA
    CONFIGDB -->|"configuration"| PSANA

    %% Control & Monitoring Feedback
    CONTROL -.->|"control_signals"| PSDAQ
    CTRL_GUI -.->|"status_control"| PSDAQ

    %% Build & Environment Integration
    BUILD_ALL -->|"builds"| PSDAQ
    BUILD_ALL -->|"builds"| EVTBUILD
    BUILD_ALL -->|"builds"| XTC
    BUILD_ALL -->|"builds"| PSANA
    BUILD_ALL -->|"builds"| PSALG
    BUILD_ALL -->|"builds"| PSCALIB
    BUILD_ALL -->|"builds"| CONFIGDB

    SETUP_ENV -->|"sets_env"| PSDAQ
    SETUP_SPACK -->|"sets_env"| PSDAQ

    %% Click Events
    click PSDAQ "https://github.com/slac-lcls/lcls2/tree/master/psdaq"
    click DRP "https://github.com/slac-lcls/lcls2/tree/master/psdaq/drp"
    click EPICS "https://github.com/slac-lcls/lcls2/tree/master/psdaq/epicsArch"
    click CONTROL "https://github.com/slac-lcls/lcls2/tree/master/psdaq/control"
    click CTRL_GUI "https://github.com/slac-lcls/lcls2/tree/master/psdaq/control_gui"
    click EVTBUILD "https://github.com/slac-lcls/lcls2/tree/master/evtbuild"
    click XTC "https://github.com/slac-lcls/lcls2/tree/master/xtcdata"
    click PSANA "https://github.com/slac-lcls/lcls2/tree/master/psana"
    click PSALG "https://github.com/slac-lcls/lcls2/tree/master/psalg"
    click PSCALIB "https://github.com/slac-lcls/lcls2/tree/master/psana/pscalib"
    click CONFIGDB "https://github.com/slac-lcls/lcls2/tree/master/psdaq/psdaq/configdb"
    click BUILD_ALL "https://github.com/slac-lcls/lcls2/blob/master/build_all.sh"
    click SETUP_ENV "https://github.com/slac-lcls/lcls2/blob/master/setup_env.sh"
    click SETUP_SPACK "https://github.com/slac-lcls/lcls2/blob/master/setup_env_spack.sh"

    %% Styles
    classDef acquisition fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef cpp fill:#ffe6cc,stroke:#ff6600,stroke-width:2px;
    classDef python fill:#e6f2ff,stroke:#0066cc,stroke-width:2px;
    classDef calibration fill:#e6ffe6,stroke:#009900,stroke-width:2px;
    classDef control fill:#f2e6ff,stroke:#6600cc,stroke-width:2px;
    classDef build fill:#fff2cc,stroke:#cccc00,stroke-width:2px;
```
