# shreyansh-shankar/nodebox architecture

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

- Interactive diagram: https://gitdiagram.com/shreyansh-shankar/nodebox
- Repository: https://github.com/shreyansh-shankar/nodebox

## Overview

##### Project type and purpose
- A native desktop application (PyQt6) for visually building Python-based automation workflows.
- Key goal: drag-drop nodes (each a Python snippet), connect them into pipelines, integrate local LLM models via Ollama.

##### File structure
- Top-level executables and configs:
- main.py – application entry point.
- requirements.txt, .pre-commit, CI workflows.
- Core modules by directory:
- ui/ – all Qt window classes (main window, automation dialogs, placeholders).
- canvasmanager/ – logic for the node canvas, connection handling, save/load.
- automation_manager/ – node definitions, editor window, palette, port abstractions.
- browsemodels_manager/ – UI and logic to browse/download/manage Ollama models.
- features/ – plug-ins: debug console, export/import, scheduler, performance monitor, node templates.
- predefined/ – built-in node implementations and registry.
- utils/ – shared utilities: font loading, node execution runner, path management, performance bus.
- Other assets:
- qss/ – custom Qt styles.
- public/ – static website files (docs, downloads).
- firebase.json – hosting config for docs site.
- test_predefined_nodes.py – unit tests for predefined nodes.

##### README for additional insights
- Confirms three high-level concerns: UI, node/graph engine, model management.
- Emphasizes Ollama integration (local LLM service).

##### Main components & interactions
A. Components
1. User Interface Layer
- MainWindow, CanvasWidget, NodeEditorWindow, BrowseModelWindow, etc.
2. Canvas & Graph Engine
- canvasmanager classes handle drawing, connections, serialization (save/load).
3. Automation Manager
- Core node abstractions (Node, Port), node palette, node editor dialogs.
4. Model Browser & Download Manager
- Communicates with local Ollama server to list/download models.
5. Execution Engine
- utils/node_runner executes graph by invoking node code in order.
6. Predefined Node Library
- Built-in nodes for file I/O, data processing, LLM calls.
7. Feature Modules
- Debug console, workflow scheduler, performance monitor, export/import, templates.
8. File System / Persistence
- Saves workflows, node definitions, downloaded model files.
9. External Services
- Ollama local server (LLM inference).
B. Interactions and data flow
- UI events (drag/drop, connect nodes) → Canvas Engine updates graph model.
- Node creation/editing → Automation Manager (NodeEditor) persists node code.
- Running a workflow → Execution Engine reads graph model → invokes NodeRunner → Python code execution in each node.
- Browse Models UI → BrowseModels Manager sends HTTP to Ollama server → downloads model artifacts to local disk.
- Saving/loading workflows → File I/O flows through canvasmanager.saveload_methods.
- Feature modules attach via event hooks or menu actions.

