# hballington12/goad architecture

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

- Interactive diagram: https://gitdiagram.com/hballington12/goad
- Repository: https://github.com/hballington12/goad

## Overview

##### Project Type and Purpose
This is a hybrid scientific simulation toolkit centered on a Rust core library for geometric‐optics light scattering (GOAD). It ships as:
- A Rust CLI binary for batch/terminal use.
- A Python extension (via PyO3/maturin) plus a GUI application.
- A Blender add-on that embeds the Python extension into Blender.

##### High-Level File Structure
- Cargo.toml, src/… – Rust library and binary (main.rs + modules: beam, clip, geom, output, params, etc.)
- examples/… – Rust example programs & sample .obj geometry data.
- tests/… – Rust unit/integration tests with sample data.
- config/… – default.toml configuration and a helper script (config_editor.sh).
- goad-py/… – Python package:
– src/lib.rs – PyO3 wrapper around the Rust core, built via maturin.sh/pyproject.toml.
– app/… – Python GUI (main_window.py, panels, OpenGL view).
- blender/addon/… – Blender add-on in Python, bundles goad_py for in-Blender use + build.sh.

##### Key Components and Their Interactions
[Rust Core Library]
- Contains all physics and numeric computation modules (.rs files).
[CLI Binary]
- Rust main.rs uses Rust Core to parse CLI args, read config/default.toml, load .obj, run simulation, write results.
[Python Extension (goad_py)]
- PyO3‐based native module exposing core APIs to Python.
[Python GUI App]
- Imports goad_py; builds a desktop UI with panels, triggers simulations, visualises via OpenGL.
[Blender Add-On]
- Registers UI panels in Blender; imports goad_py to drive simulations inside Blender’s Python runtime.

##### Architectural Patterns and Principles
- Layered Architecture:
– Core computation (Rust library)
– API layers (Rust CLI, Python binding)
– Clients (Terminal, Desktop GUI, Blender)
- FFI Boundary: Clean separation at PyO3 interface.
- Configuration-over-code: TOML files (config/) overridden by CLI args/env.
- Modularity: Each major feature (beam tracing, clipping, diffraction) in its own Rust module.

– Clear component labels (e.g., “GOAD Core (Rust Library)”).
– Call out config layer (TOML) and sample data (.obj) feeding into CLI and Python layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Resources
    config["Config\nconfig/default.toml\nconfig_editor.sh"]:::external
    obj["Geometry Files\n*.obj"]:::external
    outputs["Results\nData files, Plots, Visualizations"]:::external

    %% GOAD Core Layer
    subgraph "GOAD Core (Rust Library)" 
        rust_lib["Core Library\nsrc/lib.rs"]:::rust
        cli["CLI Binary\nsrc/main.rs"]:::rust
        examples["Rust Examples & Sample Data\nexamples/"]:::external
        tests["Rust Tests & Sample Data\ntests/"]:::external
    end

    %% Python Package Layer
    subgraph "GOAD Python Package"
        python_ext["Python Extension\ngoad-py/src/lib.rs"]:::python
        gui["Python GUI App\ngoad-py/app/main.py"]:::python
        blender["Blender Add-On\nblender/addon/__init__.py"]:::python
    end

    %% DevOps Layer
    subgraph "DevOps & Build"
        ci_rust["Rust CI\n.github/workflows/rust.yml"]:::ci
        ci_py["Python CI\ngoad-py/.github/workflows/CI.yml"]:::ci
        build["Build Scripts\nsetup.sh\nmaturin.sh\nblender/build.sh"]:::ci
    end

    %% Data & Config flows
    config -->|".toml → loadConfig()"| cli
    obj -->|".obj → parseGeometry()"| cli
    cli -->|"runSimulation() / writeResults()"| rust_lib
    cli -->|"> Generate Outputs"| outputs

    obj -->|".obj → parseGeometry()"| python_ext
    config -->|".toml → loadConfig()"| python_ext
    python_ext -->|"runSimulation()"| rust_lib
    gui -->|"displayResults() / OpenGL" | outputs
    gui -->|"invoke Extension"| python_ext
    blender -->|"invoke Extension"| python_ext
    blender -->|"display in Blender UI"| outputs

    %% Examples & Tests to Core
    examples --> rust_lib
    tests --> rust_lib

    %% DevOps flows
    ci_rust --> rust_lib
    ci_py --> python_ext
    build --> rust_lib
    build --> python_ext
    build --> blender

    %% Click Events
    click rust_lib "https://github.com/hballington12/goad/blob/master/src/lib.rs"
    click cli "https://github.com/hballington12/goad/blob/master/src/main.rs"
    click config "https://github.com/hballington12/goad/blob/master/config/default.toml"
    click examples "https://github.com/hballington12/goad/tree/master/examples/"
    click tests "https://github.com/hballington12/goad/tree/master/tests/"
    click python_ext "https://github.com/hballington12/goad/blob/master/goad-py/src/lib.rs"
    click gui "https://github.com/hballington12/goad/blob/master/goad-py/app/main_window.py"
    click blender "https://github.com/hballington12/goad/blob/master/blender/addon/__init__.py"
    click ci_rust "https://github.com/hballington12/goad/blob/master/.github/workflows/rust.yml"
    click ci_py "https://github.com/hballington12/goad/blob/master/goad-py/.github/workflows/CI.yml"
    click build "https://github.com/hballington12/goad/blob/master/setup.sh"

    %% Styles
    classDef rust fill:#f5a623,stroke:#e67e22,color:#000;
    classDef python fill:#5dade2,stroke:#3498db,color:#000;
    classDef external fill:#d7dbdd,stroke:#95a5a6,color:#000;
    classDef ci fill:#abebc6,stroke:#27ae60,color:#000;
```
