How pascobrain/workflow-canvas works
1. This repository is a Next.js 16 app-router project that combines a browser-based workflow builder with a server-side API. The main runtime boundary is between React UI in app/ and route handlers in app/api/, with PostgreSQL-backed persistence underneath.
2. The user-facing application lives in app/page.tsx and app/workflows/**. The /workflows area is the core product surface: a workflow list, a workflow detail/editor page, and a nested layout for workflow-specific navigation and state.
3. The workflow editor is built from the components/workflow/** and components/ai-elements/** trees. These components provide the visual canvas, nodes, toolbar, context menus, configuration panels, and run history UI. The architecture is centered on a graph editor model: trigger nodes feed action nodes, and the editor stores both layout and workflow semantics.
4. Server-side workflow management is exposed through app/api/workflows/**. This includes CRUD for workflows, duplication, current-workflow lookup, code export/download, webhook binding, execution history, and execution status/log access. These routes form the main backend contract for the UI.
5. Workflow execution is a distinct subsystem. The execution route under app/api/workflow/[workflowId]/execute and the execution log/status routes indicate that runs are persisted separately from workflow definitions. The runtime pieces in lib/workflow-executor.workflow.ts, lib/workflow-logging.ts, lib/workflow-store.ts, and lib/steps/** are the likely orchestration layer that turns a workflow graph into executable steps and records the results.
6. The repository has a plugin architecture for integrations, and it is one of the most important boundaries in the system. Each integration under plugins/<name>/ defines credentials, icons, step implementations, and a test harness. plugins/registry.ts, plugins/index.ts, and scripts/discover-plugins.ts suggest the app dynamically discovers and registers these packages so they can appear in the builder and be executed by the engine.
7. Workflow “steps” are a shared abstraction across the app. Core step types live in lib/steps/** for conditions, triggers, HTTP requests, database queries, and credential handling, while plugin-specific actions add specialized capabilities like Slack, Resend, GitHub, Linear, Stripe, Firecrawl, Webflow, and AI gateway calls. This separation keeps generic execution logic independent from external service APIs.
8. Code generation is a major subsystem. lib/workflow-codegen.ts, lib/workflow-codegen-sdk.ts, lib/workflow-codegen-shared.ts, and components/workflow/utils/code-generators.ts indicate the app can turn visual workflows into TypeScript with a "use workflow" directive. The generated code is intended to be executable, type-safe, and aligned with the same step catalog used by the visual editor.
9. AI-assisted workflow creation is handled separately from normal workflow execution. The routes under app/api/ai/generate and the AI Gateway routes in app/api/ai-gateway/** expose consent/status/team management and generation endpoints. lib/ai-gateway/** and the plugins/ai-gateway package show that AI is both a product feature and an integration target within the workflow system.
10. Persistence is centered on Drizzle ORM and PostgreSQL. lib/db/schema.ts, lib/db/index.ts, drizzle.config.ts, and the drizzle/ migrations define the data model, which includes users, sessions, workflows, workflow executions, and execution logs. The architecture clearly separates durable workflow definitions from transient run state.
11. Authentication is handled with Better Auth via app/api/auth/[...all], lib/auth.ts, lib/auth-client.ts, and lib/auth-providers.ts. This auth layer gates user-facing workflow and integration operations, and it ties into account settings, sessions, and API-key management routes.
12. Integrations are also exposed as first-class backend resources. app/api/integrations/**, app/api/api-keys/**, app/api/user/route.ts, and lib/integrations-store.ts indicate that the app stores integration configuration, tests connectivity, and lets users manage credentials/API keys through the UI overlays in components/overlays/** and settings components in components/settings/**.
13. The UI shell is assembled from reusable design-system primitives in components/ui/**, auth and theme providers, global modals, and workflow-specific overlays. State for overlays and canvas interactions is split across Jotai atoms in lib/atoms/**, provider components, and editor-specific context/state components, which keeps the canvas responsive while the backend remains authoritative.
14. Operationally, the repo is set up for deployment and validation with Vercel, Drizzle migrations, and end-to-end tests in e2e/workflow.spec.ts. The presence of vercel-template.json, GitHub Actions in .github/workflows/, and Playwright config shows this is meant to be deployed as a full product, not just a library.
Main entry points: page.tsx Workflows · workflow-canvas.tsx Workflow Editor · workflow-executor.workflow.ts Executor · index.ts Step Library
Components 23
App Router
User-facing routes and API handlers
- Home · Top-level landing page and entrypoint
app/page.tsx - Workflows · Workflow list and workflow detail/editor surface
app/workflows/page.tsx - Workflow Shell · Per-workflow route shell and state boundary
app/workflows/[workflowId]/layout.tsx - Workflow API · CRUD, duplication, code export, webhook binding, and execution history
app/api/workflows/route.ts - Run API · Workflow execution trigger and execution-status/log access
app/api/workflow/[workflowId]/execute/route.ts - AI API · AI generation plus AI Gateway consent, status, and team routes
app/api/ai/generate/route.ts - Auth API · Better Auth entrypoint for sessions and identity
app/api/auth/[...all]/route.ts - Integrations API · Integration listing, testing, and credential-backed resource management
app/api/integrations/route.ts
Frontend UI
Workflow editor, overlays, and shared components
- Workflow Editor · Visual builder for nodes, connections, configuration, and runs
components/workflow/workflow-canvas.tsx - AI Canvas · Specialized canvas and node primitives used by the builder experience
components/ai-elements/canvas.tsx - Overlays · Dialogs, drawers, export, settings, integration, and consent flows
components/overlays/overlay-container.tsx - UI Shell · Reusable primitives, auth shell, theme, and global controls
components/ui/button.tsx
Workflow Core
Execution, code generation, and shared step logic
- Executor · Turns workflow graphs into step execution and persists results
lib/workflow-executor.workflow.ts - Workflow Store · Workflow definition and execution state access layer
lib/workflow-store.ts - Codegen · Generates executable workflow code with shared step metadata
lib/workflow-codegen.ts - Step Library · Core trigger, condition, HTTP, database, and credential steps
lib/steps/index.ts - Logging · Run logs and execution status recording
lib/workflow-logging.ts
Integrations
Plugin registry and provider packages
- Plugin Registry · Discovers and registers integration packages for the builder and engine
plugins/registry.ts - Plugins · Provider packages with credentials, icons, steps, and tests
plugins/index.ts
Data & Ops
Database schema, migrations, tests, and deployment tooling
- DB Schema · Users, sessions, workflows, executions, logs, and integrations model
lib/db/schema.ts - Migrations · Versioned PostgreSQL schema evolution
drizzle/0000_easy_supernaut.sql - Auth Layer · Auth client, providers, and server configuration
lib/auth.ts - Ops & Tests · Playwright e2e, Vercel template, and plugin discovery scripts
e2e/workflow.spec.ts
Connections 26
- Home → Workflows: enters · User flow continues into the workflow product surface
- Workflows → Workflow Shell: nests · Workflow pages share a dedicated layout and state boundary
- Workflow Shell → Workflow Editor: renders · Workflow shell mounts the builder and its panels
- Workflows → Workflow API: calls · List, create, update, duplicate, export, and webhook actions
- Workflows → Run API: runs · Editor and history views trigger executions and fetch results
- Workflows → AI API: assists · AI-assisted generation and AI Gateway flows
- Workflows → Integrations API: configures · Connects and tests external services
- Workflows → Auth API: authenticates · Session and identity management for app access
- Workflow Editor → AI Canvas: uses · Canvas, nodes, edges, controls, and prompt surfaces
- Workflow Editor → Overlays: opens · Configuration, export, settings, and issue dialogs
- Workflow Editor → Codegen: exports · Visual workflows can be converted into executable TypeScript
- Workflow Editor → Step Library: binds · Editor node catalog maps to runtime step types
- Workflow API → Workflow Store: reads/writes · Workflow definitions and derived state are persisted through the store
- Run API → Executor: invokes · Execution route starts workflow runs
- Executor → Step Library: executes · Graph nodes resolve to concrete step handlers
- Executor → Logging: records · Execution progress, logs, and status updates
- Executor → Workflow Store: loads/saves · Executor reads workflow definitions and stores run state
- Codegen → Step Library: targets · Generated code is aligned with the shared step catalog
- Plugin Registry → Plugins: registers · Discovered integration packages are added to the runtime catalog
- Plugins → Step Library: extends · Plugin steps expand the executor and editor action set
- Integrations API → Plugin Registry: enumerates · UI and API expose available integrations from registered plugins
- Integrations API → DB Schema: persists · Integration credentials and metadata are stored in PostgreSQL
- Auth Layer → Auth API: backs · Auth route is implemented by the shared auth layer
- DB Schema → Migrations: evolves · Schema is materialized through migrations
- Ops & Tests → Workflow API: validates · End-to-end tests exercise core workflow flows
- Ops & Tests → Plugin Registry: discovers · Scripts build and verify plugin registration