##### Architectural patterns & principles
- Model-View-Controller (MVC) or Model-View-Presenter in UI: separate Qt widgets (views) from canvas model / node model.
- Plugin-style features loaded dynamically (features/ directory).
- Modular separation: each concern in its own package.
- Event bus or signal/slot pattern (Qt signals, utils/performance_bus).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        UI1["Enhanced Main Window"]:::internal
        UI2["New Automation Window"]:::internal
        UI3["Placeholder Widget"]:::internal
        UI4["Node Editor Window"]:::internal
        UI5["Browse Model Window"]:::internal
        UI6["Downloaded Models Window"]:::internal
        UI7["Filter Window"]:::internal
        UI8["Model Card"]:::internal
    end

    %% Core Logic Layer
    subgraph "Core Logic"
        direction TB
        subgraph "Canvas & Graph Engine"
            direction TB
            C1["Canvas Widget"]:::internal
            C2["Canvas Node Methods"]:::internal
            C3["Ports Handler"]:::internal
            C4["Save/Load Methods"]:::internal
        end
        subgraph "Automation Manager"
            direction TB
            A1["Node"]:::internal
            A2["Connection"]:::internal
            A3["Ports"]:::internal
            A4["Node Palette"]:::internal
            A5["Node Editor Dialog"]:::internal
            A6["Node Editor Window"]:::internal
        end
        subgraph "Model Browser & Download Manager"
            direction TB
            M1["Download Manager"]:::internal
            M2["Browse Model Window"]:::internal
            M3["Downloaded Models Window"]:::internal
            M4["Filter Window"]:::internal
            M5["Model Card"]:::internal
        end
    end

    %% Feature Modules
    subgraph "Feature Modules"
        direction TB
        F1["Debug Console"]:::internal
        F2["Export/Import"]:::internal
        F3["Node Templates"]:::internal
        F4["Performance Monitor"]:::internal
        F5["Workflow Scheduler"]:::internal
    end

    %% Execution & Persistence Layer
    subgraph "Execution & Persistence"
        direction TB
        E1["Node Runner"]:::internal
        DB1[(Filesystem / Assets)]:::db
        DB2[(Styles/QSS)]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        EXT1["Ollama Local Server"]:::external
    end

    %% Application Entry Point & Config
    subgraph "Entry & Config"
        direction TB
        MAIN["main.py"]:::internal
        CONF1["requirements.txt"]:::internal
        CONF2[".pre-commit-config.yaml"]:::internal
        CONF3["ci.yml"]:::internal
        CONF4["firebase.json"]:::internal
    end

    %% Interactions
    MAIN -->|launches| UI1
    UI1 -->|signals| C1
    UI2 -->|signals| C1
    UI4 -->|edits nodes| A5
    UI5 -->|browse models| M1
    M1 -->|HTTP| EXT1
    EXT1 -->|model artifacts| DB1
    C1 -->|draw/connect| A1
    A6 -->|create/edit| A5
    C4 -->|read/write workflows| DB1
    UI7 -->|filter UI| M4
    UI8 -->|display| M5
    C1 -->|serialize| C4
    MAIN -->|executing workflow| E1
    E1 -->|invokes| A1
    E1 -->|runs| DB2
    F1 -->|hooks into| UI1
    F2 -->|export/import| DB1
    F3 -->|templates| A4
    F4 -->|monitor| E1
    F5 -->|schedule| E1

    %% Click Events
    click UI1 "https://github.com/shreyansh-shankar/nodebox/blob/main/ui/enhanced_main_window.py"
    click UI2 "https://github.com/shreyansh-shankar/nodebox/blob/main/ui/newautomation_window.py"
    click UI3 "https://github.com/shreyansh-shankar/nodebox/blob/main/ui/placeholder_widget.py"
    click UI4 "https://github.com/shreyansh-shankar/nodebox/blob/main/automation_manager/node_editor_window.py"
    click UI5 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/browsemodel_window.py"
    click UI6 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/downloaded_models_window.py"
    click UI7 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/filter_window.py"
    click UI8 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/model_card.py"
    click C1 "https://github.com/shreyansh-shankar/nodebox/blob/main/canvasmanager/canvas_widget.py"
    click C2 "https://github.com/shreyansh-shankar/nodebox/blob/main/canvasmanager/canvas_nodemethods.py"
    click C3 "https://github.com/shreyansh-shankar/nodebox/blob/main/canvasmanager/ports_handler.py"
    click C4 "https://github.com/shreyansh-shankar/nodebox/blob/main/canvasmanager/saveload_methods.py"
    click A1 "https://github.com/shreyansh-shankar/nodebox/blob/main/automation_manager/node.py"
    click A2 "https://github.com/shreyansh-shankar/nodebox/blob/main/automation_manager/connection.py"
    click A3 "https://github.com/shreyansh-shankar/nodebox/blob/main/automation_manager/ports.py"
    click A4 "https://github.com/shreyansh-shankar/nodebox/blob/main/automation_manager/node_pallete.py"
    click A5 "https://github.com/shreyansh-shankar/nodebox/blob/main/automation_manager/nodeeditor_dialog.py"
    click A6 "https://github.com/shreyansh-shankar/nodebox/blob/main/automation_manager/node_editor_window.py"
    click M1 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/downlaod_manager.py"
    click M2 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/browsemodel_window.py"
    click M3 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/downloaded_models_window.py"
    click M4 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/filter_window.py"
    click M5 "https://github.com/shreyansh-shankar/nodebox/blob/main/browsemodels_manager/model_card.py"
    click E1 "https://github.com/shreyansh-shankar/nodebox/blob/main/utils/node_runner.py"
    click MAIN "https://github.com/shreyansh-shankar/nodebox/blob/main/main.py"

    %% Styles
    classDef internal fill:#A8D5E2,stroke:#333,stroke-width:1px
    classDef external fill:#E2A8D5,stroke-dasharray: 5 5,stroke:#333
    classDef db fill:#E2E2A8,stroke:#333,stroke-width:1px
```
