ChainGraph v2

ChainGraph is a source-available, flow-based programming framework that empowers developers to visually design, execute, and manage complex computational graphs. Whether you're building custom AI agents, data processing pipelines, or collaborative automation systems, ChainGraph's modular architecture, strong type-safety guarantees, and real-time features help you build robust workflows efficiently.

Disclaimer: This version is intended for demonstration and experimentation purposes only. The API and internal architecture are still evolving, and breaking changes may occur as new features are added and improvements are made.

Table of Contents

• Key Features
• Architecture & Technologies
• Getting Started
• Installation
• Running in Development Mode
• PostgreSQL Database Storage
• Building for Production
• Docker & Docker-compose
• Project Structure
• Contributing
• Development Tools
• Current Limitations & Work-In-Progress
• Release Process
• Developer Documentation
• License

Key Features

• Type-Safe Port System: Supports a rich set of port types including primitives (string, number, boolean) and complex types (arrays, objects, streams, enums). Each port is defined with its own configuration and runtime validation (via Zod and SuperJSON) and employs both lazy instantiation and caching for optimal memory usage.

• Modular and Extensible Nodes: Create custom nodes using decorators and metadata. Nodes feature multiple input and output ports and integrate seamlessly into the flow builder, enabling rapid development of complex workflows.

• Visual Flow Editor: Build flows graphically with a React- and XYFlow-based frontend. Enjoy features like drag-and-drop layout, zoom and pan, resizing, contextual menus, and live previews.

• Robust Execution Engine & Debugging Tools: A backend execution engine supports concurrent execution of flows with real-time event subscriptions, plus debugging features such as breakpoints, step-over, and detailed event logging for effective troubleshooting.

• Real-Time Synchronization & Optimistic Updates: Integrated with tRPC and Effector for end-to-end type safety, the system provides real-time updates (via WebSockets) and supports optimistic UI updates—ensuring an interactive and responsive user experience.

• Docker and Cloud Compatibility: Easily build, deploy, and scale both the backend and frontend using Docker and docker-compose. Containerized deployment simplifies the setup process and enhances portability.

Architecture & Technologies

ChainGraph is built with modern web technologies, aiming at a robust and type-safe development experience:

• TypeScript: Uses advanced TypeScript features (generics, decorators, conditional types) for compile-time safety and robustness.

• Effector: A reactive state management library that powers both frontend and backend state handling and simplifies the implementation of optimistic updates and subscriptions.

• tRPC: Facilitates end-to-end type-safe API communication between the frontend and backend, minimizing runtime errors and ensuring consistency in data handling.

• Zod & SuperJSON: Zod is used for runtime schema validation, while SuperJSON manages complex data serialization, ensuring that data remains consistent across the client and server boundaries.

• XYFlow: A visual flow library used on the frontend to render and manage the drag-and-drop canvas, enabling users to compose workflows visually.

• WebSockets: Real-time subscriptions using WebSocket (via tRPC's adapter) keep the client in constant sync with backend state and execution events.

Getting Started

ChainGraph provides a complete development environment with hot module reloading, integrated testing, and containerized deployment options. This guide covers local installation and Docker-based setups.

Installation

Clone the repository and install dependencies:

git clone https://github.com/badaitech/chaingraph.git
cd chaingraph
pnpm install

Running in Development Mode

To start the development environment (both frontend and backend), run:

pnpm run dev

This command launches:

• The frontend development server (with hot reloading)
• The backend development process (watch mode)

You can also run each package individually if desired:

• Backend: pnpm run dev:back
• Frontend: pnpm run dev:front

Debugging with IDE

ChainGraph supports debugging TypeScript source files directly in WebStorm or VS Code:

WebStorm:

1. Open Run/Debug Configurations
2. Create a new Bun configuration:
   • File: apps/chaingraph-backend/src/index.ts (or other app)
   • Bun parameters: --conditions=development
3. Set breakpoints in TypeScript files and start debugging

VS Code: Add to .vscode/launch.json:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Backend",
  "runtimeExecutable": "bun",
  "runtimeArgs": ["--conditions=development", "--watch", "run", "src/index.ts"],
  "cwd": "${workspaceFolder}/apps/chaingraph-backend"
}

