feat: add visual builder + workspace mode to Burr UI by andreahlert · Pull Request #687 · apache/burr

andreahlert · 2026-03-23T05:13:05Z

Building on #667 (Graph Builder by @skrawcz), this adds a workspace mode and significantly enhanced builder that turns Burr's UI into a development environment.

What's new

Visual Builder (enhanced)

9 node types: Action, Input, Result, LLM Call, API Call, Code, Streaming, Loop, Router
Each type has specialized property editors (LLM: provider/model, API: url/method, Code: inline editor, Router: branch conditions)
Inline + button on edges (Activepieces-style) with searchable type picker
Recursive layout algorithm (replaces dagre) supporting loop arcs and router fan-out/fan-in
Node type picker with search bar and categories (I/O, Logic, Integrations)

Monaco Editor (split view)

Builder canvas on the left, VS Code-style editor on the right
Multi-file code generation: actions.py, app.py, run.py, requirements.txt
File explorer sidebar with tabs (open/close files)
Bidirectional sync: edit code and the graph updates, edit graph and the code updates
Full Ctrl+C/V/Z support in both canvas and editor

Project save/load

File menu (New, Save, Open, Download .py)
Projects persisted server-side in ~/.burr/builder_projects/
Ctrl+S to save

Workspace integration

Backend workspace router with file browsing, code viewing, and script execution (SSE streaming)
Link workspace directories to projects
Path traversal protection with workspace validation

Other improvements

Undo/redo with 50-state history
Keyboard shortcuts (Delete to remove nodes, Ctrl+C/V to copy/paste nodes)
Code generation includes proper imports, sanitized identifiers, and with_tracker()

Screenshots

Builder with nodes and generated code

Node editor with LLM Call configuration

Searchable node type picker

Technical details

Backend (Python)

burr/tracking/server/workspace.py: new APIRouter with endpoints for file tree, file content, script execution (SSE), process management, workspace links, and builder project persistence
Modified run.py to mount workspace router, schema.py to add supports_workspace

Frontend (~6,700 new lines)

utils/: builderTypes, codeGenerator (9 node types + multi-file), codeParser (bidirectional sync), flowLayout (recursive layout), treeUtils (immutable tree ops), stateFlow
hooks/useBuilderState.ts: tree-based state with undo/redo, keyboard shortcuts, save/load
builder/: BuilderView (split layout), BuilderGraph (ReactFlow with custom node/edge types), NodeEditor, NodeTypePicker (portal-based), 4 node components, 5 edge components with inline + buttons
workspace/: FileExplorer, CodeViewer, RunTerminal, WorkspaceSelector
project/: ProjectWorkspaceView, ActivityBar, SidePanel, TabBar, TrackingSidePanel

Dependencies added

@monaco-editor/react (MIT)
@tanstack/react-query (MIT)
@xyflow/react (MIT)
react-joyride (MIT)

All MIT license, ASF Category A compatible.

How I tested

npx tsc --noEmit zero errors
Backend endpoints tested with curl
Manual E2E: create flow, add nodes via toolbar and inline +, edit properties, see code update, save/load projects

Checklist

PR has an informative and human-readable title
Changes are limited to a single goal
Code passed the pre-commit check
New functions are documented
Placeholder code is flagged / future TODOs are captured in comments

skrawcz · 2026-03-28T06:17:16Z

@andreahlert I can't get this to run locally -- did you commit everything? otherwise see the CI failures.

skrawcz · 2026-03-28T06:21:37Z

Also need some example to load to help someone get started.

andreahlert · 2026-03-28T12:33:22Z

Thanks for reviewing. Didn't have the time to check it properly, I'll do it as soon as possible. Target: 03-30-2026

andreahlert · 2026-03-28T20:12:09Z

Thanks for trying it out. Two things:

