# sonderwoods/mantaray architecture

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

- Interactive diagram: https://gitdiagram.com/sonderwoods/mantaray
- Repository: https://github.com/sonderwoods/mantaray

## Overview

##### Project Type and Purpose
- This is an open-source Grasshopper plugin (C#/.NET) that connects Rhino/Grasshopper to a Linux Radiance environment over SSH.
- It bundles a suite of GH components (SSH Connect, Execute Async, MeshToObj, RadViewer, etc.) that build Radiance commands or files, send them to WSL, run them, and return parsed results into the GH canvas.

##### File Structure
- Top level:
- MantaRay.sln (Visual Studio solution)
- MantaRay/ (C# plugin project)
- UnitTests/ (test project)
- Examples/ (sample Grasshopper/Rhino files and Radiance files)
- Setup/ (installation helpers and scripts)
- Within MantaRay/:
- Components/ (each GH component class)
- Components/Templates/ (base classes and async templates)
- HeadsUpDisplay/ (UI overlay classes)
- Helpers/ (utility classes: SSH_Helper, PathHelper, LogHelper, etc.)
- Interfaces/ (ISetConnection, IFolderConversion, etc.)
- Radiance/ (domain model for Radiance geometry & materials)
- Types/ (value types: Grid, GradientParser, etc.)

##### Extract Key Architectural Insights from README
- Core workflow: GH component → builds Radiance files/commands → SSH to WSL → execute Radiance CLI or GUI tools → return geometry, images, logs → display in GH.
- Supports asynchronous execution, caching of results, streaming man pages over HTTP, integration with ImageMagick and optional denoiser.
- Single “Setup Globals” component provides shared configuration (project folder, SSH settings).

##### Main System Components
a. Grasshopper UI Layer (Client)
- Rhino viewport & GH canvas hosting components
- User-placed GH Components (SSH Connect, Execute Async, CreateView, etc.)
b. Plugin Core Layer
- Component Classes (in Components/)
- Async & Template Base Classes (in Components/Templates/)
- HeadsUpDisplay UI overlays
- Domain Model (Radiance geometry & Material classes)
- Helpers & Interfaces (SSH helper, file IO, logging, parsing)
c. Infrastructure Layer
- SSH Service (WSL SSH Daemon)
- File synchronization (SFTP, temp folders)
- Radiance CLI & GUI Tools (rad, rpict, rvu)
- External Utilities (ImageMagick, Intel OIDenoiser)
- ManPage HTTP service (fetched on demand)
d. Sample & Test Artifacts
- Example GH definitions (.gh), Rhino files (.3dm), .rad files
- UnitTests project

##### Relationships & Data Flows
- “Setup Globals” sits at the top of the plugin core and feeds configuration into all components.
- Async components spawn parallel SSH sessions; use RAN output to synchronize downstream GH components.
- RadViewer parses .rad files returned over SSH and feeds geometry into GH preview.

##### Architectural Patterns & Design Principles
- Layered architecture: UI → Component layer → Domain model → Infrastructure.
- Plugin pattern: Components/Templates allow easy addition of new GH components.
- Async execution: non-blocking GH UI, parallel SSH commands.
- Single source of configuration via “Setup Globals”.
- Clear separation: Radiance domain objects are defined in Radiance/ folder, SSH logic in Helpers, UI logic in HeadsUpDisplay.

##### Final Checklist
- Optional: annotate key classes (SSH_Helper, RadianceObjectCollection, GH_ExecuteAsync) to highlight extension points.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Grasshopper UI Layer"
        direction TB
        GHComponents["GH Components\n(SSH Connect, Execute Async, MeshToObj, …)"]:::ui
    end

    subgraph "Plugin Core Layer"
        direction TB
        SetupGlobals["Setup Globals\n(shared configuration)"]:::core
        subgraph "Component Base & Templates"
            direction TB
            Templates["Templates\n(GH_Template.cs,\nGH_Template_Async.cs,\nWorkerInstance.cs)"]:::core
        end
        subgraph "Heads-Up Display"
            direction TB
            HUD["HUD Overlay\n(HUD.cs,\nHUD_Item.cs, …)"]:::core
        end
        subgraph "Radiance Domain Model"
            direction TB
            RadianceModel["Radiance Domain\n(Polygon.cs, Material.cs,\nRadianceObjectCollection.cs, …)"]:::core
        end
        subgraph "Helpers & Interfaces"
            direction TB
            Helpers["Helpers\n(SSH_Helper.cs,\nPathHelper.cs,\nManPageHelper.cs,\nLogHelper.cs, …)"]:::infra
            Interfaces["Interfaces\n(ISetConnection.cs,\nIFolderConversion.cs)"]:::core
        end
        subgraph "Types & Parsers"
            direction TB
            Types["Value Types & Parsers\n(Grid.cs,\nGradientParser.cs, …)"]:::core
        end
        SetupGlobals --> Templates
        SetupGlobals --> Helpers
        SetupGlobals --> RadianceModel
        SetupGlobals --> Interfaces
        SetupGlobals --> Types
    end

    subgraph "Infrastructure & Remote Execution"
        direction TB
        SSHService["WSL SSH Service"]:::infra
        FileSync["File Sync (SFTP,\nTemp Folders)"]:::infra
        RadianceCLI["Radiance CLI & GUI\n(rad, rpict, rvu)"]:::external
        ExternalTools["ImageMagick,\nIntel OIDenoiser"]:::external
        ManPages["HTTP ManPage Service"]:::external
    end

    subgraph "Samples & Tests"
        direction TB
        Examples["Examples\n(.gh, .3dm, .rad)"]:::core
        UnitTestsProj["UnitTests Project\n(UnitTests.csproj,\nUnitTest1.cs)"]:::core
    end

    %% Data Flows
    GHComponents -->|"uses"| Helpers
    GHComponents -->|"depends on"| Templates
    GHComponents -->|"renders via"| HUD
    Helpers -->|"SSH to"| SSHService
    SSHService -->|"executes"| RadianceCLI
    SSHService -->|returns results| Helpers
    RadianceCLI -->|optional| ExternalTools
    Helpers -->|"fetches docs from"| ManPages
    GHComponents -->|"builds domain objects"| RadianceModel
    GHComponents -->|"parses types with"| Types
    GHComponents -->|"reads config from"| SetupGlobals

    %% Click events
    click GHComponents "https://github.com/sonderwoods/mantaray/tree/main/MantaRay/Components"
    click Templates "https://github.com/sonderwoods/mantaray/tree/main/MantaRay/Components/Templates"
    click HUD "https://github.com/sonderwoods/mantaray/tree/main/MantaRay/HeadsUpDisplay"
    click RadianceModel "https://github.com/sonderwoods/mantaray/tree/main/MantaRay/Radiance"
    click Helpers "https://github.com/sonderwoods/mantaray/tree/main/MantaRay/Helpers"
    click Interfaces "https://github.com/sonderwoods/mantaray/tree/main/MantaRay/Interfaces"
    click SetupGlobals "https://github.com/sonderwoods/mantaray/blob/main/MantaRay/Components/GH_Globals.cs"
    click Types "https://github.com/sonderwoods/mantaray/tree/main/MantaRay/Types"
    click Examples "https://github.com/sonderwoods/mantaray/tree/main/Examples"
    click UnitTestsProj "https://github.com/sonderwoods/mantaray/tree/main/UnitTests"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#1C96F2,color:#1C96F2,stroke-width:2px;
    classDef core fill:#DFF7D8,stroke:#2E8B57,color:#2E8B57,stroke-width:2px;
    classDef infra fill:#FFEEDD,stroke:#FF8C00,color:#FF8C00,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#8A2BE2,color:#8A2BE2,stroke-width:2px;
```
