# devhelpr/code-flow-canvas architecture

> Architecture diagram of the GitHub repository devhelpr/code-flow-canvas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devhelpr/code-flow-canvas
- Repository: https://github.com/devhelpr/code-flow-canvas

## Overview

##### Project type and purpose
- This is a full-stack monorepo for a browser-based visual programming system ("Codeflowcanvas") that lets users build, run, and export “flows” (node graphs) in vanilla JS/TS.
- It uses an Nx/Lerna monorepo to manage multiple shared libraries and two “apps”:
- apps/vps-web – the main front-end SPA (Vite + TS + DOM components + web workers for execution)
- apps/vps-api – a small Deno service that can serve HTML or static assets via REST endpoints

##### File structure
- Top-level orchestrator: nx.json, lerna.json, package.json, tsconfig.base.json
- apps/ – two runnable targets:
- vps-web: Vite/React-like SPA, Playwright and Vitest tests, custom Babel JSX plugin, web-workers in src/app/ai-flow-engine-worker, IndexedDB storage.
- vps-api: Deno service, entry main.ts, HTML-from-API endpoint.
- libs/ – six distinct packages providing core architecture:
- visual-programming-system: core canvas, state machines, thumbs/geometry, reactivity, themes
- web-flow-executor: business-logic engine that interprets/executes a flow JSON at runtime
- app-canvas: glue code to render flows, host command handlers, importers/exporters (OCIF, Tldraw), follow-path animations
- dom-components: a tiny framework for web components/atoms
- media-library: asset management library
- ocif: import/export schema support
- tools/, .github/workflows: CI (build, test), CD (npm publish, deploy to Cloudflare via wrangler)

##### README
- Confirms it’s a “Generic Visual programming system using vanilla DOM and JS.”
- Running instructions (npm start → Vite dev of vps-web; Deno for vps-api).
- No DB or external 3rd-party dependency beyond optional AI or file hosting.

1. Monorepo Orchestrator
– Nx / Lerna / GitHub Actions
2. Shared Libraries
– visual-programming-system
– web-flow-executor
– app-canvas
– dom-components
– media-library
– ocif
3. Frontend (apps/vps-web)
– Vite dev server / build
– Browser
– Web Worker (ai-flow-engine-worker)
– IndexedDB storage provider
– UI pages / flows / test harness
4. Backend (apps/vps-api)
– Deno HTTP server
– html-from-api endpoint
5. CI/CD & Deployment
– GitHub Actions (ci.yml, deploy.yml)
– Wrangler (Cloudflare Workers)
– npm registry (package publish)

b. Relationships & data flow
- Monorepo → builds/publishes libs & apps
- apps/vps-web imports Shared Libraries (visual-programming-system, web-flow-executor, app-canvas, dom-components, media-library, ocif)
- Browser UI ↔ Web Worker for heavy flow execution
- Browser UI ↔ IndexedDB for flow persistence
- apps/vps-api ↔ static assets or flow definitions (optional hosting)
- CI pipeline triggers build & deploy of apps and libs → Cloudflare / npm

c. Architectural patterns & principles
– Monorepo modularization: well-scoped TS packages with isolated tsconfig & vite.config
– Layered UI: DOM components (dom-components) → Canvas host (app-canvas) → Core rendering & execution (visual-programming-system + web-flow-executor)
– Worker offload: heavy compute in ai-flow-engine-worker
– Import/Export abstraction: OCIF schema library
– IndexedDB abstraction for persistence

d. Key technologies & frameworks
– Nx / Lerna, TypeScript, Vite, Babel (custom JSX), Deno, Vitest, Playwright
– Web components / vanilla DOM for UI, Web Workers for concurrency, IndexedDB for storage
– OCIF & tldraw exporters

## Diagram (Mermaid)

