# gremlin529/vectric-box-gadget architecture

> Architecture diagram of the GitHub repository gremlin529/vectric-box-gadget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gremlin529/vectric-box-gadget
- Repository: https://github.com/gremlin529/vectric-box-gadget

## Overview

So the “system” you’re diagramming is not a distributed backend—it’s a **plugin architecture**:
- Host application: **Vectric** (the runtime environment)
- Packaging/release pipeline: PowerShell script that emits `.vgadget`

##### What the README adds (key architectural implications)
- The repo is intended to be **cloned directly into the Vectric Gadgets directory** and run “live” during development.
- Release is a deliberate process via `MakeRelease.ps1` to generate versioned gadgets.

You want to capture **runtime flow** and **build flow** separately.

##### Vectric API → modifies Vectric Document Model
- Outputs: vectors, toolpaths, materials, etc.

##### Build/release flow
1. **Source files** (`*_dev.lua`, `*_dev.html`, `stylesheets/`, `Images/`) → input into **MakeRelease.ps1**

##### Architectural patterns / principles to explicitly highlight
- **Plugin architecture / in-process extension**: gadget runs within Vectric host.
- **UI/Logic separation**:
- Presentation layer: HTML/CSS/Images
- Logic layer: Lua
- **Host API boundary**:
- Lua is the only part that can directly manipulate the Vectric document via SDK/API.
- **Artifact-based distribution**:
- `.vgadget` is the deployable unit; repo is the source form.

##### Technologies to label
- **Lua** (core logic)
- **HTML + CSS** (UI)
- **PowerShell** (`MakeRelease.ps1`) for packaging
- **Vectric Gadget Framework / SDK** (host integration)
- **`.vgadget`** (packaging format)

##### Development & Release
- Repo working tree
- `MakeRelease.ps1`
- `release/*.vgadget`

##### Vectric Host Runtime
- Vectric Desktop App
- Gadget Host / SDK/API
- Vectric Document Model (Vectors/Toolpaths)

##### Gadget Internals
- HTML UI
- CSS
- Images
- Lua Script

