# jack000/deepnest architecture

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

- Interactive diagram: https://gitdiagram.com/jack000/deepnest
- Repository: https://github.com/jack000/deepnest

## Overview

##### Project type and purpose
- This is a desktop nesting tool (“Deepnest”) built on Electron.
- It uses a C++ native addon (the Minkowski engine) for speed-critical geometry operations, plus a JavaScript/HTML/CSS frontend (SVGNest-derived) for user interaction and visualization.

##### File structure
- Top level:
- package.json – project metadata and Electron scripts
- binding.gyp / binding.windowsgyp / binding.gyp mac – build configs for the native C++ addon
- main.js – Electron “main” process entry point
- renderer.js – common logic injected into the renderer
- addon.cc – C++ glue layer exposing the Minkowski engine as a Node module
- “minkowski/” directory:
- Pure C/C++ code + Makefiles + compiled outputs (Release/addon.node) – the fast nesting engine
- “main/” directory:
- HTML (index.html, background.html, login.html), CSS (style.css), background scripts, deepnest.js, svgparser.js – the UI & business logic
- “util/” subfolder – helper libraries (clipper.js, d3-polygon.js, ractive.js, etc.)

##### README
- Confirms it’s a desktop app for laser-cut nesting.
- Highlights new C engine, DXF support, path approximation.

a. Main components
- Electron Main Process (Node.js + OS integration)
- Renderer Process (BrowserWindow hosting HTML/CSS/JS)
- Native Addon Module (minkowski engine in C/C++)
- File System (SVG/DXF input & export)
- Utility Libraries (clipper, d3-polygon, ractive, etc.)

b. Relationships & interactions
1. User launches app → Electron Main Process
2. Main spawns Renderer (loads index.html + deepnest.js + util)
3. Renderer sends IPC calls to Main for file I/O, menu commands
4. Renderer calls the native addon (require('addon.node')) for heavy geometry (Minkowski sums, nesting)
5. Native addon returns processed geometry back to Renderer
7. Main handles saving/export (SVG/DXF), external commands

c. Architectural patterns & principles
- Multi-process separation (Main vs Renderer) per Electron best practices
- Native addon for CPU-intensive tasks – keeps JS thread responsive
- Modular JS code (util/ helpers, core UI logic in deepnest.js)
- Clear layering: UI ← business logic ← geometry engine

d. Key technologies
- Electron (desktop shell, IPC)
- Node native addons (binding.gyp, C++ addon.cc)
- HTML/CSS/JS (Ractive.js templating, D3, SVG)
- Geometry libs (Clipper, Minkowski C code)

