# ldmx-software/ldmx-sw architecture

> Architecture diagram of the GitHub repository ldmx-software/ldmx-sw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ldmx-software/ldmx-sw
- Repository: https://github.com/ldmx-software/ldmx-sw

## Overview

##### Main Components Organization

a) Core Framework Layer:
- Framework/ directory contains the core infrastructure
- Process, Event, and Configuration management
- Connections to conditions system and random number services

b) Detector Systems:
- DetDescr/, Detectors/, and geometry-related components
- Relationships between detector description and simulation
- Detector ID systems and electronics mapping

c) Simulation Stack:
- SimCore/ as the central simulation component
- Integration with Geant4 (indicated by G4 prefixes)
- Biasing operators and physics models
- To magnetic field and detector construction

d) Reconstruction Chain:
- Recon/, Tracking/, and detector-specific reconstruction (Ecal/, Hcal/, TrigScint/)
- Data flow from raw data through reconstruction stages
- Clustering and particle identification

e) Analysis & Validation:
- DQM/ for monitoring
- Validation/ for quality checks
- Tools/ for analysis utilities

##### Specific Implementation Details

**[Core Framework Layer]**

- [Event Processing]-->[Conditions System]

- [Configuration]---->[Python Interface]

- [Plugin System]---->[Module Loading]

**[Detector Description]**

- [Geometry]-------->[GDML Parsing]

- [ID Systems]------>[Electronics Mapping]

**[Simulation Stack]**

- [Geant4 Interface]

- [Physics Lists]
- [Biasing Operators]
- [Sensitive Detectors]

- [Magnetic Field]
- [Primary Generators]

**[Reconstruction]**

- [Tracking]-------->[Track Finding]-->[Track Fitting]

- [Calorimetry]----->[Clustering]---->[Energy Reconstruction]

- [Trigger]--------->[Hardware Trigger]-->[Software Trigger]

##### Additional Elements

a) External dependencies:
- Geant4
- ROOT
- Python
- ONNX Runtime
- Acts (for tracking)

b) Data formats and storage:
- Event data model
- Persistent storage
- Conditions database

c) Processing flow:
- Configuration
- Initialization
- Event processing
- Finalization

##### Important Interfaces

Interfaces between components:
- Framework to modules interface
- Simulation to reconstruction interface
- Detector description to simulation interface
- Analysis to reconstruction interface

##### Deployment Aspects

Container-based deployment:
- Docker/Apptainer support
- Development environment
- Production environment

- Hierarchical layout
- Different line styles
- Proper labeling
- Export to high-resolution formats

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef framework fill:#b3d9ff,stroke:#333
    classDef detector fill:#fff2b3,stroke:#333
    classDef simulation fill:#b3ffb3,stroke:#333
    classDef reconstruction fill:#ffcc99,stroke:#333
    classDef analysis fill:#e6b3ff,stroke:#333
    classDef external fill:#f2f2f2,stroke:#333
    
    subgraph Core
        Process["Process Manager"]:::framework
        Event["Event Model"]:::framework
        Config["Configuration"]:::framework
        PluginSys["Plugin System"]:::framework
    end

    subgraph DetectorSystems
        DetDesc["Detector Description"]:::detector
        DetID["Detector ID System"]:::detector
        Geometry["Geometry Manager"]:::detector
        ElecMap["Electronics Mapping"]:::detector
    end

    subgraph SimulationStack
        SimCore["Simulation Core"]:::simulation
        G4Interface["Geant4 Interface"]:::simulation
        PhysicsList["Physics Lists"]:::simulation
        BiasOp["Biasing Operators"]:::simulation
        MagField["Magnetic Field"]:::simulation
        PrimaryGen["Primary Generators"]:::simulation
    end

    subgraph ReconstructionChain
        Tracking["Tracking System"]:::reconstruction
        Ecal["ECal Reconstruction"]:::reconstruction
        Hcal["HCal Reconstruction"]:::reconstruction
        TrigScint["Trigger Scintillator"]:::reconstruction
        ReconCore["Reconstruction Core"]:::reconstruction
    end

    subgraph Analysis
        DQM["Data Quality Monitor"]:::analysis
        Valid["Validation"]:::analysis
        Tools["Analysis Tools"]:::analysis
        EventDisplay["Event Display"]:::analysis
    end

    subgraph External
        Geant4["Geant4"]:::external
        ROOT["ROOT"]:::external
        Python["Python"]:::external
        ONNX["ONNX Runtime"]:::external
        Acts["Acts"]:::external
    end

    %% Relationships
    Process --> Event
    Config --> Process
    PluginSys --> Process
    
    DetDesc --> SimCore
    DetID --> ElecMap
    Geometry --> DetDesc
    
    SimCore --> G4Interface
    G4Interface --> PhysicsList
    G4Interface --> BiasOp
    MagField --> SimCore
    PrimaryGen --> SimCore
    
    ReconCore --> Tracking
    ReconCore --> Ecal
    ReconCore --> Hcal
    ReconCore --> TrigScint
    
    Event --> ReconCore
    Event --> DQM
    
    %% External Dependencies
    G4Interface --> Geant4
    Tracking --> Acts
    
    %% Click Events
    click Process "https://github.com/LDMX-Software/ldmx-sw/blob/trunk/Framework/include/Framework/Process.h"
    click Event "https://github.com/LDMX-Software/ldmx-sw/blob/trunk/Framework/include/Framework/Event.h"
    click Config "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/Framework/include/Framework/Configure/"
    click DetDesc "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/DetDescr/"
    click DetID "https://github.com/LDMX-Software/ldmx-sw/blob/trunk/DetDescr/include/DetDescr/DetectorID.h"
    click Geometry "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/Detectors/data/"
    click SimCore "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/SimCore/"
    click BiasOp "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/SimCore/include/SimCore/BiasOperators/"
    click MagField "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/MagFieldMap/"
    click Tracking "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/Tracking/"
    click Ecal "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/Ecal/"
    click Hcal "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/Hcal/"
    click TrigScint "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/TrigScint/"
    click ReconCore "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/Recon/"
    click DQM "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/DQM/"
    click Valid "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/Validation/"
    click Tools "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/Tools/"
    click EventDisplay "https://github.com/LDMX-Software/ldmx-sw/tree/trunk/EventDisplay/"
```
