# samuelmtimbo/unit architecture

> Architecture diagram of the GitHub repository samuelmtimbo/unit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samuelmtimbo/unit
- Repository: https://github.com/samuelmtimbo/unit

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Build & Packaging Layer
  subgraph "Build & Packaging Layer"
    direction TB
    P_JSON["package.json"]:::build
    SCRPT["src/script/"]:::build
    SBUILD["src/build/"]:::build
    P_JSON --> SCRPT
    SCRPT --> SBUILD
    SBUILD --> CLIENT_BUNDLE
    SBUILD --> WORKER_BUNDLE
    SBUILD --> SYSTEM_BUNDLE
  end

  %% Output Bundles
  CLIENT_BUNDLE["Client Bundle"]:::build
  WORKER_BUNDLE["Worker Bundle"]:::build
  SYSTEM_BUNDLE["System Bundle"]:::build

  %% Browser Frontend
  subgraph "Browser Frontend"
    direction TB
    HTML["public/index.html"]:::ui
    CLIENT_BUNDLE --> HTML
    RENDER["src/client/render/"]:::ui
    EVENT["src/client/event/"]:::ui
    API_UI["makeRemoteUnitAPI"]:::ui
    HTML --> RENDER
    HTML --> EVENT
    HTML --> API_UI
  end

  %% Web Worker
  subgraph "Web Worker"
    direction TB
    WORKER_ENTRY["src/worker/system.ts"]:::engine
    WORKER_HELPER["src/client/platform/web/port/worker.ts"]:::engine
    WORKER_BUNDLE --> WORKER_ENTRY
    WORKER_ENTRY --> WORKER_HELPER
  end

  %% Node.js Backend
  subgraph "Node.js Backend"
    direction TB
    SERVE["src/server/serve.ts"]:::server
    BOOT["src/boot/index.ts"]:::server
    PEER_API["src/api/server/"]:::server
    SERVE --> BOOT
    BOOT --> PEER_API
  end

  %% Core Graph Engine & Language Spec
  subgraph "Core Graph Engine & Spec"
    direction TB
    CLASS["src/Class/"]:::engine
    SYSCORE["src/system/"]:::engine
    SYSF["src/system/f/"]:::engine
    SPEC["src/spec/"]:::engine
    SYSCORE --> SYSF
    SYSCORE --> SPEC
  end

  %% External Services & APIs
  subgraph "External & Platform APIs"
    direction TB
    PEER_NET(("Peer-to-Peer Network")):::external
    STORAGE[(Local/Session Storage)]:::external
    SPEECH[(Speech API)]:::external
  end

  %% Relationships & Data Flows
  HTML -->|"postMessage"| WORKER_ENTRY
  HTML -->|"HTTP GET / Static Files"| SERVE
  HTML -->|"WebSocket/REST"| SERVE
  WORKER_ENTRY -->|"loads"| SYSCORE
  SYSCORE --> CLASS
  SYSCORE --> SPEC
  HTML -->|"Storage Access"| STORAGE
  HTML -->|"Speech Invoke"| SPEECH
  HTML -->|"Peer API"| PEER_NET

  %% Click Events
  click P_JSON "https://github.com/samuelmtimbo/unit/blob/main/package.json"
  click SCRPT "https://github.com/samuelmtimbo/unit/tree/main/src/script/"
  click SBUILD "https://github.com/samuelmtimbo/unit/tree/main/src/build/"
  click HTML "https://github.com/samuelmtimbo/unit/blob/main/public/index.html"
  click RENDER "https://github.com/samuelmtimbo/unit/tree/main/src/client/render/"
  click EVENT "https://github.com/samuelmtimbo/unit/tree/main/src/client/event/"
  click API_UI "https://github.com/samuelmtimbo/unit/blob/main/src/client/makeRemoteUnitAPI.ts"
  click WORKER_ENTRY "https://github.com/samuelmtimbo/unit/blob/main/src/worker/system.ts"
  click WORKER_HELPER "https://github.com/samuelmtimbo/unit/blob/main/src/client/platform/web/port/worker.ts"
  click SERVE "https://github.com/samuelmtimbo/unit/blob/main/src/server/serve.ts"
  click BOOT "https://github.com/samuelmtimbo/unit/blob/main/src/boot/index.ts"
  click PEER_API "https://github.com/samuelmtimbo/unit/tree/main/src/api/server/"
  click CLASS "https://github.com/samuelmtimbo/unit/tree/main/src/Class/"
  click SYSCORE "https://github.com/samuelmtimbo/unit/tree/main/src/system/"
  click SYSF "https://github.com/samuelmtimbo/unit/tree/main/src/system/f/"
  click SPEC "https://github.com/samuelmtimbo/unit/tree/main/src/spec/"

  %% Styles
  classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef engine fill:#98FB98,stroke:#333,stroke-width:1px
  classDef server fill:#FFA500,stroke:#333,stroke-width:1px
  classDef build fill:#D3D3D3,stroke:#333,stroke-width:1px
  classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
