nFlow — Visual Deep Learning Model Creator

A node-based, native desktop app for designing deep-learning models visually. Wire nodes on a canvas → see live tensor shapes → run CPU inference → export to PyTorch, Keras, or ONNX. Zero Python required.

Stack: Tauri v2 (Rust backend + WebView frontend) · React 19 · xyflow (React Flow) · Tailwind v4 · Zustand

Architecture spec & SRS: krystv/nflow-architecture-spec

---

What works right now

Feature	Status
Node-graph canvas (pan, zoom, drag, multi-select)	✅
90+ built-in operators (IO, Layer, Linalg, Activation, Norm, Pooling, Movement, Loss, Composite)	✅
Live symbolic tensor shape inference (every wire shows shape + dtype)	✅
Shape error diagnostics per node	✅
Custom node creator (composite editor tab)	✅
Custom node io.input / io.output — inline rename, dtype picker, rank badge	✅
Composite validity bar (port count, error count, Rust diagnostics)	✅
Snapshot-based undo / redo (all edit types)	✅
Code export — PyTorch, Keras, ONNX text	✅
ONNX binary protobuf export (passes onnx.checker, runs in onnxruntime)	✅
CPU numeric forward pass (real tensor evaluation — Simulate button)	✅
.nfl project file — save / open / recent files	✅
Global composite library (reusable nodes across projects, persisted in redb)	✅
Group-to-composite (select nodes → right-click → Create Block)	✅
Double-click block node → inline to primitives	✅
Double-click user composite → open editor tab	✅
Rhai custom op scripting (define shape inference in-place, no recompile)	✅
Multi-tab canvas (main project + one tab per open composite editor)	✅
Training config (AdamW / SGD / Adam + loss — emits PyTorch training loop)	✅

---

Rust crate status

Crate	What it does	Tests
nflow-ir	SSA graph IR, SlotMap nodes/values, Dim algebra, UserComposite	6 ✅
nflow-infer	DimSolver (union-find), broadcast, cost model (params + FLOPs)	7 ✅
nflow-ops	90+ operator registry — OpSpec + shape infer + Rhai custom ops	14 ✅
nflow-events	Session (event-sourced undo/redo + live inference + view) + .nfl format + redb	6 ✅
nflow-codegen	PyTorch / Keras / ONNX text + binary protobuf exporters	5 ✅
nflow-exec	Backend trait, CPU evaluator (90/90 ops covered), GPU stub (burn+wgpu, --features wgpu)	4 ✅

42 tests, 0 failures, 0 warnings (cargo test at workspace root, no GPU needed).

---

Quick start

# Prerequisites: Rust stable, Node 20+, Tauri v2 system deps
# See: https://tauri.app/start/prerequisites/

npm install

# Desktop app (Rust backend + hot-reload frontend):
npm run tauri dev

# Frontend-only preview — uses in-browser mock engine, no Rust needed:
npm run dev

# Production bundle:
npm run tauri build

# Rust unit tests only (no webkit/GPU needed):
cargo test

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│  React/xyflow frontend  (src/)                              │
│  ┌──────────┐  ┌────────────┐  ┌──────────────────────┐    │
│  │LeftPalette│  │   Editor   │  │  RightInspector      │    │
│  │Ops/Custom │  │ (canvas)   │  │  (attrs + ports)     │    │
│  └──────────┘  └────────────┘  └──────────────────────┘    │
│       │               │                    │                │
│       └───────────────┴────────────────────┘                │
│                       │ invoke(Intent)                      │
└───────────────────────┼─────────────────────────────────────┘
                        │  Tauri IPC
┌───────────────────────┼─────────────────────────────────────┐
│  Rust backend  (src-tauri/src/lib.rs)                       │
│                       │                                     │
│          Session::apply(intent)                             │
│               ↓              ↓                              │
│        Graph mutation   run_inference()                     │
│                              ↓                              │
│                    GraphView (nodes+edges+shapes)           │
└─────────────────────────────────────────────────────────────┘

The Rust core is the single source of truth. The frontend is a read-only projection — it sends Intent messages (add_node, connect, disconnect, move, delete, set_attr) and receives back a GraphView. The frontend never owns graph state; all mutation logic, shape inference, validation, and undo/redo live in Rust.

---

Frontend file map

