# flydelabs/flyde architecture

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

- Interactive diagram: https://gitdiagram.com/flydelabs/flyde
- Repository: https://github.com/flydelabs/flyde

## Overview

##### Project Type & Purpose
- Flyde is an open-source visual programming platform delivered as a monorepo.
- It provides:
- A runtime library for executing “.flyde” flows in Node.js or the browser.
- A resolver to load, link and type-check flow definitions against TS/JS code.
- A rich standard-library of nodes.
- Embeddable React flow-editor components (used in Playground and VSCode).
- A Dev-Server for local flow hosting, hot-reload and code resolution.
- A VSCode extension to edit flows inside the IDE.
- A public website & docs.
- A Next.js Playground app for browser‐based flow creation & execution (with Supabase auth).

##### High-Level Architecture & Components

A. Apps & UIs (Frontend)
- VSCode Extension
– Hosts embedded flow-editor (Flow-Editor package) inside VSCode WebView
– Uses `@flyde/core`, `@flyde/resolver` and communicates with `remote-debugger`.
- Web Playground (Next.js app)
– Pages + API routes
– Embeds the same Flow-Editor component
– Talks to Dev-Server for scanning, code resolution, and to Supabase for auth/storage.
- Website & Docs (Docusaurus)
– Uses the UI library for styling and embeds flow previews (EmbeddedFlyde).

B. Flow-Editor & UI Libraries (Shared React Components)
- `flow-editor` package
– Visual graph rendering, UI for nodes, ports, connections, debugger overlays.
- `ui` package

C. Core Logic Libraries (Business Logic)
- `@flyde/core`
– Defines flow schemas, node instances, type metadata, debug event streams.
- `@flyde/resolver`
– Parses `.flyde` files, resolves imports (JS/TS), inlines custom code nodes, performs AST‐level linking.
- `@flyde/runtime`
– Executes flows step by step, emits debug events, supports cleanups and progression reporting.
- `@flyde/stdlib`
– Pre-built nodes (HTTP, FS, Lists, ControlFlow, OpenAI, etc.) packaged as Flow-Editor config and runtime components.

D. Supporting Services & Tools
- Dev-Server (`dev-server` package)
– Express-based CLI + HTTP server
– Scans file system, bundles dependencies, generates TypeScript typings for flows, hot-reloads clients.
- Remote Debugger (`remote-debugger` package)
– WebSocket / postMessage bridge between the runtime (in browser or Node) and the editor UI for step-through debugging.
- Examples & Playground Helpers
– Example flows demonstrating custom macros, CLI apps, Discord bots, geolocation, loan apps.
- Build & Workspace Management
– `pnpm-workspace.yaml`, root `tsconfig.json`, build scripts, per‐package `tsconfig.json`, Wallaby/Jest specs.

##### Relationships & Data Flows
- The VSCode Extension and Web Playground both embed the Flow-Editor React component.
- On load, the editor UI asks the Resolver to load & link a flow, which in turn uses Core types & Stdlib definitions.
- When “Run” is invoked, the Runtime is instantiated (in-browser or in Node via Dev-Server), executing the flow, emitting debug events.
- Debug events travel via Remote-Debugger to the editor UI to render execution highlights.
- Dev-Server watches `.flyde` files, rebuilds on change, regenerates typings and notifies clients for HMR.
- Supabase (in Playground) handles user auth and persisting flow definitions.

