sample-workflow-builder

Overview

This repository is a full-stack workflow builder application that allows users to visually create, edit, and execute workflows composed of multiple steps. It features a modern React-based frontend for interactive workflow design and a Node.js/Express backend with a PostgreSQL database for persistent storage and workflow execution.

---

Features

Frontend (frontend)

• React + Vite: Fast, modern SPA development using React 19 and Vite.
• Visual Workflow Editor: Drag-and-drop interface for creating and connecting workflow steps, powered by @xyflow/react.
• Workflow Management: Create, edit, and delete workflows and steps.
• Step Configuration: Each step can be configured with a type and JSON-based config.
• Execution Modal & Output Panel: Users can execute workflows with custom input variables and view real-time execution logs via Server-Sent Events (SSE).
• Routing: Uses React Router for navigation between workflow list, editor, and forms.

Backend (backend)

• Express API: RESTful endpoints for workflows, steps, connections, and execution.
• PostgreSQL Database: Schema managed by Drizzle ORM and drizzle-kit.
• Workflow Execution Engine: Integrates with @langchain/langgraph to execute workflows as directed acyclic graphs (DAGs), streaming execution events to the frontend via SSE.
• SSE Streaming: Real-time feedback for workflow execution, including step-by-step logs and results.
• Migration Support: Database migrations managed with drizzle-kit.

---

Directory Structure

sample-workflow-builder/
│
├── backend/
│   ├── db/
│   │   ├── schema.js
│   │   ├── queries.js
│   │   └── migrations/
│   ├── services/
│   │   └── workflowExecutor.js
│   ├── index.js
│   ├── migrate.js
│   ├── drizzle.config.js
│   └── .env
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── public/
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
│
├── package.json
└── README.md

---

How It Works

1. Workflow Creation & Editing

• Users create workflows via a form.
• In the editor, users add steps (nodes), connect them (edges), and configure each step's properties.
• All changes are persisted to the backend via REST API calls.

2. Workflow Execution

• Users can execute a workflow, providing initial input variables.
• The backend builds a LangGraph graph from the workflow definition, executes it, and streams real-time events (step start, output, errors, completion) to the frontend using SSE.
• The frontend displays these events in a live output panel.

3. Database Schema

• workflows: Stores workflow metadata.
• steps: Stores individual steps (nodes) for each workflow, including type, config, and position.
• connections: Stores directed edges between steps.
• executions: Stores execution records, including input, output, and status.

---

Technologies Used

• Frontend: React, Vite, @xyflow/react, React Router
• Backend: Node.js, Express, Drizzle ORM, PostgreSQL, dotenv
• Workflow Engine: @langchain/langgraph
• Database Migration: drizzle-kit

---

Getting Started

1. Install dependencies in both backend and frontend folders.
2. Configure your database in backend/.env.
3. Run migrations:

   cd backend
   npm run db:migrate

4. Start the backend:

   node index.js

5. Start the frontend:

   cd ../frontend
   npm run dev

6. Open the app in your browser at the provided Vite dev server URL.

---

API Reference

• Workflows:

  • GET /api/workflows
  • POST /api/workflows
  • GET /api/workflows/:id
  • PUT /api/workflows/:id
  • DELETE /api/workflows/:id

• Steps:

  • POST /api/workflows/:workflowId/steps
  • GET /api/workflows/:workflowId/steps
  • PUT /api/steps/:stepId
  • DELETE /api/steps/:stepId

• Connections:

  • POST /api/workflows/:workflowId/connections
  • GET /api/workflows/:workflowId/connections
  • DELETE /api/connections/:connectionId

• Execution:

  • POST /api/workflows/:workflowId/execute (SSE streaming)

---

Extensibility

• Step Types: Easily add new step types (e.g., LLM, API call, data loader) by extending the execution logic in workflowExecutor.js.
• UI Components: Add new node types or customize the workflow editor by editing components in frontend/src/components.
• Database Schema: Modify or extend the schema in schema.js and generate new migrations.

---

License

This project is licensed under the ISC License. See package.json for details.

---