# pascobrain/workflow-canvas architecture

> Architecture diagram of the GitHub repository pascobrain/workflow-canvas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pascobrain/workflow-canvas
- Repository: https://github.com/pascobrain/workflow-canvas

## Overview

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: [`app/workflows/page.tsx`](https://github.com/pascobrain/workflow-canvas/blob/main/app/workflows/page.tsx) (Workflows), [`components/workflow/workflow-canvas.tsx`](https://github.com/pascobrain/workflow-canvas/blob/main/components/workflow/workflow-canvas.tsx) (Workflow Editor), [`lib/workflow-executor.workflow.ts`](https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-executor.workflow.ts) (Executor), [`lib/steps/index.ts`](https://github.com/pascobrain/workflow-canvas/blob/main/lib/steps/index.ts) (Step Library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_app_home["Home<br/>next page<br/>[page.tsx]"]
  node_app_workflows["Workflows<br/>next routes<br/>[page.tsx]"]
  node_app_workflow_layout["Workflow Shell<br/>nested layout<br/>[layout.tsx]"]
  node_app_api_workflows["Workflow API<br/>route handlers<br/>[route.ts]"]
  node_app_api_execution["Run API<br/>execution route<br/>[route.ts]"]
  node_app_api_ai["AI API<br/>generation routes<br/>[route.ts]"]
  node_app_api_auth["Auth API<br/>auth route<br/>[route.ts]"]
  node_app_api_integrations["Integrations API<br/>resource routes<br/>[route.ts]"]
end

subgraph group_ui["Frontend UI"]
  node_workflow_editor["Workflow Editor<br/>canvas ui"]
  node_ai_canvas["AI Canvas<br/>visual primitives<br/>[canvas.tsx]"]
  node_overlays["Overlays"]
  node_design_system["UI Shell<br/>shared components<br/>[button.tsx]"]
end

subgraph group_core["Workflow Core"]
  node_workflow_executor["Executor<br/>runtime orchestration"]
  node_workflow_store[("Workflow Store<br/>persistence access<br/>[workflow-store.ts]")]
  node_workflow_codegen["Codegen<br/>typescript generator"]
  node_step_library["Step Library<br/>step abstractions<br/>[index.ts]"]
  node_workflow_logging["Logging<br/>execution logs"]
end

subgraph group_integrations["Integrations"]
  node_plugin_registry["Plugin Registry<br/>discovery layer<br/>[registry.ts]"]
  node_plugin_packages["Plugins<br/>integration packages<br/>[index.ts]"]
end

subgraph group_data["Data & Ops"]
  node_db_schema[("DB Schema<br/>drizzle schema<br/>[schema.ts]")]
  node_drizzle_migrations["Migrations"]
  node_auth_layer["Auth Layer<br/>better auth<br/>[auth.ts]"]
  node_tests_ops["Ops & Tests<br/>tooling<br/>[workflow.spec.ts]"]
end

node_app_home -->|"enters"| node_app_workflows
node_app_workflows -->|"nests"| node_app_workflow_layout
node_app_workflow_layout -->|"renders"| node_workflow_editor
node_app_workflows -->|"calls"| node_app_api_workflows
node_app_workflows -->|"runs"| node_app_api_execution
node_app_workflows -->|"assists"| node_app_api_ai
node_app_workflows -->|"configures"| node_app_api_integrations
node_app_workflows -->|"authenticates"| node_app_api_auth
node_workflow_editor -->|"uses"| node_ai_canvas
node_workflow_editor -->|"opens"| node_overlays
node_workflow_editor -->|"exports"| node_workflow_codegen
node_workflow_editor -->|"binds"| node_step_library
node_app_api_workflows -->|"reads/writes"| node_workflow_store
node_app_api_execution -->|"invokes"| node_workflow_executor
node_workflow_executor -->|"executes"| node_step_library
node_workflow_executor -->|"records"| node_workflow_logging
node_workflow_executor -->|"loads/saves"| node_workflow_store
node_workflow_codegen -->|"targets"| node_step_library
node_plugin_registry -->|"registers"| node_plugin_packages
node_plugin_packages -->|"extends"| node_step_library
node_app_api_integrations -->|"enumerates"| node_plugin_registry
node_app_api_integrations -->|"persists"| node_db_schema
node_auth_layer -->|"backs"| node_app_api_auth
node_db_schema -->|"evolves"| node_drizzle_migrations
node_tests_ops -.->|"validates"| node_app_api_workflows
node_tests_ops -.->|"discovers"| node_plugin_registry

click node_app_home "https://github.com/pascobrain/workflow-canvas/blob/main/app/page.tsx"
click node_app_workflows "https://github.com/pascobrain/workflow-canvas/blob/main/app/workflows/page.tsx"
click node_app_workflow_layout "https://github.com/pascobrain/workflow-canvas/blob/main/app/workflows/[workflowId]/layout.tsx"
click node_app_api_workflows "https://github.com/pascobrain/workflow-canvas/blob/main/app/api/workflows/route.ts"
click node_app_api_execution "https://github.com/pascobrain/workflow-canvas/blob/main/app/api/workflow/[workflowId]/execute/route.ts"
click node_app_api_ai "https://github.com/pascobrain/workflow-canvas/blob/main/app/api/ai/generate/route.ts"
click node_app_api_auth "https://github.com/pascobrain/workflow-canvas/blob/main/app/api/auth/[...all]/route.ts"
click node_app_api_integrations "https://github.com/pascobrain/workflow-canvas/blob/main/app/api/integrations/route.ts"
click node_workflow_editor "https://github.com/pascobrain/workflow-canvas/blob/main/components/workflow/workflow-canvas.tsx"
click node_ai_canvas "https://github.com/pascobrain/workflow-canvas/blob/main/components/ai-elements/canvas.tsx"
click node_overlays "https://github.com/pascobrain/workflow-canvas/blob/main/components/overlays/overlay-container.tsx"
click node_design_system "https://github.com/pascobrain/workflow-canvas/blob/main/components/ui/button.tsx"
click node_workflow_executor "https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-executor.workflow.ts"
click node_workflow_store "https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-store.ts"
click node_workflow_codegen "https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-codegen.ts"
click node_step_library "https://github.com/pascobrain/workflow-canvas/blob/main/lib/steps/index.ts"
click node_workflow_logging "https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-logging.ts"
click node_plugin_registry "https://github.com/pascobrain/workflow-canvas/blob/main/plugins/registry.ts"
click node_plugin_packages "https://github.com/pascobrain/workflow-canvas/blob/main/plugins/index.ts"
click node_db_schema "https://github.com/pascobrain/workflow-canvas/blob/main/lib/db/schema.ts"
click node_drizzle_migrations "https://github.com/pascobrain/workflow-canvas/blob/main/drizzle/0000_easy_supernaut.sql"
click node_auth_layer "https://github.com/pascobrain/workflow-canvas/blob/main/lib/auth.ts"
click node_tests_ops "https://github.com/pascobrain/workflow-canvas/blob/main/e2e/workflow.spec.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_home,node_app_workflows,node_app_workflow_layout,node_app_api_workflows,node_app_api_execution,node_app_api_ai,node_app_api_auth,node_app_api_integrations toneBlue
class node_workflow_editor,node_ai_canvas,node_overlays,node_design_system toneAmber
class node_workflow_executor,node_workflow_store,node_workflow_codegen,node_step_library,node_workflow_logging toneMint
class node_plugin_registry,node_plugin_packages toneRose
class node_db_schema,node_drizzle_migrations,node_auth_layer,node_tests_ops toneIndigo
```

## Components

### App Router

User-facing routes and API handlers

- [Home](https://github.com/pascobrain/workflow-canvas/blob/main/app/page.tsx): next page · Top-level landing page and entrypoint · `app/page.tsx`
- [Workflows](https://github.com/pascobrain/workflow-canvas/blob/main/app/workflows/page.tsx): next routes · Workflow list and workflow detail/editor surface · `app/workflows/page.tsx`
- [Workflow Shell](https://github.com/pascobrain/workflow-canvas/blob/main/app/workflows/[workflowId]/layout.tsx): nested layout · Per-workflow route shell and state boundary · `app/workflows/[workflowId]/layout.tsx`
- [Workflow API](https://github.com/pascobrain/workflow-canvas/blob/main/app/api/workflows/route.ts): route handlers · CRUD, duplication, code export, webhook binding, and execution history · `app/api/workflows/route.ts`
- [Run API](https://github.com/pascobrain/workflow-canvas/blob/main/app/api/workflow/[workflowId]/execute/route.ts): execution route · Workflow execution trigger and execution-status/log access · `app/api/workflow/[workflowId]/execute/route.ts`
- [AI API](https://github.com/pascobrain/workflow-canvas/blob/main/app/api/ai/generate/route.ts): generation routes · AI generation plus AI Gateway consent, status, and team routes · `app/api/ai/generate/route.ts`
- [Auth API](https://github.com/pascobrain/workflow-canvas/blob/main/app/api/auth/[...all]/route.ts): auth route · Better Auth entrypoint for sessions and identity · `app/api/auth/[...all]/route.ts`
- [Integrations API](https://github.com/pascobrain/workflow-canvas/blob/main/app/api/integrations/route.ts): resource routes · Integration listing, testing, and credential-backed resource management · `app/api/integrations/route.ts`

### Frontend UI

Workflow editor, overlays, and shared components

- [Workflow Editor](https://github.com/pascobrain/workflow-canvas/blob/main/components/workflow/workflow-canvas.tsx): canvas ui · Visual builder for nodes, connections, configuration, and runs · `components/workflow/workflow-canvas.tsx`
- [AI Canvas](https://github.com/pascobrain/workflow-canvas/blob/main/components/ai-elements/canvas.tsx): visual primitives · Specialized canvas and node primitives used by the builder experience · `components/ai-elements/canvas.tsx`
- [Overlays](https://github.com/pascobrain/workflow-canvas/blob/main/components/overlays/overlay-container.tsx): ui overlays · Dialogs, drawers, export, settings, integration, and consent flows · `components/overlays/overlay-container.tsx`
- [UI Shell](https://github.com/pascobrain/workflow-canvas/blob/main/components/ui/button.tsx): shared components · Reusable primitives, auth shell, theme, and global controls · `components/ui/button.tsx`

### Workflow Core

Execution, code generation, and shared step logic

- [Executor](https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-executor.workflow.ts): runtime orchestration · Turns workflow graphs into step execution and persists results · `lib/workflow-executor.workflow.ts`
- [Workflow Store](https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-store.ts): persistence access · Workflow definition and execution state access layer · `lib/workflow-store.ts`
- [Codegen](https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-codegen.ts): typescript generator · Generates executable workflow code with shared step metadata · `lib/workflow-codegen.ts`
- [Step Library](https://github.com/pascobrain/workflow-canvas/blob/main/lib/steps/index.ts): step abstractions · Core trigger, condition, HTTP, database, and credential steps · `lib/steps/index.ts`
- [Logging](https://github.com/pascobrain/workflow-canvas/blob/main/lib/workflow-logging.ts): execution logs · Run logs and execution status recording · `lib/workflow-logging.ts`

### Integrations

Plugin registry and provider packages

- [Plugin Registry](https://github.com/pascobrain/workflow-canvas/blob/main/plugins/registry.ts): discovery layer · Discovers and registers integration packages for the builder and engine · `plugins/registry.ts`
- [Plugins](https://github.com/pascobrain/workflow-canvas/blob/main/plugins/index.ts): integration packages · Provider packages with credentials, icons, steps, and tests · `plugins/index.ts`

### Data & Ops

Database schema, migrations, tests, and deployment tooling

- [DB Schema](https://github.com/pascobrain/workflow-canvas/blob/main/lib/db/schema.ts): drizzle schema · Users, sessions, workflows, executions, logs, and integrations model · `lib/db/schema.ts`
- [Migrations](https://github.com/pascobrain/workflow-canvas/blob/main/drizzle/0000_easy_supernaut.sql): sql migrations · Versioned PostgreSQL schema evolution · `drizzle/0000_easy_supernaut.sql`
- [Auth Layer](https://github.com/pascobrain/workflow-canvas/blob/main/lib/auth.ts): better auth · Auth client, providers, and server configuration · `lib/auth.ts`
- [Ops & Tests](https://github.com/pascobrain/workflow-canvas/blob/main/e2e/workflow.spec.ts): tooling · Playwright e2e, Vercel template, and plugin discovery scripts · `e2e/workflow.spec.ts`

## Connections

- 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