src/
├── main.tsx                  ← bootstrap, global contextmenu suppression
├── App.tsx                   ← layout shell, multi-tab canvas mount
├── ErrorBoundary.tsx         ← catches render crashes, shows readable error
├── index.css                 ← Tailwind v4, react-flow overrides, scrollbar, font
├── lib/utils.ts              ← cn(), fmtShape, dtypeClass, IS_MAC, fmtShortcut
│
├── bridge/
│   ├── types.ts              ← all TS interfaces mirroring Rust types
│   ├── invoke.ts             ← api.* — the ONLY place that calls invoke()
│   └── mock.ts               ← in-browser mock engine for npm run dev
│
├── store/
│   ├── graph.ts              ← main session state (view, catalog, file, undo/redo)
│   ├── tabs.ts               ← tab system (main + composite editor tabs)
│   └── composites.ts         ← project + global composite library
│
├── components/
│   ├── layout/
│   │   ├── TopBar.tsx        ← file menu, undo/redo, export, simulate, settings
│   │   ├── TabBar.tsx        ← tab strip (main + editor tabs)
│   │   ├── LeftPalette.tsx   ← 28px strip + Ops panel + Custom panel + create modal
│   │   ├── RightInspector.tsx← node inspector (attrs, ports, weights, cost)
│   │   └── BottomMetrics.tsx ← collapsible metrics bar (params, FLOPs, event log)
│   └── editor/
│       ├── Editor.tsx        ← ReactFlow canvas, all callbacks useCallback-wrapped
│       ├── ContextMenu.tsx   ← right-click menus (node / edge / canvas)
│       └── nodes/
│           ├── PrimitiveNode.tsx   ← leaf op node (read-only display)
│           ├── BlockNode.tsx       ← composite/block node (double-click to expand)
│           └── IoNode.tsx          ← io.input / io.output (editable label + dtype)
│
└── panels/
    ├── CompositeEditorToolbar.tsx  ← toolbar for editor tabs (save/discard/undo/promote)
    ├── CompositeValidityBar.tsx    ← validity strip above each editor canvas
    ├── ExportModal.tsx             ← code export (PyTorch / Keras / ONNX)
    ├── RunPanel.tsx                ← forward pass result + coverage report
    ├── TrainPanel.tsx              ← training config (optimizer, loss, metrics)
    ├── SettingsPanel.tsx           ← app settings (shortcuts, canvas, general)
    ├── NodeLibraryPanel.tsx        ← full node library panel
    └── Toast.tsx                   ← error/info toasts

---

Custom node creation flow

LeftPalette → Custom tab → "New" button
    │
    ├─ QuickCreate (inline)
    │     Type name → Enter → createComposite() → loadProjectComposites() → openEditorTab()
    │
    └─ Advanced… link → AdvancedCreateModal
          Name, uid, category, colour, port counts, doc, paper URL
          → createComposite() → loadProjectComposites() → openEditorTab()

openEditorTab(uc):
    1. api.openCompositeEditor(uid)  →  Rust creates sub-Session with inner_graph
    2. tabs store: push new tab, set editorViews[uid] = GraphView
    3. App.tsx: mounts <Editor editorUid={uid} /> (display:flex, others display:none)
    4. CompositeValidityBar renders above canvas (port count, valid/invalid, errors)
    5. io.input / io.output nodes render as IoNode (click label to rename, dtype picker)

---

Critical bugs fixed (session history)

Bug	Symptom	Fix
onSelectionChange inline arrow	Maximum update depth (infinite loop)	Wrapped in useCallback with [] deps
nodeTypes inside component	All nodes remount every render	Moved to module-level const
onClick={void go}	Create button does nothing	Changed to onClick={() => void go()}
App.tsx single <Editor>	Editor tab canvas never appeared	All tab canvases mounted simultaneously, display:none for inactive
mockCreateUserComposite always returned Mamba	New composite had wrong uid	Mock now inserts real entry into store
open_composite_editor ignored uid	Editor always showed Mamba graph	mockEditorViewForUid(uid) generates correct io nodes
Graph unused import in lib.rs	Rust compiler warning	Removed; use Definition directly
import { useEffect } after usage	Module ordering issue	All imports hoisted to top of file
CreateCompositeModal imported but never rendered in App.tsx	Advanced modal inaccessible	Inlined as AdvancedCreateModal in LeftPalette.tsx

---

Design system

• Canvas bg: #0a0c10 · Panel bg: #14161b · Strip bg: #0e1016 · Border: #2d313a
• Fonts: Inter (body) · JetBrains Mono (code/values) — defined in @theme CSS vars
• 28px strip pattern: LeftPalette and RightInspector use 28px permanent strips with rotated text
• Port hover: box-shadow glow only — never transform: scale() (causes positional jump)
• Wire z-index: .react-flow__connection-line { z-index: 1001 } — above port handles

---

Repo layout

crates/             Rust workspace (pure, no GUI deps — cargo test works anywhere)
  nflow-ir/         SSA graph IR + UserComposite + Dim algebra
  nflow-infer/      DimSolver + shape broadcast + cost model
  nflow-ops/        Operator registry (90+ ops) + Rhai custom op scripting
  nflow-events/     Session (undo/redo + inference) + .nfl format + redb DB
  nflow-codegen/    PyTorch + Keras + ONNX exporters
  nflow-exec/       CPU evaluator + GPU Backend trait (wgpu feature)
src-tauri/          Tauri v2 IPC command layer (~30 commands)
src/                React 19 + xyflow + Tailwind v4 + Zustand frontend
docs/               Architecture docs, SRS, operator reference

---

License

Apache-2.0

Generated by ML Intern

This repository was built and maintained by ML Intern.

• Try ML Intern: https://smolagents-ml-intern.hf.space
• Source code: https://github.com/huggingface/ml-intern