##### Labels
- “Lua: Box_Creator_Ver_dev.lua”
- “UI: Box_Creator_Ver_dev.html”
- “CSS: stylesheets/*.css”
- “Assets: Images/*”
- “Release: Box_Creator_Ver_X.Y.vgadget”

- “User clicks / enters parameters”
- “Parameter values + commands”
- “Calls Vectric SDK/API”
- “Creates vectors/toolpaths in current job”
- “Loads CSS / images”
- “Packages / renames / emits .vgadget”

##### “Don’t overthink it” detail expansion (separate into many components)
- “Parameter validation”
- “Layer/material setup”
- “Toolpath generation”

Similarly, split UI into:
- “Input forms / controls”
- “Status/errors”

##### Build & Release Pipeline: repo → MakeRelease.ps1 → `.vgadget` → loaded by Vectric.

That pair will be the most accurate representation of this project as it exists in the tree and README.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================================================
%% Diagram 1: Runtime Architecture (in-process Vectric Gadget)
%% =========================================================
subgraph "Runtime Architecture (In-Process Plugin)"
direction TB

  U["User"]:::external

  subgraph "Vectric Host Runtime"
  direction TB
    VApp["Vectric Desktop App (VCarve Pro / Aspire)"]:::host
    VGH["Gadget Host Runtime"]:::host
    VAPI["Vectric Gadget SDK / API"]:::api
    VDoc[("Vectric Document Model\n(Vectors / Geometry / Toolpaths)")]:::data
  end

  subgraph "Box Creator Gadget (Plugin Internals)"
  direction TB

    subgraph "UI Layer (Embedded HTML Panel)"
    direction TB
      UIHTML["HTML UI\n(Box_Creator_Ver_dev.html)"]:::ui
      UIFORM["Input Controls / Parameters"]:::ui
      UIPRE["Preview / Diagram Area"]:::ui
      UISTATUS["Status / Validation Messages"]:::ui
      UICSS["CSS Styles\n(stylesheets/*.css)"]:::asset
      UIIMG["Images / Icons\n(Images/*)"]:::asset
    end

    subgraph "Logic Layer (Lua)"
    direction TB
      LUALOGIC["Lua Core Logic\n(Box_Creator_Ver_dev.lua)"]:::logic

      subgraph "Logical Responsibilities (within Lua file)"
      direction TB
        LVALID["Parameter Validation"]:::logic
        LGEOM["Box Geometry Generator"]:::logic
        LJOINT["Finger Joints / Tabs Generator"]:::logic
        LLAYER["Layer / Material Setup"]:::logic
        LTP["Toolpath Generation"]:::logic
      end
    end

    BRIDGE["UI-to-Lua Bridge\n(Vectric gadget framework)"]:::bridge
  end

  %% Runtime connections
  U -->|"clicks/inputs"| UIHTML
  UIHTML -->|"drives"| UIFORM
  UIHTML -->|"renders"| UIPRE
  UIHTML -->|"shows"| UISTATUS

  UIHTML -->|"loads"| UICSS
  UIHTML -->|"loads"| UIIMG

  UIFORM -->|"UIevents+parametervalues"| BRIDGE
  BRIDGE -->|"dispatchescommands"| LUALOGIC

  LUALOGIC -->|"uses"| LVALID
  LUALOGIC -->|"uses"| LGEOM
  LUALOGIC -->|"uses"| LJOINT
  LUALOGIC -->|"uses"| LLAYER
  LUALOGIC -->|"uses"| LTP

  LUALOGIC -->|"calls"| VAPI
  VAPI -->|"creates/updates"| VDoc

  LUALOGIC -->|"status/errors/computed_dims"| BRIDGE
  BRIDGE -->|"updatesUI"| UISTATUS

  %% Host runtime wiring
  VApp -->|"runs_in_process"| VGH
  VGH -->|"hosts"| UIHTML
  VGH -->|"executes"| LUALOGIC
  VGH -->|"exposes"| VAPI
end

%% =====================================
%% Diagram 2: Build & Release Pipeline
%% =====================================
subgraph "Build & Release Pipeline"
direction TB

  DEV["Developer Workstation"]:::external

  subgraph "Repo Working Tree (Source)"
  direction TB
    SRC_LUA["Lua Source\nBox_Creator_Ver_dev.lua"]:::logic
    SRC_HTML["HTML Source\nBox_Creator_Ver_dev.html"]:::ui
    SRC_CSS["CSS Directory\nstylesheets/"]:::asset
    SRC_IMG["Images Directory\nImages/"]:::asset
    DOCS["Docs\nREADME.md"]:::doc
    META["Repo Metadata\n.gitattributes"]:::meta
  end

  PKG["Release Automation\nMakeRelease.ps1 (PowerShell)"]:::build

  subgraph "Release Output"
  direction TB
    RELDIR["Release Directory\nrelease/"]:::artifact
    VG56[".vgadget Artifact\nBox_Creator_Ver_5.6.vgadget"]:::artifact
    VG57[".vgadget Artifact\nBox_Creator_Ver_5.7.vgadget"]:::artifact
    VG58[".vgadget Artifact\nBox_Creator_Ver_5.8.vgadget"]:::artifact
  end

  INSTALL["Installed Gadget Package\n(.vgadget)"]:::artifact

  %% Build flow connections
  DEV -->|"edits"| SRC_LUA
  DEV -->|"edits"| SRC_HTML
  DEV -->|"edits"| SRC_CSS
  DEV -->|"edits"| SRC_IMG
  DEV -->|"follows"| DOCS

  SRC_LUA -->|"input"| PKG
  SRC_HTML -->|"input"| PKG
  SRC_CSS -->|"input"| PKG
  SRC_IMG -->|"input"| PKG

  PKG -->|"packages/renames/emits"| RELDIR
  RELDIR -->|"contains"| VG56
  RELDIR -->|"contains"| VG57
  RELDIR -->|"contains"| VG58

  VG56 -->|"install/use"| INSTALL
  VG57 -->|"install/use"| INSTALL
  VG58 -->|"install/use"| INSTALL

  INSTALL -->|"loaded_by"| VApp
end

%% =================
%% Click Events
%% =================
click LUALOGIC "https://github.com/gremlin529/vectric-box-gadget/blob/main/Box_Creator_Ver_dev.lua"
click SRC_LUA "https://github.com/gremlin529/vectric-box-gadget/blob/main/Box_Creator_Ver_dev.lua"

click UIHTML "https://github.com/gremlin529/vectric-box-gadget/blob/main/Box_Creator_Ver_dev.html"
click SRC_HTML "https://github.com/gremlin529/vectric-box-gadget/blob/main/Box_Creator_Ver_dev.html"

click UICSS "https://github.com/gremlin529/vectric-box-gadget/tree/main/stylesheets/"
click SRC_CSS "https://github.com/gremlin529/vectric-box-gadget/tree/main/stylesheets/"

click UIIMG "https://github.com/gremlin529/vectric-box-gadget/tree/main/Images/"
click SRC_IMG "https://github.com/gremlin529/vectric-box-gadget/tree/main/Images/"

click PKG "https://github.com/gremlin529/vectric-box-gadget/blob/main/MakeRelease.ps1"

click RELDIR "https://github.com/gremlin529/vectric-box-gadget/tree/main/release/"
click VG56 "https://github.com/gremlin529/vectric-box-gadget/blob/main/release/Box_Creator_Ver_5.6.vgadget"
click VG57 "https://github.com/gremlin529/vectric-box-gadget/blob/main/release/Box_Creator_Ver_5.7.vgadget"
click VG58 "https://github.com/gremlin529/vectric-box-gadget/blob/main/release/Box_Creator_Ver_5.8.vgadget"

click DOCS "https://github.com/gremlin529/vectric-box-gadget/blob/main/README.md"
click META "https://github.com/gremlin529/vectric-box-gadget/blob/main/.gitattributes"

%% Optional: link specific css files (as separate nodes to maximize mapped clicks)
subgraph "Mapped Stylesheets (Files)"
direction TB
  CSS_IE["layout-css-8-ie.css"]:::asset
  CSS_LAYOUT["layout-css-8.css"]:::asset
  CSS_RESET["reset.css"]:::asset
end
UICSS -->|"includes"| CSS_RESET
UICSS -->|"includes"| CSS_LAYOUT
UICSS -->|"includes"| CSS_IE
click CSS_IE "https://github.com/gremlin529/vectric-box-gadget/blob/main/stylesheets/layout-css-8-ie.css"
click CSS_LAYOUT "https://github.com/gremlin529/vectric-box-gadget/blob/main/stylesheets/layout-css-8.css"
click CSS_RESET "https://github.com/gremlin529/vectric-box-gadget/blob/main/stylesheets/reset.css"

%% ==============
%% Styles / Color
%% ==============
classDef host fill:#0B3C5D,stroke:#06263A,color:#FFFFFF,stroke-width:1px
classDef api fill:#1D84B5,stroke:#11536F,color:#FFFFFF,stroke-width:1px
classDef data fill:#1B5E20,stroke:#0E3A13,color:#FFFFFF,stroke-width:1px

classDef ui fill:#6A1B9A,stroke:#3E105B,color:#FFFFFF,stroke-width:1px
classDef logic fill:#283593,stroke:#151C55,color:#FFFFFF,stroke-width:1px
classDef asset fill:#455A64,stroke:#263238,color:#FFFFFF,stroke-width:1px
classDef bridge fill:#00897B,stroke:#005B52,color:#FFFFFF,stroke-width:1px

classDef build fill:#EF6C00,stroke:#A64B00,color:#FFFFFF,stroke-width:1px
classDef artifact fill:#B71C1C,stroke:#7F1313,color:#FFFFFF,stroke-width:1px
classDef doc fill:#2E7D32,stroke:#1C4D1F,color:#FFFFFF,stroke-width:1px
classDef meta fill:#616161,stroke:#3D3D3D,color:#FFFFFF,stroke-width:1px

classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#111111,stroke-width:1px
```