Missing pieces: This PR is meant to be applied on top of feat: add visual Graph Builder tool to Burr UI #667 (your graph builder). On main alone, the builder route works but some of the other UI improvements (HomeView, SearchView, etc.) won't be there. The builder itself at /builder should load fine since all its deps are self-contained. I'll add a note about this in the PR description.
Example graphs: Good call. I'll add a few pre-loaded examples (chatbot flow, data pipeline, agent with tools) that load from the File > Open menu so someone can see the builder in action without building from scratch.

Working on both now.

JiwaniZakir

In run.py, the shutdown sequence in lifespan calls await workspace.cleanup_processes() directly before await backend.lifespan(app).__anext__(), but there's no try/finally wrapping these calls. If cleanup_processes() raises an exception, the backend's own cleanup will be silently skipped, potentially leaking database connections or other resources. The backend shutdown should be guarded with a try/finally block regardless of what happens in workspace cleanup.

Additionally, supports_workspace=True is hardcoded unconditionally in _get_app_spec() — this means the UI will always advertise workspace support even if the feature is disabled or broken at runtime. This should be derived from a config flag or at least check that the workspace module initialized successfully, similar to how is_snapshotting_backend and is_annotations_backend are computed from the actual backend capabilities.

The _validate_workspace allowlist approach in workspace.py is a reasonable security boundary, but _read_links() is called on every file-browsing request with no caching. If the links file is read from disk on each API call under load, this could become a bottleneck — a short-lived in-process cache or memoization with invalidation on write would be worth considering.

skrawcz · 2026-03-29T16:28:18Z

validated things load locally at least.

elijahbenizzy

Played around some -- looking great! Node types should probably have specific implementations but I think this is a good start to put out there.

Adds a low-code visual builder with split-view Monaco editor, workspace file browsing, and project persistence. Builder features: - 9 node types (Action, Input, Result, LLM Call, API Call, Code, Streaming, Loop, Router) with specialized property editors - Inline + buttons on edges for inserting nodes (Activepieces-style) - Recursive layout algorithm supporting loop arcs and router fan-out - Monaco Editor with multi-file code generation (actions.py, app.py, run.py, requirements.txt) - Bidirectional sync between graph and code - Searchable node type picker with categories - File menu with save/load projects, Ctrl+S support - Undo/redo (50-state history), copy/paste, delete shortcuts - Code generation with sanitized identifiers and proper imports Workspace features: - Backend router for file browsing, code viewing, script execution (SSE streaming), process management, and workspace-project linking - Builder project persistence in ~/.burr/builder_projects/ - Path traversal protection with workspace validation New dependencies (all MIT, ASF Category A): - @monaco-editor/react - @tanstack/react-query - @xyflow/react - react-joyride

- Remove unused imports/variables flagged by ESLint - Replace regex literal with RegExp constructor to avoid no-control-regex - Format workspace.py with black and isort

- Replace `as any` with proper types where possible - Add eslint-disable comments for icon type maps (heroicons ForwardRef) - Remove unused `id` from edge component destructures - Remove unused `langMap` variable from BuilderView

@jaeyow

This takes work from @jaeyow and apache#572. Adds a drag-and-drop graph editor for designing Burr application graphs visually and exporting as Python code or JSON. Key changes: - New /graph-builder route with full visual editor (ReactFlow v12) - Migrate existing GraphView from reactflow v11 to @xyflow/react v12 - Remove reactflow and @tisoap/react-flow-smart-edge dependencies - Per-node async/streaming toggles matching Burr's 4 action variants - Python code generation with correct decorators and signatures - 3 pre-built example graphs (MultiModal Chatbot, CRAG, Streaming) - localStorage auto-save/restore of graph state - Empty-state onboarding overlay and structured help sidebar - Fix appcontainer layout for full-height content

Python (workspace.py): - Module-level docstring describing all capabilities - Docstrings on all Pydantic models, endpoints, and helper functions - Documented security functions with Args/Returns/Raises TypeScript: - JSDoc on all exported types in builderTypes, codeGenerator, codeParser - JSDoc on all tree operation functions in treeUtils - JSDoc on layout algorithm functions in flowLayout - JSDoc on useBuilderState hook

