# cosinekitty/sapphire architecture

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

- Interactive diagram: https://gitdiagram.com/cosinekitty/sapphire
- Repository: https://github.com/cosinekitty/sapphire

## Overview

##### Main Components

a) Core Plugin Infrastructure
- Plugin Registration System (based on plugin.cpp and plugin.hpp)
- Common Utilities (sapphire_globals.cpp, sapphire_vcvrack.hpp)
- Shared Components (sapphire_panel.hpp, sapphire_widget.hpp)

b) Module Categories
##### Chaos/Vector Modules
- Frolic, Glee, Lark (chaotic oscillators)
- Chaops (expander module)
- Hiss (random vector generator)
- Pivot (vector manipulation)
- Rotini (vector cross product)

##### Physics Simulation Modules
- Nucleus/Polynucleus (particle physics)
- Elastika (mesh physics simulation)

##### Audio Processing Modules
- Galaxy (reverb)
- Gravy/Sauce (filters)
- TubeUnit (waveguide synthesis)

##### Utility Modules
- Moots (connection simulation)
- Pop (trigger generator)
- SplitAddMerge (signal routing)
- Tin/Tout/Tricorder (visualization system)

**┌─────────────────────────────────────────────────────┐**
- VCV Rack Plugin API                │
- ┤
- Sapphire Core Infrastructure             │
- (SIMD, Panel System, Widget System, Resampling)   │
- ┬──────────────┬────────────┬───────────┤
- Chaos    │   Physics    │   Audio    │  Utility  │
- Modules  │   Modules    │  Modules   │  Modules  │
- ┴──────────────┴────────────┴───────────┘

##### Important Elements to Highlight

a) Shared Components:
- SIMD optimization system (sapphire_simd.hpp)
- Panel/widget inheritance hierarchy

b) Module Interactions:
- Expander relationships (Chaops with Frolic/Glee/Lark)
- Signal flow between visualization modules (Tin → Tricorder → Tout)
- Vector data flow between chaos modules

##### Implementation Details

