# barebaric/rayforge architecture

> Architecture diagram of the GitHub repository barebaric/rayforge, 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/barebaric/rayforge
- Repository: https://github.com/barebaric/rayforge

## Overview

##### Project Type and Purpose
- Rayforge is a full-featured, cross-platform desktop application (Python + GTK4 + Libadwaita) for sending and controlling G-code on GRBL-based laser cutters.
- It combines a rich GUI, a core data/model layer for vector and geometry operations, an importer subsystem, a pipeline for path generation and transformation, and a machine-communication layer.

##### High-Level Architectural Components
a. User Interface Layer (GTK4/Libadwaita)
- MainWindow, dialogs, preferences, canvas (2D/3D), camera overlay, machine status widgets.
- Modules: rayforge/app.py, main_menu.py, mainwindow.py; subpackages: camera/ui, doceditor/ui, machine/ui, shared/ui, workbench, undo/ui.
b. Core Data & Domain Logic
- Data models (items, layers, workflows), geometry operations, config, grouping, undo/redo.
- Modules: rayforge/core, rayforge/shared/units, rayforge/shared/util, rayforge/undo/models.
c. Importer Subsystem
- Parses and renders input formats (SVG, DXF, PDF, PNG, BMP, Ruida).
- Modules: rayforge/importer/*; format-specific importer/parser/renderer.
d. Pipeline & G-code Generation
- Takes core data to produce toolpaths, applies modifiers (filters, tabs), encodes to G-code or preview contexts.
- Modules: rayforge/pipeline/{producer,transformer,modifier,encoder,steprunner}.
e. Machine Communication Layer
- Sends G-code over Serial, HTTP, Telnet, WebSocket; driver abstraction for GRBL, Smoothieware, dummy.
- Modules: rayforge/machine/{driver,transport,models,ui}.
f. Background Tasking & Concurrency
- Offloads long-running jobs (import, pipeline, machine I/O) to a task manager.
- Modules: rayforge/shared/tasker.
g. Localization & Resources

##### Component Relationships and Data Flows
- User clicks or imports a file → UI Layer dispatches action to Core or Importer.
- Importer reads format → produces vector/document model in Core.
- Core model → passed to Pipeline Producer → generates raw path segments.
- Transformer and Modifier components → optimize, add tabs, apply filters.
- Encoder → produces G-code or preview context → displayed in 3D preview or sent to Machine layer.
- Machine Transport uses selected Driver to send G-code to laser cutter.
- Tasker runs heavy operations asynchronously, reporting progress back to UI.

##### Architectural Patterns & Design Principles
- Modular separation by responsibility: UI vs domain vs import vs pipeline vs machine.
- MVC/MVP flavor: UI views interact with controllers (actions.py, app.py) and update underlying model.
- Strategy/Plugin pattern in Importer and Machine Driver subsystems to support extensibility.
- Command pattern for undo/redo in core and doceditor (undo/models, doceditor/edit_cmd).
- Task queue for concurrency (shared/tasker).

##### Key Technologies & Frameworks
- Python 3, GTK4, Libadwaita for GUI.
- PyGObject for GObject introspection.
- External libs: pyvips, potrace, optional OpenCV for camera integration.
- Build/packaging: Pixi (pixi.toml), Meson/pyproject.toml, Snap, Flatpak, Debian packaging.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "User Interface Layer" 
        direction TB
        App["App Entry & MainWindow"]:::ui
        MainMenu["Main Menu"]:::ui
        CameraUI["Camera UI"]:::ui
        DocEditorUI["Document Editor UI"]:::ui
        MachineUI["Machine UI"]:::ui
        SharedUI["Shared UI Components"]:::ui
        Workbench["Workbench Canvas & Overlays"]:::ui
    end

    %% Core Data & Domain Logic
    subgraph "Core Data & Domain Logic"
        direction TB
        CoreModels["Core Models & Geometry"]:::core
        Config["Configuration"]:::core
        UndoModels["Undo/Redo Models"]:::core
    end

    %% Importer Subsystem
    subgraph "Importer Subsystem"
        direction TB
        ImportBase["Base Interfaces"]:::importer
        SVG["SVG Importer"]:::importer
        DXF["DXF Importer"]:::importer
        PDF["PDF Importer"]:::importer
        PNG["PNG Importer"]:::importer
        BMP["BMP Importer"]:::importer
        Ruida["Ruida Job Importer"]:::importer
    end

    %% Pipeline & G-code Generation
    subgraph "Pipeline & G-code Generation"
        direction TB
        Producer["Producer Stage"]:::pipeline
        Transformer["Transformer Stage"]:::pipeline
        Modifier["Modifier Stage"]:::pipeline
        Encoder["Encoder Stage"]:::pipeline
        Orchestration["Orchestration"]:::pipeline
    end

    %% Machine Communication Layer
    subgraph "Machine Communication Layer"
        direction TB
        Drivers["Drivers"]:::machine
        Transports["Transports"]:::machine
        MachineModels["Machine Models"]:::machine
        CmdAPI["Command API"]:::machine
    end

    %% Tasker
    Tasker["Background Tasking & Concurrency"]:::tasker

    %% External Systems
    subgraph "External & OS Services"
        direction TB
        SerialPort["Serial Port"]:::external
        HTTP["HTTP"]:::external
        Telnet["Telnet"]:::external
        WebSocket["WebSocket"]:::external
        FileSystem["File System"]:::external
        Camera["Camera"]:::external
    end

    %% Connections
    App -->|"dispatch action"| CoreModels
    App -->|"open dialog"| MainMenu
    App -->|"render UI"| Workbench
    App -->|"invoke camera"| CameraUI
    App -->|"open editor"| DocEditorUI
    App -->|"open machine"| MachineUI
    App -->|"use shared components"| SharedUI

    CoreModels -->|"uses geometry"| CoreModels
    CoreModels -->|"config load"| Config
    CoreModels -->|"undo/redo"| UndoModels

    App -->|"import file"| ImportBase
    ImportBase -->|"SVG parse"| SVG
    ImportBase -->|"DXF parse"| DXF
    ImportBase -->|"PDF parse"| PDF
    ImportBase -->|"PNG parse"| PNG
    ImportBase -->|"BMP parse"| BMP
    ImportBase -->|"Ruida parse"| Ruida
    SVG -->|"produces model"| CoreModels
    DXF -->|"produces model"| CoreModels
    PDF -->|"produces model"| CoreModels
    PNG -->|"produces model"| CoreModels
    BMP -->|"produces model"| CoreModels
    Ruida -->|"produces model"| CoreModels

    CoreModels -->|"DocumentModel"| Producer
    Producer -->|"raw segments"| Transformer
    Transformer -->|"optimized paths"| Modifier
    Modifier -->|"filtered toolpath"| Encoder
    Encoder -->|"G-code / Preview"| Workbench
    Encoder -->|"G-code"| CmdAPI

    Tasker -.->|"async import"| ImportBase
    Tasker -.->|"async pipeline"| Producer
    Tasker -.->|"async I/O"| CmdAPI
    Tasker -->|"progress feedback"| App

    CmdAPI -->|"send commands"| Transports
    Transports -->|"use driver"| Drivers
    Drivers -->|"communicate"| SerialPort
    Drivers -->|"communicate"| HTTP
    Drivers -->|"communicate"| Telnet
    Drivers -->|"communicate"| WebSocket

    Workbench -->|"load assets"| FileSystem
    CameraUI -->|"capture image"| Camera

    %% Click Events
    click App "https://github.com/barebaric/rayforge/blob/main/rayforge/app.py"
    click MainMenu "https://github.com/barebaric/rayforge/blob/main/rayforge/main_menu.py"
    click CameraUI "https://github.com/barebaric/rayforge/tree/main/rayforge/camera/ui/"
    click DocEditorUI "https://github.com/barebaric/rayforge/tree/main/rayforge/doceditor/ui/"
    click MachineUI "https://github.com/barebaric/rayforge/tree/main/rayforge/machine/ui/"
    click SharedUI "https://github.com/barebaric/rayforge/tree/main/rayforge/shared/ui/"
    click Workbench "https://github.com/barebaric/rayforge/tree/main/rayforge/workbench/"
    click CoreModels "https://github.com/barebaric/rayforge/tree/main/rayforge/core/"
    click Config "https://github.com/barebaric/rayforge/blob/main/rayforge/core/config.py"
    click UndoModels "https://github.com/barebaric/rayforge/tree/main/rayforge/undo/models/"
    click ImportBase "https://github.com/barebaric/rayforge/blob/main/rayforge/importer/base_importer.py"
    click SVG "https://github.com/barebaric/rayforge/tree/main/rayforge/importer/svg/"
    click DXF "https://github.com/barebaric/rayforge/tree/main/rayforge/importer/dxf/"
    click PDF "https://github.com/barebaric/rayforge/tree/main/rayforge/importer/pdf/"
    click PNG "https://github.com/barebaric/rayforge/tree/main/rayforge/importer/png/"
    click BMP "https://github.com/barebaric/rayforge/tree/main/rayforge/importer/bmp/"
    click Ruida "https://github.com/barebaric/rayforge/tree/main/rayforge/importer/ruida/"
    click Producer "https://github.com/barebaric/rayforge/tree/main/rayforge/pipeline/producer/"
    click Transformer "https://github.com/barebaric/rayforge/tree/main/rayforge/pipeline/transformer/"
    click Modifier "https://github.com/barebaric/rayforge/tree/main/rayforge/pipeline/modifier/"
    click Encoder "https://github.com/barebaric/rayforge/tree/main/rayforge/pipeline/encoder/"
    click Orchestration "https://github.com/barebaric/rayforge/blob/main/rayforge/pipeline/generator.py"
    click Drivers "https://github.com/barebaric/rayforge/tree/main/rayforge/machine/driver/"
    click Transports "https://github.com/barebaric/rayforge/tree/main/rayforge/machine/transport/"
    click MachineModels "https://github.com/barebaric/rayforge/tree/main/rayforge/machine/models/"
    click CmdAPI "https://github.com/barebaric/rayforge/blob/main/rayforge/machine/cmd.py"
    click Tasker "https://github.com/barebaric/rayforge/tree/main/rayforge/shared/tasker/"
    click SerialPort "https://github.com/barebaric/rayforge/tree/main/External: Serial Port"
    click HTTP "https://github.com/barebaric/rayforge/tree/main/External: HTTP"
    click Telnet "https://github.com/barebaric/rayforge/tree/main/External: Telnet"
    click WebSocket "https://github.com/barebaric/rayforge/tree/main/External: WebSocket"
    click FileSystem "https://github.com/barebaric/rayforge/tree/main/External: File System"
    click Camera "https://github.com/barebaric/rayforge/tree/main/External: Camera"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef importer fill:#FFA500,stroke:#000,stroke-width:1px
    classDef pipeline fill:#FFA500,stroke:#000,stroke-width:1px
    classDef machine fill:#FFA500,stroke:#000,stroke-width:1px
    classDef tasker fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