Remove the legacy react-query v3 package and standardize on @tanstack/react-query v5 across all components. This fixes the "No QueryClient set" error in BuilderView which was caused by two separate QueryClient providers from different packages.

Wrap workspace.cleanup_processes() in try/finally so backend shutdown always runs even if process cleanup fails. Derive supports_workspace from workspace.is_available() instead of hardcoding True. Add in-process cache to _read_links() to avoid disk reads on every file-browsing request.

andreahlert · 2026-04-09T14:12:30Z

All review feedback addressed. Rebased clean on main, no conflicts.

@JiwaniZakir your three points: cleanup_processes() is wrapped in try/finally now so backend shutdown always runs, supports_workspace is derived from workspace.is_available() instead of hardcoded, and _read_links() has an in-process cache with invalidation on write.

@skrawcz docstrings on every function/class in workspace.py, including the inner ones. Examples were already in from the graph-builder merge.

@elijahbenizzy opened #735 to track the node type implementations as a follow-up. Agreed it's fine for the initial merge.

Ready for re-review whenever you get a chance.

github-actions · 2026-04-27T09:53:01Z

This PR has been inactive for 17 days after receiving review feedback.
Converting to draft.

Please mark it as ready for review when you have addressed the comments.
If no activity occurs within 90 days, it will be closed automatically.

Combine event consumer cancellation from main with workspace cleanup from this branch in the lifespan shutdown path.

skrawcz · 2026-06-22T20:12:30Z

+
+# In-process cache for workspace links to avoid disk reads on every request.
+_links_cache: Optional[dict] = None
+_links_cache_lock = threading.Lock()


we don't need this. we run fastapi in an asyncio context.

skrawcz · 2026-06-22T20:12:53Z

+    global _links_cache
+    with _links_cache_lock:
+        if _links_cache is not None:
+            return _links_cache
+    if os.path.exists(_LINKS_PATH):
+        with open(_LINKS_PATH, "r") as f:
+            data = json_module.load(f)
+    else:
+        data = {}
+    with _links_cache_lock:
+        _links_cache = data
+    return data


due to the way python runs, this should be atomic in an asyncio context.

skrawcz · 2026-06-22T20:13:30Z

+    with _links_cache_lock:
+        _links_cache = data


again we don't need the lock.

yeah fair, my bad. threw the lock in out of habit (check-then-act on a global), but ofc it's all async + no awaits so it's already serialized. ripping out the lock + threading import.

skrawcz

just one nit around threading.lock

All workspace endpoints are async and the cache helpers never await, so they are already serialized on the event loop. Addresses review feedback on apache#687. Signed-off-by: André Ahlert <andre@aex.partners>

…r-lowcode Signed-off-by: André Ahlert <andre@aex.partners> # Conflicts: # telemetry/ui/package-lock.json

TypeScript 4.9 misresolves @tanstack/react-query v5's legacy .d.ts under CRA's enforced moduleResolution: node, widening every useQuery `data` to any/unknown. After the react-query -> @tanstack/react-query migration this surfaced as TS7006/TS18046 noImplicitAny build failures (20 sites across AdminView, AnnotationsView, AppView, TrackingSidePanel and the examples views), breaking the Node.js CI and Release Validation build jobs. TypeScript 5 infers the query generics correctly, clearing all 20 errors with no component changes (verified with a full `npm run build`). CRA still forces moduleResolution: node, so no tsconfig change is needed. react-scripts@5.0.1 caps its optional typescript peer at ^4, so add telemetry/ui/.npmrc with legacy-peer-deps=true to let `npm install` resolve TS 5 (the build itself is unaffected by the peer range). Exclude the new .npmrc from Apache RAT, matching the other header-less tool config files. Signed-off-by: André Ahlert <andre@aex.partners>

