# nishchaybhutoria/node-based-image-processor architecture

> Architecture diagram of the GitHub repository nishchaybhutoria/node-based-image-processor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nishchaybhutoria/node-based-image-processor
- Repository: https://github.com/nishchaybhutoria/node-based-image-processor

## Overview

1. **Overall shape**
   - This is a **C++ desktop image-processing editor** with a **visual node graph** as the main interaction model.
   - The app is not a web service or batch pipeline; it is an interactive GUI application where users assemble an image pipeline, inspect previews, and export the result.

2. **Top-level runtime stack**
   - `src/main.cpp` is the application entry point and likely owns the main loop, window setup, and per-frame update/render flow.
   - The UI is built on **Dear ImGui** plus **ImNodes** for node-graph editing, with **GLFW + OpenGL** providing the desktop windowing and rendering layer.
   - The repository includes the ImGui/ImNodes sources and GLFW/OpenGL backends directly, so the UI stack is embedded in the repo rather than pulled in as an external app framework.

3. **Core architecture boundary**
   - `src/core/Node.h` defines the base abstraction for all nodes.
   - `src/core/Graph.h` manages the collection of nodes and links, including evaluation order and validation.
   - This separation creates a clear boundary between:
     - the **editor/runtime graph model**,
     - and the **concrete image-processing operations** implemented by individual nodes.

4. **Graph evaluation and correctness**
   - The graph subsystem is responsible for **link management**, **topological sorting**, and **cycle detection**.
   - The README indicates it uses **Kahn’s algorithm** to compute execution order and reject cyclic graphs.
   - This means the pipeline is evaluated as a directed acyclic graph, not as arbitrary connected nodes, which is a key architectural constraint.

5. **Node execution model**
   - Each node inherits from the base node class and overrides behavior such as processing, preview generation, and property-panel rendering.
   - The available node types in `src/nodes/` show the current pipeline stages:
     - `InputNode`
     - `BrightnessContrastNode`
     - `BlurNode`
     - `OutputNode`
   - The node system is designed so each node owns its own parameters and can contribute both to computation and UI.

6. **Concrete pipeline data flow**
   - The usual flow is: **Input node loads an image → intermediate effect nodes transform it → Output node saves or previews the final result**.
   - Intermediate nodes operate on image data and pass results downstream through graph links.
   - The graph therefore acts as the control plane for dependencies, while the nodes themselves are the data-plane operators.

7. **Image-processing backend**
   - OpenCV is the core image-processing library, used for loading, manipulating, and saving images.
   - The README explicitly mentions `imwrite` for export and support for JPG quality options.
   - This means the image pipeline is backed by CPU-side image matrices rather than GPU shader processing.

8. **Texture and preview bridge**
   - `src/utils/TextureUtils.h` is the bridge between image data and rendering.
   - Its role is likely to convert processed OpenCV images into OpenGL textures so the GUI can display previews inside node panels and output views.
   - This is the main boundary between the image-processing world and the rendering/UI world.

9. **Editor interaction layer**
   - ImGui and ImNodes provide the interactive node editor: creating nodes, connecting ports, deleting links, and editing node parameters.
   - The README highlights right-click node creation, drag-and-drop linking, and ALT+click link deletion.
   - Node property controls are rendered inside the same UI loop, which keeps editing and inspection tightly coupled.

10. **Input and output nodes as system edges**
   - `InputNode` is the ingestion boundary, handling image file loading and metadata display.
   - `OutputNode` is the egress boundary, responsible for final preview and export to disk.
   - These two nodes define where external filesystem data enters and leaves the graph.

11. **Presentational vs processing responsibilities**
   - The architecture cleanly separates:
     - **UI state and node editor interactions**,
     - **graph structure and validation**,
     - **image transformation logic**,
     - **OpenGL texture presentation**.
   - That separation is important for diagramming: the graph does not render images itself, and the node implementations do not own the main application loop.

12. **Assets and packaging**
   - `assets/` contains runtime resources such as the font and test image referenced by the README.
   - The build is centered in `src/Makefile`, which suggests a simple native build workflow rather than a large multi-module build system.
   - The app expects a specific working directory layout, which matters because asset paths are relative.

13. **Architectural limits / scope**
   - The project currently implements a small set of image nodes and does not include serialization, undo/redo, or the more advanced planned filters mentioned in the README.
   - So the architecture is intentionally lightweight: a manually built visual graph editor with a few core operators rather than a generalized node-runtime platform.