The --conditions=development flag enables debugging TypeScript source files directly without relying on source maps.

Frontend (Browser): The frontend automatically supports TypeScript debugging in browser DevTools:

1. Start dev server: pnpm run dev:front
2. Open Chrome/Firefox and navigate to http://localhost:3004
3. Open DevTools (F12) → Sources/Debugger tab
4. Press Cmd+P (or Ctrl+P) to quick-open files
5. Set breakpoints in .tsx/.ts files (click line numbers)
6. Interact with the app to trigger breakpoints

WebStorm (JavaScript Debug):

1. Run → Edit Configurations → + → npm
2. Configuration tab:
   • package.json: Select apps/chaingraph-frontend/package.json
   • Command: run
   • Scripts: dev
3. Switch to Browser / Live Edit tab:
   • Check "After launch"
   • Browser: Chrome (or Edge/Firefox)
   • Check "with JavaScript debugger"
   • URL: http://localhost:3004
4. Click OK, set breakpoints in .tsx files, then click Debug

Source maps are enabled by default in development. You can debug both your app code and workspace packages (@badaitech/*).

PostgreSQL Database Storage

ChainGraph can be configured to use PostgreSQL for persistent storage instead of the default in-memory storage solution. Follow these steps to set up database storage:

1. Start PostgreSQL Database

Use the included Docker Compose configuration to start a PostgreSQL database:

docker compose up -d postgres

This will start a PostgreSQL instance accessible on port 5432.

2. Configure Database Connection

Create a .env file in the project root with your database connection parameters based on the provided .env.example:

DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable

3. Run Database Migrations

Before starting ChainGraph with PostgreSQL storage, you need to run migrations to create the necessary database schema:

pnpm run migrate

This command will create all required tables and indexes in your PostgreSQL database.

4. Start ChainGraph with Database Storage

Once migrations are complete, you can start ChainGraph as usual. It will automatically detect and use the PostgreSQL database for persistent storage:

pnpm run dev

With this configuration, your flows, nodes, and execution data will be stored persistently in PostgreSQL instead of being lost when the server restarts.

Building for Production

To build the entire project, execute:

pnpm run build

You can also build specific packages:

# Build frontend only
pnpm run build:front

# Build backend only
pnpm run build:back

To preview the production build:

pnpm run preview

Docker & Docker-compose

ChainGraph can also be built and run using Docker. The repository includes Dockerfiles for both the backend and frontend, along with a docker-compose configuration for orchestrating the containers.

Building Docker Images

You can build Docker images for individual components using the Makefile targets:

• Build backend image:

  make docker-build-backend
  

• Build frontend image:

  make docker-build-frontend
  

• Build both images:

  make docker-build-all
  

Alternatively, you can build them manually using Docker commands. For example, to build the backend image manually use:

docker build -t chaingraph-backend -f apps/chaingraph-backend/Dockerfile .

And likewise for the frontend:

docker build -t chaingraph-frontend -f apps/chaingraph-frontend/Dockerfile .

Running with Docker-compose

Use docker-compose to launch both containers concurrently. In the repository root, run:

make docker-compose-up

This command will start the backend on port 3001 and the frontend (serving on port 80 inside the container, mapped to 5173 on your host). To stop and remove containers, run:

make docker-compose-down

You can also run these commands manually:

docker-compose up -d      # Start containers in the background
docker-compose down       # Stop and remove containers

Project Structure

• packages/chaingraph-types: Contains shared type definitions, interfaces, port implementations, node/event models, and utilities ensuring end-to-end type safety.

• packages/chaingraph-nodes: A collection of pre-built