Codebase Map — agentcanvas

§1Backend: Root Files

Entry points, core singletons, and domain modules that live at the package root. Imported by nearly every sub-package — they stay at the top level to avoid circular imports.

1.1 Entry Points

1.2 Core Singletons

Small files imported everywhere — config, state, models, and the core data model.

1.3 Domain Modules

Single-file modules with one consumer each — candidates for future sub-packages as their domains grow.

§2Backend: API Layer

Grouped into 5 domain sub-packages. Each module exports a router = APIRouter() that main.py mounts.

2.1 Canvas — graph editing + environment control

2.2 Execution — run, eval, logs, websocket

2.3 Platform — config, components, LLM profiles

2.4 Registry — component snapshot

2.5 Replay — episode replay API

§3Backend: Execution Engine

The core runtime that turns a GraphDefinition JSON into a live agent run. All execution goes through this package. No HTTP/FastAPI imports — pure Python.

3.1 Execution Pipeline

When the user presses Play on the canvas, this is the call chain:

3.2 File by File

loop_runner.py216 lines

The outermost lifecycle shell — first thing called from the API. Owns the lifecycle: pause, stop, resume.

• Receives a GraphDefinition JSON from the frontend
• Calls flatten_graph() to expand composites into a flat graph
• Builds StateContainer instances from the graph's container definitions
• Creates a GraphExecutor and calls .forward()
• Manages pause/stop/resume via asyncio events
• ExecutionPrinciples dataclass configures batch eval mode

Does not know how nodes fire — sets up the world and hands control to the executor.

flatten.py300 lines

Pre-processing step. Runs before execution starts. The canvas supports nested graphs (composite nodes containing sub-graphs), but the executor needs a flat list of nodes and edges.

• Recursively walks composite nodes that have a subgraph
• Expands them into the parent graph, rewiring graphIn/graphOut boundary nodes to parent edges
• Prefixes node IDs to avoid collisions (composite1.inner_node)
• Returns a FlattenMap so error messages can trace back to the original composite context

graph_executor.py1,987 lines · largest file

Where nodes actually execute. Implements a dataflow FIFO queue model:

1. Build: wraps each NodeDef into a NodeInstance (tracks pending inputs per port)
2. Seed: finds nodes with no required inputs (environment nodes, constants) and enqueues them
3. Loop: pull a node from queue → execute → deliver outputs to downstream ports → if downstream has all required inputs, enqueue it
4. Fan-out: when a node produces output, all target ports are filled before any downstream node fires
5. Fan-in: a node only fires when all required input ports have data
6. Cycles: IterOutNode copies its inputs to the paired IterInNode and re-enqueues it
7. Termination: IterOut's stop input port goes true (Decide phase), step budget reached, stop event set, empty queue, or a node-raised StopExecution

Each node fires by calling NODE_HANDLERS[node_type].forward(inputs, ctx).

scope_analysis.py416 lines

Computes the scope forest before execution starts.

• analyze_scopes() — walks the flat graph and returns every (iterIn, iterOut) scope plus its parent/child topology (ADR-dataflow-007)
• Classifies composite boundaries: graphIn = parameter slot, graphOut = return slot of a scope
• Validates scope shape (inner scopes bounded by mandatory graphIn/graphOut) — feeds the executor's per-scope _ScopeState

builtin_nodes.py1,369 lines

