apps/web-visualizer/docs/architecture.md

build123d Live Visualizer — Architecture Notes

Live Update Loop

• Front-end trigger – Run & Stream button encodes the textarea contents into an SSE request (/api/run?code=...).
• Server orchestration – Express writes the snippet to artifacts/<job>.py, spawns the dedicated build123d Python interpreter, and relays stdout/stderr as Server-Sent Events (log events).
• Completion signal – When the Python runner finishes, Express emits a complete event containing the STL path (or an error message). The client loads the STL via three.js and refreshes the viewer.
• Resilience – Each run is isolated via UUIDs, making the log stream and artifacts easy to correlate while enabling multiple sequential runs without restarts.

Artifact Flow

1. Client sends code → Express persists under artifacts/<job>.py.
2. Python runner executes snippet, requiring a result variable and exporting to artifacts/<job>.stl.
3. Express serves /artifacts statically so the browser can fetch STL files immediately.
4. Front-end STL loader retrieves the file, renders it, and exposes a download link; artifacts remain on disk for inspection or later cleanup.

LLM Integration Options

• OpenClaw Orchestrator – Keep the current human-in-the-loop workflow where OpenClaw agents call the /api/run endpoint, enabling prompt-to-geometry iteration without exposing provider keys to the prototype.
• Direct Provider Calls – Embed provider SDK (OpenAI, Anthropic, etc.) within the server. The Express layer would accept natural-language prompts, forward them to an LLM, and pipe the generated build123d script straight into the runner before streaming results back.
• Local Coding Agent – Bundle a lightweight model (e.g., llama.cpp) or a deterministic templating agent that runs locally, translating UI prompts to build123d code without external network usage—aligned with offline or air-gapped deployments.

Next-Step Roadmap

• Add job queueing plus cancellation support per run id (currently a single in-memory stream).
• Persist structured job metadata (prompt, status, artifact path) for replay and auditing.
• Harden sandboxing by running the Python process inside a constrained container or Firejail profile.
• Expand the viewer with assembly overlays (multiple STL layers, color coding, exploded views).
• Wire optional LLM prompt templates + history so designers can iterate conversationally.
• Author smoke tests covering the SSE endpoint and sample runner invocation.