How samuelmtimbo/unit works
Project Type and Purpose
• Unit is a full-stack, web-based visual programming environment and library.
• It consists of a browser-based editor (“Environment”), a graph-evaluation engine (the “System/Spec” modules), a Node.js server for hosting and peer communication, and a build toolchain that produces bundles for browser, worker, and server.
Top-Level Architecture & File Structure
• public/ + index.html – static assets & entry HTML for the browser UI
• src/client/ + src/platform/web/ – browser UI code, DOM & SVG-based rendering, event handling, and “makeRemoteUnitAPI” to talk to the graph engine
• src/worker/ + src/platform/worker/ – Web Worker bootstrap for heavy graph evaluation
• src/server/ + src/api/server/ – Node.js HTTP/WS server, static‐file serving, peer API, and middleware
• src/system/ + src/spec/ + src/Class/ – core graph engine modules and language spec (system of “units” and spec-based evaluators)
• src/script/ + src/build/ – build/bundling scripts that generate the client, worker, and system bundles
• src/api/peer + src/api/storage + src/api/speech – portable APIs for peer-to-peer graph sharing, storage (local/session), and TTS/STT
Main Components
A. Build & Packaging Layer (Developer/CI)
• npm / package.json, build scripts in src/script/ and src/build/
• Outputs: client bundle.js, worker bundle.js, system bundle.js
B. Browser Frontend
• UI Layer: public/index.html → loads client bundle
• Render Engine: src/client/render & component library (DOM/SVG)
• Event Layer: src/client/event & context menu, gestures, voice commands
• Remote API: “RemoteUnitAPI” communicates with Worker or Server for graph ops
C. Web Worker (Graph Engine Host)
• Worker entry (src/worker/system.ts) loads system bundle
• Runs core graph evaluation (src/system/core + src/system/f + src/spec)
• Exchanges data/events with frontend via postMessage
D. Node.js Backend
• HTTP Server (src/server/serve.ts) serves static assets & REST endpoints
• WebSocket / PeerServer (src/api/server/peer) for real-time graph sharing
• Boot process (src/boot/index.ts) initializes server environment
• Optional CLI entry (‘unit’ command) via bin in package.json
E. Core Graph Engine & Language Spec
• Multi‐Input/Multi‐Output FSM model, represented by src/Class and src/spec
• Functional transformations in src/system/f and JSON-based specs in src/system/core
F. External Services & APIs
• Browser APIs: LocalStorage, SessionStorage, Speech, Clipboard (src/api/storage, src/api/speech)
• Peer‐to‐Peer: WebRTC/Duplex channels (src/api/peer)
• Node APIs: file system, HTTP, WebSocket
Relationships & Data Flows
• Build → [bundles] → deployed to Server and Browser
• Browser UI ←HTTP GET→ Node Server (static files)
• Browser UI ↔ WebSocket/REST ↔ Node Server (graph storage, multi-user sync)
• Browser UI ↔ postMessage ↔ Web Worker (graph evaluation, unit runtime)
• Web Worker ↔ spec/system modules (pure computation)
• Browser UI ↔ Browser APIs (storage, speech, clipboard)
Architectural Patterns & Design Principles
• Separation of Concerns: UI vs. computation vs. server
• Reactive, Data-Flow Graph: event-driven, MIMO FSM units
• Layered API Abstraction: src/api/* defines platform-agnostic interfaces for storage, speech, peer
• Build‐time bundling isolates code per runtime (client, worker, system)
Elements
• Labels: “Client Bundle”, “Worker Bundle”, “System Bundle”
• Annotations: note key directories (src/client, src/worker, src/server, src/system, src/spec) and core modules