The node handler registry and the home for all built-in framework nodes (see TODO #37).

Registry:

• NODE_HANDLERS: dict[str, type[BaseCanvasNode]] — global registry mapping node_type string to Python class
• register_node(cls) — called by WorkspaceComponentRegistry when loading nodesets
• ExecutionContext dataclass — mutable state passed to every node

Built-in node classes (14):

state_containers.py469 lines

Implements the dual-wire system: nodes communicate via data edges (typed values) and state edges (access grants to shared containers).

• BaseState ABC with 3 reducer implementations (ephemeral removed 2026-04-18 — use lifetime="step"): AccumulatorState (append), LastWriteState (overwrite), CounterState (increment)
• BaseState.on_signal(name, payload) — clears to initial_value when a name in reset_on fires
• StateContainer — a dict of named BaseState entries
• Factory function builds containers from ContainerDef in graph JSON
• Executor injects connected containers into ctx._containers before each node fires
• Nodeset-owned / keyed containers — BaseNodeSet.get_containers() lets a nodeset own containers (with allow_opaque values and per-key evict for worker parallelism), alongside graph-level containers

eval_batch.py827 lines

Wraps LoopRunner for batch evaluation:

• BatchEvalRunner takes a graph + episode iterator
• For each episode: leases a WorkerHandle from EnvWorkerPool, creates a fresh LoopRunner, sets the episode, runs under asyncio.wait_for(timeout=max_steps × per_step_budget_sec), collects metrics
• At worker_count>1: shared asyncio.Queue of episode indices drained by N coroutines under asyncio.gather, results aggregated under asyncio.Lock, sorted by episode_index before persistence
• Emits WS progress events (eval_progress, eval_episode_done) tagged with worker_id
• Respects ExecutionGuard — only one eval or canvas run at a time

env_worker_pool.py244 lines

Sits between BatchEvalRunner and LoopRunner (ADR-eval-002 PA-3 + PB).

• EnvWorkerPool(worker_count=N, env_nodeset=name) — async context manager. __aenter__ populates N WorkerHandles; at worker_count>1 each binds to a tagged RemoteEnvPanelProxy + tagged URL
• acquire() — async context manager that leases one WorkerHandle per episode
• WorkerHandle carries env_panel_overrides and server_url_overrides consumed by the leased LoopRunner's executor for per-worker routing
• resolve_per_step_budget(env_nodeset, override) — resolves the per-step wall-clock budget

hooks.py307 lines

Fires shell commands at graph/node boundaries — like git hooks for graph execution.

• 5 events: GraphStart, GraphComplete, GraphError, PreNodeExecute, PostNodeExecute
• Protocol: event payload sent as JSON on stdin → hook process → JSON response on stdout with {"action": "continue"|"block"|"modify"}
• Fail-open: any error (timeout, crash, malformed JSON) defaults to action="continue"
• HookRunner class manages execution; load_hooks_file() loads hook definitions from YAML

__init__.py17 lines

PolicyEntry dataclass: metadata for a loadable neural policy checkpoint (id, name, checkpoint path, config path). Used by WorkspaceComponentRegistry when scanning workspace/policies/.

3.3 Layering

§4Backend: Component System

The public API for node authors. Files in workspace/ import from this package.

§5Backend: Server SDK

Implements the write-once deploy-anywhere server mode (ADR-server-001). A BaseNodeSet subclass runs identically in-process or as an auto-hosted HTTP server. Three roles: server-side, framework-side, bridge.

§6Backend: LLM System

Self-contained package for the LLM/VLM subsystem. __init__.py re-exports the public API so external imports work unchanged.

6.1 Fallback Chain (ADR-platform-003)

§7Backend: Logging

Two-layer logging system (ADR-observability-003): the executor captures port I/O automatically (exterior); nodes add domain detail via _self_log() (interior).

§8Backend: Standard Library

Shared type definitions and constants used by node implementations and the executor. This is a leaf package with no intra-app dependencies.

§9Backend: Services, Replay & Tools

Long-running backend-process services owned by the FastAPI lifespan: job scheduling, file watching, resource sampling.

Episode replay backend — turns persisted episode logs into an env-agnostic replay timeline (served by api/replay/, §2.5; consumed by the frontend Replay page, §17).

§10Backend: Dependency Flow

How the backend packages depend on each other. Arrows point from importer to imported.

• Leaf packages (no intra-app deps): standard/, logging/, llm/
• Core data model: graph_def.py — imported by everything
• Cross-cutting: state.broadcast() — used by both agent_loop/ and api/execution/websocket.py. The engine no longer imports from the API layer
• Diagram shows the three largest of the five api/ sub-packages; api/registry/ and api/replay/ (§2.4–2.5) are omitted for legibility, as are services/, replay/, and tools/ (§9)

§11Frontend: App Shell

Shared components (src/components/)

§12Frontend: Canvas Editor

Core graph editing workspace. React Flow drives the visual layer; a Zustand store owns all graph state.

§13Frontend: Canvas Nodes

The renderer tree that turns Python-defined NodeUIConfig into visible canvas nodes.

Shared primitives

Special node types

Generic renderer stack (agentloop/inner/)

All non-special nodes flow through this stack, driven entirely by NodeUIConfig from Python.

Display field renderers (layouts/fields/)

§14Frontend: Canvas Panels

Sidebar and toolbar UI components that surround the React Flow canvas.

§15Frontend: Evaluation Page

Batch evaluation launcher and live monitor (ADR-eval-001).

§16Frontend: Log Viewer

Dedicated page for post-hoc inspection of execution logs (ADR-observability-003).

Renderers (logs/renderers/)

Each renderer handles one value type in a log entry's port snapshot.

§17Frontend: Replay & Monitor

Two post-hoc inspection pages beyond the log viewer: episode replay and system/run performance monitoring.

§18Frontend: NodeSet Manager

§19Config and Build