##### Detail
- Binding.gyp and Makefiles under the native addon area
- IPC channels are annotated (e.g., “ipcMain.on('nest')”)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Entities
    User["User"]:::external

    %% Electron App
    subgraph "Electron App"
        subgraph "Main Process"
            MainJS["main.js"]:::core
            RendererJS["renderer.js"]:::core
            BackgroundJS["background.js"]:::core
            BackgroundSingleJS["background single.js"]:::core
        end

        subgraph "Renderer Process (UI Layer)"
            IndexHTML["index.html"]:::ui
            BackgroundHTML["background.html"]:::ui
            LoginHTML["login.html"]:::ui
            StyleCSS["style.css"]:::ui
            DeepnestJS["deepnest.js"]:::ui
            SvgnestJS["svgnest.js"]:::ui
            SvgParserJS["svgparser.js"]:::ui

            subgraph "Util Libraries"
                Clipper["clipper.js"]:::lib
                ClipperNode["clippernode.js"]:::lib
                D3Polygon["d3-polygon.js"]:::lib
                DomParser["domparser.js"]:::lib
                Eval["eval.js"]:::lib
                FileSaver["filesaver.js"]:::lib
                GeometryUtil["geometryutil.js"]:::lib
                Hull["hull.js"]:::lib
                Interact["interact.js"]:::lib
                Json["json.js"]:::lib
                Matrix["matrix.js"]:::lib
                Parallel["parallel.js"]:::lib
                Pathsegpolyfill["pathsegpolyfill.js"]:::lib
                PlacementWorker["placementworker.js"]:::lib
                Ractive["ractive.js"]:::lib
                Simplify["simplify.js"]:::lib
                SvgPanZoom["svgpanzoom.js"]:::lib
            end
        end
    end

    %% Native Addon Module
    subgraph "Native Addon Module (C/C++ Minkowski Engine)"
        AddonCC["addon.cc"]:::native
        BindGyp["binding.gyp"]:::native
        BindWinGyp["binding.windowsgyp"]:::native
        BindMacGyp["binding.gyp mac"]:::native
        MinkThread["thread.cc"]:::native
        MinkCC["minkowski.cc"]:::native
        MinkH["minkowski.h"]:::native
        Makefile["Makefile"]:::native
        BindingMake["binding.Makefile"]:::native
        ConfigGypi["config.gypi"]:::native
        GypMacTool["gyp-mac-tool"]:::native
        AddonNode["Release/addon.node"]:::native
    end

    %% File System
    FileSystem["File System (SVG/DXF)"]:::external
    SVGFile["SVG File"]:::external
    DXFFile["DXF File"]:::external

    %% Data Flows
    User -->|"launch app"| MainJS
    MainJS -->|"spawn Renderer"| IndexHTML
    MainJS --> RendererJS
    RendererJS -->|"ipc|ipcMain"| MainJS
    RendererJS -->|"ipc|ipcRenderer"| MainJS

    IndexHTML --> DeepnestJS
    DeepnestJS --> SvgParserJS
    DeepnestJS --> Clipper
    DeepnestJS --> D3Polygon
    %% simplify showing util grouping
    DeepnestJS --> SvgPanZoom

    DeepnestJS -->|"geometry calls"| AddonNode
    AddonNode -->|"results"| DeepnestJS
    DeepnestJS -->|"render"| IndexHTML

    MainJS -->|"save/export"| FileSystem
    RendererJS -->|"load file"| FileSystem

    FileSystem --> SVGFile
    FileSystem --> DXFFile
    DXFFile --> SvgParserJS

    %% Click Events
    click MainJS "https://github.com/jack000/deepnest/blob/master/main.js"
    click RendererJS "https://github.com/jack000/deepnest/blob/master/renderer.js"
    click BackgroundJS "https://github.com/jack000/deepnest/blob/master/main/background.js"
    click BackgroundSingleJS "https://github.com/jack000/deepnest/blob/master/main/background single.js"

    click IndexHTML "https://github.com/jack000/deepnest/blob/master/main/index.html"
    click BackgroundHTML "https://github.com/jack000/deepnest/blob/master/main/background.html"
    click LoginHTML "https://github.com/jack000/deepnest/blob/master/main/login.html"
    click StyleCSS "https://github.com/jack000/deepnest/blob/master/main/style.css"
    click DeepnestJS "https://github.com/jack000/deepnest/blob/master/main/deepnest.js"
    click SvgnestJS "https://github.com/jack000/deepnest/blob/master/main/svgnest.js"
    click SvgParserJS "https://github.com/jack000/deepnest/blob/master/main/svgparser.js"

    click AddonCC "https://github.com/jack000/deepnest/blob/master/addon.cc"
    click BindGyp "https://github.com/jack000/deepnest/blob/master/binding.gyp"
    click BindWinGyp "https://github.com/jack000/deepnest/blob/master/binding.windowsgyp"
    click BindMacGyp "https://github.com/jack000/deepnest/blob/master/binding.gyp mac"
    click MinkThread "https://github.com/jack000/deepnest/blob/master/minkowski/thread.cc"
    click MinkCC "https://github.com/jack000/deepnest/blob/master/minkowski/minkowski.cc"
    click MinkH "https://github.com/jack000/deepnest/blob/master/minkowski/minkowski.h"
    click Makefile "https://github.com/jack000/deepnest/tree/master/minkowski/Makefile"
    click BindingMake "https://github.com/jack000/deepnest/blob/master/minkowski/binding.Makefile"
    click ConfigGypi "https://github.com/jack000/deepnest/blob/master/minkowski/config.gypi"
    click GypMacTool "https://github.com/jack000/deepnest/tree/master/minkowski/gyp-mac-tool"
    click AddonNode "https://github.com/jack000/deepnest/blob/master/minkowski/Release/addon.node"

    click Clipper "https://github.com/jack000/deepnest/blob/master/main/util/clipper.js"
    click ClipperNode "https://github.com/jack000/deepnest/blob/master/main/util/clippernode.js"
    click D3Polygon "https://github.com/jack000/deepnest/blob/master/main/util/d3-polygon.js"
    click DomParser "https://github.com/jack000/deepnest/blob/master/main/util/domparser.js"
    click Eval "https://github.com/jack000/deepnest/blob/master/main/util/eval.js"
    click FileSaver "https://github.com/jack000/deepnest/blob/master/main/util/filesaver.js"
    click GeometryUtil "https://github.com/jack000/deepnest/blob/master/main/util/geometryutil.js"
    click Hull "https://github.com/jack000/deepnest/blob/master/main/util/hull.js"
    click Interact "https://github.com/jack000/deepnest/blob/master/main/util/interact.js"
    click Json "https://github.com/jack000/deepnest/blob/master/main/util/json.js"
    click Matrix "https://github.com/jack000/deepnest/blob/master/main/util/matrix.js"
    click Parallel "https://github.com/jack000/deepnest/blob/master/main/util/parallel.js"
    click Pathsegpolyfill "https://github.com/jack000/deepnest/blob/master/main/util/pathsegpolyfill.js"
    click PlacementWorker "https://github.com/jack000/deepnest/blob/master/main/util/placementworker.js"
    click Ractive "https://github.com/jack000/deepnest/blob/master/main/util/ractive.js"
    click Simplify "https://github.com/jack000/deepnest/blob/master/main/util/simplify.js"
    click SvgPanZoom "https://github.com/jack000/deepnest/blob/master/main/util/svgpanzoom.js"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#2980B9
    classDef core fill:#D5F5E3,stroke:#27AE60
    classDef native fill:#FCF3CF,stroke:#F1C40F
    classDef external fill:#EEEEEE,stroke:#7F8C8D
    classDef lib fill:#FADBD8,stroke:#E74C3C
```
