# terenceccwu/runbok architecture

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

- Interactive diagram: https://gitdiagram.com/terenceccwu/runbok
- Repository: https://github.com/terenceccwu/runbok

## Overview

##### Project type and purpose
- This is an open-source Node.js tool/CLI with a built-in web server and browser-based UI.
- Key clues:
– bin/runbok.js (CLI entry point)
– server.js + public/index.html (server + static front-end)
– utils/ (child-process orchestration: node-inspector, tsc)
– example/ (demonstrates how to wire in libraries, workflows)

##### File structure
- Top-level
– bin/         → CLI launcher (runbok)
– server.js    → core HTTP/WebSocket server
– public/      → static front-end assets
– utils/       → helper modules for spawning and controlling external tools
– example/     → sample project using the tool
- Other files
– package.json/lock → dependencies, scripts

##### Architecture components
a. CLI Component (bin/runbok.js)
– Parses arguments
– Boots server.js
– Watches files, passes config/workflow into server
b. Server Component (server.js)
– HTTP server: serves public/index.html + assets
– WebSocket or REST API: communicates with front-end
– Invokes utils modules to:
- Launch Node Inspector
- Compile TypeScript (utils/tsc.js)
- Manage inspector connection pool (utils/node-inspector-connection-pool.js)
c. Front-end UI (public/index.html + JS/CSS)
– Connects to server via WebSocket/HTTP
– Displays live compilation or debug info
– Sends user commands (rebuild, reload, debug controls)
d. Utils Modules
– Encapsulate child_process logic
– Provide reusable abstraction layers for tooling
e. Example Project (example/src + workflow-1.yml)
– Demonstrates how end users plug in their code and workflows
– Lives outside main tool, but connects via CLI and server API

##### Relationships & Data Flow
– CLI → launches → Server
– Server ↔︎ Utils (spawns child processes for tsc & inspector)
– Server ↔︎ Front-end (HTTP serve + WebSocket/REST)
– Front-end → user actions → Server → triggers Utils → returns results → Front-end

##### Architectural patterns & design principles
– Separation of concerns:
- CLI vs. server vs. front-end vs. utils
– Modularization: utils folder isolates process-control logic
– Extension points: example folder shows how user code/workflow plugs in
– Event-driven: server uses WebSockets/events to push updates to UI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI Layer"
        CLI["bin/runbok.js\n(CLI)"]:::nodejs
    end

    subgraph "Server Layer"
        Server["server.js\n(HTTP/WebSocket Server)"]:::nodejs
    end

    subgraph "Utils Layer"
        TSC["utils/tsc.js\n(TypeScript Compiler)"]:::nodejs
        Inspector["utils/node-inspector.js\n(Debug Launcher)"]:::nodejs
        Pool["utils/node-inspector-connection-pool.js\n(Connection Pool)"]:::nodejs
    end

    subgraph "Front-end Layer"
        Frontend["public/index.html + assets\n(Browser UI)"]:::frontend
    end

    subgraph "Example Project"
        Src["example/src/\n(User Code)"]:::example
        Workflow["example/workflow-1.yml\n(Workflow Definition)"]:::example
    end

    CLI -->|"start server"| Server
    Server -->|"spawn compile"| TSC
    Server -->|"spawn debug"| Inspector
    Server -->|"manage connections"| Pool
    Server -->|"serve assets (HTTP)"| Frontend
    Server -->|"WebSocket (events)"| Frontend
    Frontend -->|"user commands"| Server
    Src -->|"provide code to"| CLI
    Workflow -->|"provide workflow to"| CLI

    click CLI "https://github.com/terenceccwu/runbok/blob/main/bin/runbok.js"
    click Server "https://github.com/terenceccwu/runbok/blob/main/server.js"
    click Frontend "https://github.com/terenceccwu/runbok/blob/main/public/index.html"
    click TSC "https://github.com/terenceccwu/runbok/blob/main/utils/tsc.js"
    click Inspector "https://github.com/terenceccwu/runbok/blob/main/utils/node-inspector.js"
    click Pool "https://github.com/terenceccwu/runbok/blob/main/utils/node-inspector-connection-pool.js"
    click Src "https://github.com/terenceccwu/runbok/tree/main/example/src/"
    click Workflow "https://github.com/terenceccwu/runbok/blob/main/example/workflow-1.yml"

    classDef nodejs fill:#EAEAEA,stroke:#333,stroke-width:2px
    classDef frontend fill:#BBDEFB,stroke:#333,stroke-width:2px
    classDef example fill:#C8E6C9,stroke:#333,stroke-width:2px
```
