Backend Overview

This is the "you are here" map of the backend: not what every file holds (that's codebase-map) and not the platform's structure (that's architecture), but the backend as a set of running objects — who owns whom, what's a singleton vs per-run, and how a graph actually gets executed. The hard fact that ties it together: almost everything is per-process and reached through one ProcessServices singleton; the only cross-object rendezvous is a single global table, NODE_HANDLERS. Read this first, then follow the links into the deep dives.

Read top to bottom — one spine. Both entry paths, Canvas Play and Batch Eval, converge on the same LoopRunner → GraphExecutor engine; only the wrapping above it differs. The engine fires nodes by querying NODE_HANDLERS — the one table the WorkspaceComponentRegistry fills and ProcessServices holds — and there is one such stack per process (the backend, and every eval subprocess).

1. What the backend is

The backend (agentcanvas/backend/app/) is a pure execution engine with zero domain knowledge (ADR-platform-001): it discovers domain code from workspace/ at runtime and runs graphs against it. As a running system it is a handful of per-process singletons hung off one ProcessServices, plus short-lived per-run objects that the API spins up on demand. Three things explain almost everything:

• One ProcessServices per process. Reached via get_services() — a module singleton. It holds the WorkspaceComponentRegistry and (after startup) the JobScheduler. There is no single global state across the system: the backend process has one, and every eval subprocess has its own.
• One global handler table, NODE_HANDLERS. The registry writes it; every GraphExecutor reads it. That table is the only rendezvous between "what's installed" and "what runs" — see §4.
• One engine, spun up per run. A LoopRunner (canvas singleton, or fresh per eval episode) builds a GraphExecutor that fires the graph's nodes. Details: execution-paths.

Follow one Play click

The smallest end-to-end trace — what one POST /api/navigate/run touches, in order:

1. run.py · run_loop grabs ExecutionGuard (canvas), validates the graph, and asks get_services().workspace_component_registry.ensure_nodesets_for_graph() to make sure every node type is in NODE_HANDLERS.
2. get_loop_runner() returns the singleton LoopRunner; a fire-and-forget asyncio task calls runner.run(graph).
3. LoopRunner.run() builds a fresh GraphExecutor and awaits it.
4. GraphExecutor.run() drives the ready-queue: for each node, NODE_HANDLERS[type].forward(). Server-mode nodes call out over HTTP to a registry-owned auto_host subprocess.
5. Outputs stream over WebSocket (broadcast()); the guard releases when run() returns.

That's the canvas path in brief — the full request path, interactive controls, and live streaming are in canvas-play; the headless eval path is batch-eval.

2. The per-process model

This is the single most load-bearing fact, and the one that surprises people: get_services() is a module global, so "singleton" means per Python process, not per system.

• The backend (uvicorn) process has one ProcessServices → one WorkspaceComponentRegistry → one NODE_HANDLERS → the canvas LoopRunner singleton.
• Each eval subprocess (eval_subprocess_main) is a separate process with a fresh ProcessServices/registry of its own (eval_subprocess_main.py notes "Subprocess starts with a fresh ProcessServices"). Rather than reload models, it attaches to the parent's already-running auto_host servers via register_remote_nodeset (a _RemoteAutoServerShim whose stop() is a no-op — it doesn't own them).

So "who owns the registry / who owns ProcessServices" has the same answer in every process — that process's get_services() — and the chain tops out at the OS process (uvicorn for the backend, eval_subprocess_main for an eval run). There is no class above ProcessServices.

3. Process-global singletons

Everything in this table is created once per process and lives for the whole process. "Reached via" is how any code gets a handle.

4. Per-run objects & the one seam

Per-run objects are created by the API/orchestrator and discarded at end-of-run. They are not owned by the registry — they only ever read its output table.

The seam. The registry and the executor never call each other — they meet at NODE_HANDLERS. The LoopRunner doesn't touch the table at all.

Concretely: register_node() + the register path in registry.py populate NODE_HANDLERS (last-write-wins; unload evicts); GraphExecutor does NODE_HANDLERS.get(node.type) then .forward() (graph_executor.py). The executor reaches the registry directly in exactly one narrow place — to wire up a RemoteContainerProxy when a node is granted a state container that lives in another process (the cross-nodeset container-access path, via get_services().workspace_component_registry); otherwise the table is the whole contract. This is why the registry is 1 and GraphExecutors are N: N executors all read the one table the one registry filled. For the firing engine itself, see graph-executor.

The two run paths

A graph reaches GraphExecutor by one of two routes — each now its own code-grounded deep doc, so this hub only names them:

• Canvas Play — interactive, in-process, single-tenant (ExecutionGuard), driven by the singleton LoopRunner, streamed live: canvas-play.
• Batch eval — headless, spawned in its own subprocess by JobScheduler (the backend loads only the shared singletons, then hands the run their borrowed URLs), a fresh LoopRunner per episode across N workers: batch-eval.

Both converge on the same LoopRunner → GraphExecutor engine and fire against the same NODE_HANDLERS table (§4 above) — the divergence is entirely in the wrapping. The class-by-class comparison of the two paths is execution-paths.

5. Startup & shutdown (lifespan)

The whole runtime is wired in main.py · lifespan (the FastAPI startup/shutdown hook). Order matters:

1. ErrorBus first — attach the event loop, subscribe the WS fan-out, install the log bridge (so every later subsystem's logs surface).
2. state = get_services() → constructs ProcessServices → constructs WorkspaceComponentRegistry (empty so far).
3. workspace_component_registry.scan_all() — discover workspace/ components → fills NODE_HANDLERS.
4. await workspace_component_registry.initialize_all() — initialize nodesets (the slow part).
5. Build JobScheduler (query VRAM, resolve outputs/eval_runs/), wire the canvas-lock callback + registry, reconcile aborted runs.
6. Launch background tasks: the scheduler loop (1 s tick — eval admit/reap + orphaned-canvas-guard reaper), the graph watcher, the nodeset-source watcher.
7. yield — serve requests.
8. On shutdown: cancel the tasks, job_scheduler.shutdown(), then workspace_component_registry.shutdown_all() (stops all server subprocesses).

6. Where to go deeper

7. Gotchas (where the clean model bites)