# bnlnpps/esi-shell architecture

> Architecture diagram of the GitHub repository bnlnpps/esi-shell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bnlnpps/esi-shell
- Repository: https://github.com/bnlnpps/esi-shell

## Overview

##### Project Type and Purpose
- This is a CLI‐based, container‐centric developer tool (“esi‐shell”) that automates the creation and execution of a reproducible, GPU-accelerated Geant4/OptiX simulation environment. It is not a multi-tier web application but a DevOps utility combining:
- A bash/python wrapper script (`esi-shell`)
- A Dockerfile that builds a container image with Spack, Geant4, plog, etc.
- Integration with the NVIDIA Container Toolkit for GPU access
- GitHub Actions CI/CD that builds and publishes images to GitHub Container Registry

##### Main Components
a. Developer Workstation (Host)
- `esi-shell` CLI script
- Docker Engine + NVIDIA Container Toolkit
- Local GPU drivers + optional host‐installed OptiX ($OPTIX_DIR)
b. Docker Container
- Base OS image (from Dockerfile)
- Spack package manager & `spack/var/spack/...` repo for building Geant4, plog, etc.
- Geant4 simulation framework
- NVIDIA OptiX SDK (mounted or baked in)
- Simulation code/tests (`eic-opticks/tests/...`)
c. CI/CD Pipeline & Registry
- `.github/workflows/*.yml` for pull-request builds and release builds
- `ghcr.io/bnlnpps/esi-shell` container registry for published images

##### Component Interactions & Data Flows
- User runs `./esi-shell [options]` → the script invokes `docker` CLI → communicates with Docker daemon → builds or runs the container.
- If mounting OptiX: host `$OPTIX_DIR` → volume mount → container’s `/usr/local/optix`.
- Once container is running, user can execute simulation commands (e.g. `test_opticks.sh`).
- On each git push or tagged release, GitHub Actions triggers:
- Build image via `Dockerfile` (using spack + OptiX install script)
- Push image to `ghcr.io/bnlnpps/esi-shell:<tag>`

##### Architectural Patterns & Design Principles
- CLI Facade Pattern: single script hides Docker complexity
- Container‐as‐Contract: Docker image encapsulates all dependencies (Spack, Geant4, plog)
- Volume‐mount strategy for host‐side SDKs (OptiX)
- CI/CD pipeline for immutable, versioned container artifacts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Zone
    subgraph "Developer Workstation (Host)"
        direction TB
        Terminal["User Terminal"]:::host
        ESIShell["esi-shell script"]:::host
        DockerCLI["Docker CLI"]:::host
        DockerDaemon["Docker Daemon"]:::host
        HostOPTIX["Host $OPTIX_DIR"]:::host
    end

    %% Container Zone
    subgraph "Docker Container Runtime"
        direction TB
        BaseOS["Base OS Image"]:::container
        subgraph "Spack Environment"
            direction TB
            SpackRepos["Spack & repos"]:::container
            BuiltinPkgs["builtin packages"]:::container
            PlogPkg["plog package definition"]:::container
        end
        Geant4["Geant4 Framework"]:::container
        OptixSDK["OptiX SDK"]:::container
        Tests["Simulation tests"]:::container
    end

    %% CI/CD Zone
    subgraph "CI/CD Pipeline (GitHub Actions)"
        direction TB
        PRBuild["PR Build Workflow"]:::ci
        ReleaseWF["Release Workflow"]:::ci
        Cleanup["Cleanup Script"]:::ci
    end

    %% Registry
    Registry["ghcr.io Container Registry"]:::registry

    %% Connections Host -> Container
    Terminal -->|"runs"| ESIShell
    ESIShell -->|"invokes docker"| DockerCLI
    DockerCLI -->|"communicates"| DockerDaemon
    DockerDaemon -->|"build/run"| BaseOS
    HostOPTIX -->|"volume mount"| OptixSDK
    BaseOS --> SpackRepos
    SpackRepos --> BuiltinPkgs
    BuiltinPkgs --> PlogPkg
    PlogPkg --> Geant4
    Geant4 --> OptixSDK
    OptixSDK --> Tests

    %% CI/CD Flows
    PRBuild -->|"docker build"| DockerDaemon
    ReleaseWF -->|"docker build"| DockerDaemon
    DockerDaemon -->|"push image"| Registry
    Cleanup -->|"maintains"| Registry

    %% Click Events
    click ESIShell "https://github.com/bnlnpps/esi-shell/tree/main/esi-shell"
    click BaseOS "https://github.com/bnlnpps/esi-shell/tree/main/Dockerfile"
    click SpackRepos "https://github.com/bnlnpps/esi-shell/tree/main/spack/var/spack/repos"
    click BuiltinPkgs "https://github.com/bnlnpps/esi-shell/tree/main/spack/var/spack/repos/builtin/packages"
    click PlogPkg "https://github.com/bnlnpps/esi-shell/blob/main/spack/var/spack/repos/builtin/packages/plog/package.py"
    click PRBuild "https://github.com/bnlnpps/esi-shell/blob/main/.github/workflows/build-pull-request.yml"
    click ReleaseWF "https://github.com/bnlnpps/esi-shell/blob/main/.github/workflows/release.yml"
    click Cleanup "https://github.com/bnlnpps/esi-shell/blob/main/.github/workflows/delete_untagged.py"

    %% Styles
    classDef host fill:#AED6F1,stroke:#1F618D,color:#1B4F72
    classDef container fill:#A9DFBF,stroke:#196F3D,color:#145A32
    classDef ci fill:#F5B041,stroke:#B9770E,color:#7E5109
    classDef registry fill:#F9E79F,stroke:#B7950B,color:#7E5109
```