- Relationship between .cpp and .hpp files
- Test infrastructure (util/unittest)
- Build system integration (.github/workflows)
- Standalone command-line tools (util/cmdline)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph VCV["VCV Rack Plugin API"]
        API[Plugin API Interface]
    end

    subgraph Core["Core Infrastructure"]
        PluginReg["Plugin Registration"]:::core
        CommonUtil["Common Utilities"]:::core
        PanelSys["Panel System"]:::core
        WidgetSys["Widget System"]:::core
        SIMD["SIMD Optimization"]:::core
        Engine["Engine Core"]:::core
    end

    subgraph Chaos["Chaos/Vector Modules"]
        ChaosBase["Chaos Base"]:::chaos
        Frolic["Frolic"]:::chaos
        Glee["Glee"]:::chaos
        Lark["Lark"]:::chaos
        Chaops["Chaops"]:::chaos
        Hiss["Hiss"]:::chaos
        Pivot["Pivot"]:::chaos
        Rotini["Rotini"]:::chaos
    end

    subgraph Physics["Physics Simulation"]
        NucleusCore["Nucleus Core"]:::physics
        NucleusImpl["Nucleus Implementation"]:::physics
        ElastikaCore["Elastika Core"]:::physics
        ElastikaImpl["Elastika Implementation"]:::physics
        MeshPhysics["Mesh Physics Engine"]:::physics
    end

    subgraph Audio["Audio Processing"]
        Galaxy["Galaxy"]:::audio
        Gravy["Gravy"]:::audio
        Sauce["Sauce"]:::audio
        TubeUnit["TubeUnit"]:::audio
    end

    subgraph Utility["Utility Modules"]
        Moots["Moots"]:::utility
        Pop["Pop"]:::utility
        SAM["SplitAddMerge"]:::utility
        Tin["Tin"]:::utility
        Tout["Tout"]:::utility
        Tricorder["Tricorder"]:::utility
    end

    subgraph Testing["Testing & Build"]
        UnitTest["Unit Tests"]:::test
        TestRunner["Test Runner"]:::test
        CICD["CI/CD Pipeline"]:::test
        TestPipe["Test Pipeline"]:::test
    end

    %% Core relationships
    API --> PluginReg
    PluginReg --> CommonUtil
    CommonUtil --> |Uses| PanelSys
    CommonUtil --> |Uses| WidgetSys
    CommonUtil --> |Uses| SIMD
    CommonUtil --> |Uses| Engine

    %% Chaos module relationships
    ChaosBase --> Frolic
    ChaosBase --> Glee
    ChaosBase --> Lark
    Chaops -.-> Frolic
    Chaops -.-> Glee
    Chaops -.-> Lark

    %% Physics relationships
    NucleusCore --> NucleusImpl
    ElastikaCore --> ElastikaImpl
    MeshPhysics --> ElastikaImpl

    %% Utility relationships
    Tin --> Tricorder
    Tricorder --> Tout

    %% Style definitions
    classDef core fill:#e1f5fe,stroke:#01579b
    classDef chaos fill:#f3e5f5,stroke:#4a148c
    classDef physics fill:#e8f5e9,stroke:#1b5e20
    classDef audio fill:#fff3e0,stroke:#e65100
    classDef utility fill:#f3e5f5,stroke:#4a148c
    classDef test fill:#eceff1,stroke:#263238

    %% Click events
    click PluginReg "https://github.com/cosinekitty/sapphire/blob/main/src/plugin.cpp"
    click CommonUtil "https://github.com/cosinekitty/sapphire/blob/main/src/sapphire_globals.cpp"
    click PanelSys "https://github.com/cosinekitty/sapphire/blob/main/src/sapphire_panel.hpp"
    click WidgetSys "https://github.com/cosinekitty/sapphire/blob/main/src/sapphire_widget.hpp"
    click SIMD "https://github.com/cosinekitty/sapphire/blob/main/src/sapphire_simd.hpp"
    click Engine "https://github.com/cosinekitty/sapphire/blob/main/src/sapphire_engine.hpp"
    click ChaosBase "https://github.com/cosinekitty/sapphire/blob/main/src/chaos.hpp"
    click Frolic "https://github.com/cosinekitty/sapphire/blob/main/src/frolic_vcv.cpp"
    click Glee "https://github.com/cosinekitty/sapphire/blob/main/src/glee_vcv.cpp"
    click Lark "https://github.com/cosinekitty/sapphire/blob/main/src/lark_vcv.cpp"
    click Chaops "https://github.com/cosinekitty/sapphire/blob/main/src/chaops_vcv.cpp"
    click Hiss "https://github.com/cosinekitty/sapphire/blob/main/src/hiss_vcv.cpp"
    click Pivot "https://github.com/cosinekitty/sapphire/blob/main/src/pivot_vcv.cpp"
    click Rotini "https://github.com/cosinekitty/sapphire/blob/main/src/rotini_vcv.cpp"
    click NucleusCore "https://github.com/cosinekitty/sapphire/blob/main/src/nucleus_engine.hpp"
    click NucleusImpl "https://github.com/cosinekitty/sapphire/blob/main/src/nucleus_vcv.cpp"
    click ElastikaCore "https://github.com/cosinekitty/sapphire/blob/main/src/elastika_engine.hpp"
    click ElastikaImpl "https://github.com/cosinekitty/sapphire/blob/main/src/elastika_vcv.cpp"
    click MeshPhysics "https://github.com/cosinekitty/sapphire/blob/main/src/mesh_physics.hpp"
    click Galaxy "https://github.com/cosinekitty/sapphire/blob/main/src/galaxy_vcv.cpp"
    click Gravy "https://github.com/cosinekitty/sapphire/blob/main/src/gravy_vcv.cpp"
    click Sauce "https://github.com/cosinekitty/sapphire/blob/main/src/sauce_vcv.cpp"
    click TubeUnit "https://github.com/cosinekitty/sapphire/blob/main/src/tubeunit_vcv.cpp"
    click Moots "https://github.com/cosinekitty/sapphire/blob/main/src/moots_vcv.cpp"
    click Pop "https://github.com/cosinekitty/sapphire/blob/main/src/pop_vcv.cpp"
    click SAM "https://github.com/cosinekitty/sapphire/blob/main/src/sam_vcv.cpp"
    click Tin "https://github.com/cosinekitty/sapphire/blob/main/src/tin_vcv.cpp"
    click Tout "https://github.com/cosinekitty/sapphire/blob/main/src/tout_vcv.cpp"
    click Tricorder "https://github.com/cosinekitty/sapphire/blob/main/src/tricorder_vcv.cpp"
    click UnitTest "https://github.com/cosinekitty/sapphire/blob/main/util/unittest/unittest.cpp"
    click TestRunner "https://github.com/cosinekitty/sapphire/tree/main/util/unittest/run"
    click CICD "https://github.com/cosinekitty/sapphire/blob/main/.github/workflows/build-plugin.yml"
    click TestPipe "https://github.com/cosinekitty/sapphire/blob/main/.github/workflows/sapphire-tests.yml"
```