skrawcz reviewed Mar 28, 2026

View reviewed changes

Comment thread burr/tracking/server/workspace.py

skrawcz reviewed Mar 28, 2026

View reviewed changes

Comment thread burr/tracking/server/workspace.py

andreahlert self-assigned this Mar 28, 2026

JiwaniZakir reviewed Mar 29, 2026

View reviewed changes

andreahlert added kind/feature Net-new functionality area/ui Burr UI (telemetry frontend) labels Mar 30, 2026

elijahbenizzy reviewed Apr 4, 2026

View reviewed changes

andreahlert and others added 11 commits April 9, 2026 10:23

fix: resolve CI lint errors

11dcd5f

- Remove unused imports/variables flagged by ESLint - Replace regex literal with RegExp constructor to avoid no-control-regex - Format workspace.py with black and isort

fix: format workspace.py with black --line-length=100

0d3718a

fix: sort imports in run.py for isort

304b76b

fix: add eslint-disable for ANSI regex control character

4335a70

fix: remove unused useCallback import and console.error

54b8530

andreahlert force-pushed the feat/workspace-builder-lowcode branch from 898f6be to 0fff68f Compare April 9, 2026 13:34

docs: add docstrings to inner functions in stream_output

46d22ff

andreahlert requested review from JiwaniZakir, elijahbenizzy and skrawcz April 9, 2026 14:11

andreahlert mentioned this pull request Apr 9, 2026

Builder: node types with specific implementations #735

Open

github-actions Bot added the pr/stale No activity for 14+ days after review label Apr 27, 2026

merge: resolve conflict with apache/main in tracking/server/run.py

a72ff9d

Combine event consumer cancellation from main with workspace cleanup from this branch in the lifespan shutdown path.

github-actions Bot added the area/tracking Telemetry, tracing, OpenTelemetry label Apr 28, 2026

Haricharanpanjwani mentioned this pull request Jun 5, 2026

fix: generate concrete low-code builder node implementations andreahlert/burr#1

Open

skrawcz reviewed Jun 22, 2026

View reviewed changes

fix(workspace): drop unnecessary threading lock on links cache

5e18bb6

All workspace endpoints are async and the cache helpers never await, so they are already serialized on the event loop. Addresses review feedback on apache#687. Signed-off-by: André Ahlert <andre@aex.partners>

github-actions Bot added the pr/needs-rebase Conflicts with main label Jun 27, 2026

Merge remote-tracking branch 'apache/main' into feat/workspace-builde…

95b0a3b

…r-lowcode Signed-off-by: André Ahlert <andre@aex.partners> # Conflicts: # telemetry/ui/package-lock.json

github-actions Bot removed the pr/needs-rebase Conflicts with main label Jun 27, 2026

andreahlert force-pushed the feat/workspace-builder-lowcode branch from 3612768 to 93880a1 Compare June 27, 2026 09:34

github-actions Bot added the area/ci Workflows, build, release scripts label Jun 27, 2026

Uh oh!

Conversation

andreahlert commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's new

Screenshots

Technical details

Dependencies added

How I tested

Checklist

Uh oh!

Uh oh!

Uh oh!

skrawcz commented Mar 28, 2026

Uh oh!

skrawcz commented Mar 28, 2026

Uh oh!

andreahlert commented Mar 28, 2026

Uh oh!

andreahlert commented Mar 28, 2026

Uh oh!

JiwaniZakir left a comment

Choose a reason for hiding this comment

Uh oh!

skrawcz commented Mar 29, 2026

Uh oh!

elijahbenizzy left a comment

Choose a reason for hiding this comment

Uh oh!

andreahlert commented Apr 9, 2026

Uh oh!

github-actions Bot commented Apr 27, 2026

Uh oh!

skrawcz Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

skrawcz Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

skrawcz Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

andreahlert Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

skrawcz left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

andreahlert commented Mar 23, 2026 •

edited

Loading