```mermaid
graph TB
    %% Monorepo Orchestrator
    subgraph "Monorepo Orchestrator"
        nxJson["nx.json"]:::code
        lernaJson["lerna.json"]:::code
        packageJson["package.json"]:::code
        projectJson["project.json"]:::code
        ciYml[".github/workflows/ci.yml"]:::pipeline
        deployYml[".github/workflows/deploy.yml"]:::pipeline
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        vpsCore["visual-programming-system"]:::code
        webExec["web-flow-executor"]:::code
        appCanvas["app-canvas"]:::code
        domComponents["dom-components"]:::code
        mediaLib["media-library"]:::code
        ocif["ocif"]:::code
    end

    %% Frontend
    subgraph "Frontend: vps-web (Vite + TS SPA)"
        appsDir["apps/vps-web/"]:::code
        viteConfig["vite.config.ts"]:::code
        srcDir["src/"]:::code
        indexHtml["index.html"]:::code
        publicDir["public/"]:::code

        subgraph "Web Worker"
            aiWorkerTs["ai-flow-engine-worker.ts"]:::code
            aiWorkerMsgTs["ai-flow-engine-worker-message.ts"]:::code
        end

        subgraph "UI Pages & Components"
            pagesDir["pages/"]:::code
            flowElementTs["flow-app.element.ts"]:::code
            mainTsx["main.tsx"]:::code
        end

        subgraph "Testing"
            e2eDir["e2e/"]:::code
            testsDir["tests/"]:::code
            playwrightCfg["playwright.config.ts"]:::code
            vitestCfg["vitest.config.ts"]:::code
        end

        subgraph "Babel JSX Plugin"
            customJsxTs["custom-jsx-compiler.ts"]:::code
            vitePluginJsxTs["vite-plugin-jsx-compiler.ts"]:::code
        end
    end

    %% Backend
    subgraph "Backend: vps-api (Deno HTTP Server)"
        mainTs["main.ts"]:::service
        htmlFromApi["html-from-api.ts"]:::service
        denoJson["deno.json"]:::code
    end

    %% CI/CD & Deployment Extras
    subgraph "CI/CD & Deployment"
        toolsPublish["tools/scripts/publish.mjs"]:::pipeline
        wranglerToml["wrangler.toml"]:::pipeline
    end

    %% Runtime & Data Stores
    BrowserUI["Browser UI"]:::service
    IndexedDB[(IndexedDB)]:::storage
    npmRegistry["npm Registry"]:::service
    cloudflare["Cloudflare Workers"]:::service

    %% Connections
    packageJson -->|builds/publishes| vpsCore
    packageJson -->|builds/publishes| webExec
    packageJson -->|builds/publishes| appCanvas
    packageJson -->|builds/publishes| domComponents
    packageJson -->|builds/publishes| mediaLib
    packageJson -->|builds/publishes| ocif
    packageJson -->|builds/publishes| appsDir
    packageJson -->|builds/publishes| mainTs

    appsDir --> viteConfig
    appsDir --> srcDir
    appsDir --> indexHtml
    appsDir --> publicDir

    appsDir -->|depends on| vpsCore
    appsDir -->|depends on| webExec
    appsDir -->|depends on| appCanvas
    appsDir -->|depends on| domComponents
    appsDir -->|depends on| mediaLib
    appsDir -->|depends on| ocif

    appsDir -->|serves to| BrowserUI
    mainTs -->|HTTP serves| BrowserUI

    BrowserUI -->|message passing| aiWorkerTs
    aiWorkerTs -->|message passing| BrowserUI

    BrowserUI -->|stores flows| IndexedDB

    ciYml -->|triggers build| packageJson
    ciYml -->|deploys| wranglerToml
    ciYml -->|publishes| npmRegistry
    deployYml -->|deploys| cloudflare
    toolsPublish -->|publishes| npmRegistry

    %% Click Events
    click nxJson "https://github.com/devhelpr/code-flow-canvas/blob/main/nx.json"
    click lernaJson "https://github.com/devhelpr/code-flow-canvas/blob/main/lerna.json"
    click packageJson "https://github.com/devhelpr/code-flow-canvas/blob/main/package.json"
    click projectJson "https://github.com/devhelpr/code-flow-canvas/blob/main/project.json"
    click ciYml "https://github.com/devhelpr/code-flow-canvas/blob/main/.github/workflows/ci.yml"
    click deployYml "https://github.com/devhelpr/code-flow-canvas/blob/main/.github/workflows/deploy.yml"
    click vpsCore "https://github.com/devhelpr/code-flow-canvas/tree/main/libs/visual-programming-system/"
    click webExec "https://github.com/devhelpr/code-flow-canvas/tree/main/libs/web-flow-executor/"
    click appCanvas "https://github.com/devhelpr/code-flow-canvas/tree/main/libs/app-canvas/"
    click domComponents "https://github.com/devhelpr/code-flow-canvas/tree/main/libs/dom-components/"
    click mediaLib "https://github.com/devhelpr/code-flow-canvas/tree/main/libs/media-library/"
    click ocif "https://github.com/devhelpr/code-flow-canvas/tree/main/libs/ocif/"
    click appsDir "https://github.com/devhelpr/code-flow-canvas/tree/main/apps/vps-web/"
    click viteConfig "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/vite.config.ts"
    click srcDir "https://github.com/devhelpr/code-flow-canvas/tree/main/apps/vps-web/src/"
    click indexHtml "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/index.html"
    click publicDir "https://github.com/devhelpr/code-flow-canvas/tree/main/apps/vps-web/public/"
    click aiWorkerTs "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/src/app/ai-flow-engine-worker/ai-flow-engine-worker.ts"
    click aiWorkerMsgTs "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/src/app/ai-flow-engine-worker/ai-flow-engine-worker-message.ts"
    click pagesDir "https://github.com/devhelpr/code-flow-canvas/tree/main/apps/vps-web/src/app/pages/"
    click flowElementTs "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/src/app/flow-app.element.ts"
    click mainTsx "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/src/main.tsx"
    click e2eDir "https://github.com/devhelpr/code-flow-canvas/tree/main/apps/vps-web/e2e/"
    click testsDir "https://github.com/devhelpr/code-flow-canvas/tree/main/apps/vps-web/src/tests/"
    click playwrightCfg "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/playwright.config.ts"
    click vitestCfg "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/vitest.config.ts"
    click customJsxTs "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/vite/babel/custom-jsx-compiler.ts"
    click vitePluginJsxTs "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-web/vite/vite-plugin-jsx-compiler.ts"
    click mainTs "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-api/src/main.ts"
    click htmlFromApi "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-api/src/html-from-api.ts"
    click denoJson "https://github.com/devhelpr/code-flow-canvas/blob/main/apps/vps-api/deno.json"
    click toolsPublish "https://github.com/devhelpr/code-flow-canvas/blob/main/tools/scripts/publish.mjs"
    click wranglerToml "https://github.com/devhelpr/code-flow-canvas/blob/main/wrangler.toml"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0366d6
    classDef service fill:#D0FFD8,stroke:#28a745
    classDef pipeline fill:#FFE8B0,stroke:#d18600
    classDef storage fill:#F0F0F0,stroke:#888888,stroke-dasharray: 4 2
```