##### Architectural Patterns & Principles
- Monorepo modularization: each package (core, resolver, runtime, stdlib, ui, flow-editor, editor apps) has a single responsibility.
- Layered architecture: UI → business logic → execution engine → external services.
- Message‐driven debugging: runtime emits events, UI subscribes via remote bridge.
- Extensibility: custom macro nodes, plug-in standard library, patchable editor via “dependencies-patch.”
- Full-stack TypeScript: shared types, AST transforms, end-to-end type safety.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Apps & UIs Layer
    subgraph "Apps & UIs" 
        direction TB
        vscodeExt["VSCode Extension"]:::frontend
        playground["Web Playground (Next.js)"]:::frontend
        website["Website & Docs (Docusaurus)"]:::frontend
    end

    %% Shared React Components
    subgraph "Shared React Libraries" 
        direction TB
        flowEditor["flow-editor"]:::shared
        uiLib["ui"]:::shared
    end

    %% Core Logic Libraries
    subgraph "Core Libraries" 
        direction TB
        flydeCore["@flyde/core"]:::core
        flydeResolver["@flyde/resolver"]:::core
        flydeRuntime["@flyde/runtime"]:::core
        flydeStdlib["@flyde/stdlib"]:::core
    end

    %% Supporting Services & Tools
    subgraph "Supporting Services & Tools"
        direction TB
        devServer["dev-server"]:::backend
        remoteDebugger["remote-debugger"]:::backend
        supabase["Supabase"]:::backend
    end

    %% Relationships
    %% Embedding flow-editor in UIs
    vscodeExt -->|"embeds"| flowEditor
    playground -->|"embeds"| flowEditor
    website -->|"embeds"| flowEditor

    %% UI libraries usage
    flowEditor -->|"uses"| uiLib
    website -->|"uses"| uiLib
    playground -->|"uses"| uiLib

    %% Flow load: Editor -> Resolver -> Core & Stdlib
    flowEditor -->|"pnpm import"| flydeResolver
    flydeResolver -->|"uses types from"| flydeCore
    flydeResolver -->|"includes metadata from"| flydeStdlib

    %% Execution: Editor -> Runtime
    flowEditor -->|"instantiate & run"| flydeRuntime
    flydeRuntime -->|"uses implementations from"| flydeStdlib

    %% Debug events: Runtime -> Remote Debugger -> Editor
    flydeRuntime -->|"WebSocket"| remoteDebugger
    vscodeExt -->|"postMessage"| remoteDebugger
    playground -->|"WebSocket"| remoteDebugger
    remoteDebugger -->|"postMessage"| flowEditor

    %% Playground dev-server interactions
    playground -->|"HTTP"| devServer
    devServer -->|"HMR WebSocket"| flowEditor
    devServer -->|"generates typings for"| flydeResolver

    %% Playground Supabase
    playground -->|"HTTP (auth, storage)"| supabase

    %% VSCode Extension uses core & resolver
    vscodeExt -->|"pnpm import"| flydeCore
    vscodeExt -->|"pnpm import"| flydeResolver
    vscodeExt -->|"connects via"| remoteDebugger

    %% Stdlib plug-in relationships
    flydeStdlib -->|"type info to"| flydeResolver
    flydeStdlib -->|"impl to"| flydeRuntime

    %% Click Events
    click flydeCore "https://github.com/flydelabs/flyde/tree/main/core/"
    click flydeResolver "https://github.com/flydelabs/flyde/tree/main/resolver/"
    click flydeRuntime "https://github.com/flydelabs/flyde/tree/main/runtime/"
    click flydeStdlib "https://github.com/flydelabs/flyde/tree/main/stdlib/"
    click uiLib "https://github.com/flydelabs/flyde/tree/main/ui/"
    click flowEditor "https://github.com/flydelabs/flyde/tree/main/flow-editor/"
    click devServer "https://github.com/flydelabs/flyde/tree/main/dev-server/"
    click remoteDebugger "https://github.com/flydelabs/flyde/tree/main/remote-debugger/"
    click vscodeExt "https://github.com/flydelabs/flyde/tree/main/vscode-extension/"
    click playground "https://github.com/flydelabs/flyde/tree/main/playground/"
    click website "https://github.com/flydelabs/flyde/tree/main/website/"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef shared fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    classDef core fill:#ffcc80,stroke:#ef6c00,color:#e65100
    classDef backend fill:#ce93d8,stroke:#6a1b9a,color:#4a148c
```