14. **Best diagram boundaries**
   - For an architecture diagram, the clearest major blocks are:
     - **Desktop UI shell**: GLFW/OpenGL + ImGui/ImNodes
     - **Graph engine**: `Graph` and base `Node`
     - **Node implementations**: input, output, brightness/contrast, blur
     - **Image backend**: OpenCV
     - **Texture bridge**: OpenCV image → OpenGL preview
     - **Assets/filesystem**: fonts, sample image, export output

Main entry points: [`imgui/imgui.h`](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imgui.h) (Dear ImGui), [`src/core/Node.h`](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/core/Node.h) (Node base), [`src/main.cpp`](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/main.cpp) (Main loop), [`src/nodes/InputNode.h`](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/InputNode.h) (Input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop app"]
  node_main["Main loop<br/>app entry<br/>[main.cpp]"]
end

subgraph group_graph["Graph engine"]
  node_graph["Graph<br/>DAG model<br/>[Graph.h]"]
  node_node_base["Node base<br/>node interface<br/>[Node.h]"]
end

subgraph group_nodes["Node types"]
  node_input_node["Input<br/>source node<br/>[InputNode.h]"]
  node_brightness_node["Brightness<br/>effect node"]
  node_blur_node["Blur<br/>effect node<br/>[BlurNode.h]"]
  node_output_node["Output<br/>sink node<br/>[OutputNode.h]"]
end

subgraph group_ui["UI stack"]
  node_imgui["Dear ImGui<br/>ui library<br/>[imgui.h]"]
  node_imnodes["ImNodes<br/>graph-ui<br/>[imnodes.h]"]
end

subgraph group_bridge["Preview bridge"]
  node_texture_utils["Textures<br/>preview bridge<br/>[TextureUtils.h]"]
  node_opencv["OpenCV<br/>image backend"]
end

subgraph group_vendor["Embedded deps"]
  node_glfw_backend["GLFW backend<br/>window backend<br/>[imgui_impl_glfw.h]"]
  node_opengl_backend["OpenGL backend<br/>render backend"]
  node_imgui_core["ImGui core<br/>vendor source<br/>[imgui.cpp]"]
  node_imnodes_core["ImNodes core<br/>vendor source<br/>[imnodes.cpp]"]
end

subgraph group_assets["Assets"]
  node_assets["Assets<br/>runtime files"]
end

node_main -->|"builds"| node_graph
node_main -->|"drives UI"| node_imgui
node_main -->|"renders previews"| node_texture_utils
node_graph -->|"contains"| node_node_base
node_input_node -->|"inherits"| node_node_base
node_brightness_node -->|"inherits"| node_node_base
node_blur_node -->|"inherits"| node_node_base
node_output_node -->|"inherits"| node_node_base
node_input_node -->|"loads image"| node_opencv
node_brightness_node -->|"processes pixels"| node_opencv
node_blur_node -->|"processes pixels"| node_opencv
node_output_node -->|"writes image"| node_opencv
node_output_node -->|"previews result"| node_texture_utils
node_texture_utils -->|"uploads texture"| node_opengl_backend
node_imgui -->|"uses"| node_glfw_backend
node_imgui -->|"uses"| node_opengl_backend
node_imgui -->|"hosts"| node_imnodes
node_imgui_core -->|"implements"| node_imgui
node_imnodes_core -->|"implements"| node_imnodes
node_assets -->|"feeds runtime"| node_main
node_input_node -->|"uses sample image"| node_assets

click node_main "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/main.cpp"
click node_graph "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/core/Graph.h"
click node_node_base "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/core/Node.h"
click node_input_node "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/InputNode.h"
click node_brightness_node "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/BrightnessContrastNode.h"
click node_blur_node "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/BlurNode.h"
click node_output_node "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/OutputNode.h"
click node_texture_utils "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/utils/TextureUtils.h"
click node_imgui "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imgui.h"
click node_imnodes "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imnodes.h"
click node_glfw_backend "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/backends/imgui_impl_glfw.h"
click node_opengl_backend "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/backends/imgui_impl_opengl3.h"
click node_imgui_core "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imgui.cpp"
click node_imnodes_core "https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imnodes.cpp"
click node_assets "https://github.com/nishchaybhutoria/node-based-image-processor/tree/main/assets"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_assets toneBlue
class node_graph,node_node_base toneAmber
class node_input_node,node_brightness_node,node_blur_node,node_output_node toneMint
class node_imgui,node_imnodes toneRose
class node_texture_utils,node_opencv toneIndigo
class node_glfw_backend,node_opengl_backend,node_imgui_core,node_imnodes_core toneTeal
```

## Components

### Desktop app

Application entry point and the interactive editor shell.

- [Main loop](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/main.cpp): app entry · Starts the desktop app, owns the frame loop, and coordinates editor/runtime flow. · `src/main.cpp`

### Graph engine

Core DAG model, validation, and node abstraction.

- [Graph](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/core/Graph.h): DAG model · Stores nodes and links, validates structure, and computes execution order. · `src/core/Graph.h`
- [Node base](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/core/Node.h): node interface · Shared abstraction for all graph nodes and their processing/UI hooks. · `src/core/Node.h`

### Node types

Concrete image-processing stages assembled in the editor.

- [Input](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/InputNode.h): source node · Loads image files and provides the graph's ingestion boundary. · `src/nodes/InputNode.h`
- [Brightness](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/BrightnessContrastNode.h): effect node · Adjusts brightness and contrast on image data. · `src/nodes/BrightnessContrastNode.h`
- [Blur](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/BlurNode.h): effect node · Applies blur filtering to the image pipeline. · `src/nodes/BlurNode.h`
- [Output](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/nodes/OutputNode.h): sink node · Shows the final result and exports the processed image to disk. · `src/nodes/OutputNode.h`

### UI stack

Embedded Dear ImGui, ImNodes, and platform/render backends.

- [Dear ImGui](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imgui.h): ui library · Immediate-mode UI used for panels, controls, and editor chrome. · `imgui/imgui.h`
- [ImNodes](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imnodes.h): graph-ui · Node-graph interaction layer for ports, links, and node placement. · `imgui/imnodes.h`

### Preview bridge

Converts processed images into renderable textures.

- [Textures](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/src/utils/TextureUtils.h): preview bridge · Converts processed images into OpenGL textures for in-app previews. · `src/utils/TextureUtils.h`
- **OpenCV**: image backend · External image-processing library used for loading, transforming, and saving images.

### Embedded deps

Third-party source shipped in the repository.

- [GLFW backend](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/backends/imgui_impl_glfw.h): window backend · Desktop windowing and input bridge for ImGui. · `backends/imgui_impl_glfw.h`
- [OpenGL backend](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/backends/imgui_impl_opengl3.h): render backend · Rendering backend used to draw the editor and previews. · `backends/imgui_impl_opengl3.h`
- [ImGui core](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imgui.cpp): vendor source · Embedded Dear ImGui implementation source. · `imgui/imgui.cpp`
- [ImNodes core](https://github.com/nishchaybhutoria/node-based-image-processor/blob/main/imgui/imnodes.cpp): vendor source · Embedded ImNodes implementation source. · `imgui/imnodes.cpp`

### Assets

Runtime resources used by the editor and sample workflow.

- [Assets](https://github.com/nishchaybhutoria/node-based-image-processor/tree/main/assets): runtime files · Fonts and sample media used by the editor at runtime. · `assets`

## Connections

- Main loop → Graph: builds · Creates and manages the graph model used by the editor.
- Main loop → Dear ImGui: drives UI · Runs the immediate-mode editor interface each frame.
- Main loop → Textures: renders previews · Feeds processed images into texture creation for display.
- Graph → Node base: contains · Graph stores and connects node instances through the base abstraction.
- Input → Node base: inherits · Input node implements the shared node interface.
- Brightness → Node base: inherits · Brightness/contrast node implements the shared node interface.
- Blur → Node base: inherits · Blur node implements the shared node interface.
- Output → Node base: inherits · Output node implements the shared node interface.
- Input → OpenCV: loads image · Uses OpenCV for file ingestion and image decoding.
- Brightness → OpenCV: processes pixels · Uses OpenCV image operations as the effect backend.
- Blur → OpenCV: processes pixels · Uses OpenCV image operations as the effect backend.
- Output → OpenCV: writes image · Uses OpenCV export support for saving results.
- Output → Textures: previews result · Sends the final image to the preview texture bridge.
- Textures → OpenGL backend: uploads texture · Converts CPU-side image data into renderable OpenGL textures.
- Dear ImGui → GLFW backend: uses · Relies on GLFW for windowing and input integration.
- Dear ImGui → OpenGL backend: uses · Relies on OpenGL for drawing the UI and previews.
- Dear ImGui → ImNodes: hosts · The editor UI embeds the node-graph interaction layer.
- ImGui core → Dear ImGui: implements · Embedded source for Dear ImGui.
- ImNodes core → ImNodes: implements · Embedded source for ImNodes.
- Assets → Main loop: feeds runtime · Provides fonts and sample media loaded by the application.
- Input → Assets: uses sample image · Input flow depends on filesystem resources in the assets directory.
