# mastra-ai/workflow-builder-template architecture

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

- Interactive diagram: https://gitdiagram.com/mastra-ai/workflow-builder-template
- Repository: https://github.com/mastra-ai/workflow-builder-template

## Overview

1. **Top-level application shape**
   - This is a **Next.js App Router** project. The main user-facing experience lives under `app/`, with workflow list/detail pages and a canvas-based workflow editor.
   - The server boundary is the set of `app/api/**/route.ts` handlers, which expose the platform’s CRUD, execution, auth, and AI functionality.

2. **Primary product surfaces**
   - `app/page.tsx` and `app/workflows/**` are the core UI entry points.
   - The workflow detail page is where a user edits a workflow, configures nodes, and reviews runs/logs.
   - The rest of the UI is assembled from reusable `components/` modules, especially the workflow editor and settings dialogs.

3. **Workflow builder UI subsystem**
   - `components/workflow/` contains the visual editor: canvas, node rendering, toolbar, context menus, run history, and configuration panels.
   - `components/ai-elements/` appears to be a specialized visual layer for AI-assisted flow construction.
   - This front-end layer is the “authoring” boundary: it captures a graph-like workflow definition and sends it to the API for persistence or execution.

4. **Workflow domain and persistence**
   - Workflow definitions, executions, and logs are stored in PostgreSQL via Drizzle (`lib/db/`, `drizzle/`).
   - The schema is centered around users, workflows, execution history, and execution log records.
   - `lib/workflow-store.ts` and related helpers likely encapsulate read/write access to workflow records and state transitions.

5. **Execution subsystem**
   - Workflow execution is handled through the `app/api/workflows/[workflowId]/execute` route and the execution-related endpoints under `app/api/workflows/executions/**`.
   - The core execution logic is split across `lib/workflow-executor.*`, `lib/steps/`, and `lib/mastra/**`, indicating a runtime that can interpret compiled workflows and run step handlers with logging.
   - `workflow-log` endpoints suggest execution events are persisted and later queried for detailed run inspection.

6. **Code generation pipeline**
   - Workflows can be converted into executable TypeScript via the `app/api/workflows/[workflowId]/code` route and the `lib/workflow-codegen*.ts` modules.
   - The generated code uses a `"use workflow"` directive and maps visual nodes to real TypeScript functions.
   - This is a key architecture boundary: the visual graph is not just stored data; it can be compiled into deployable workflow code.

7. **AI-assisted workflow creation**
   - `app/api/ai/generate` and `app/api/ai/generate-code` expose AI-based generation features.
   - `lib/mastra/agents/*` and `lib/codegen-templates/*` support prompt-to-workflow or prompt-to-code generation.
   - The README indicates OpenAI-backed generation via an AI Gateway key, so the system can synthesize workflow definitions and code from natural language.

8. **Integration/plugin system**
   - `plugins/` is a major subsystem: each integration has its own `index.ts`, credentials definition, icon, test harness, and step implementations.
   - Examples include Slack, Resend, Linear, Stripe, GitHub, Firecrawl, Perplexity, Blob, fal.ai, Superagent, AI Gateway, and v0.
   - `plugins/registry.ts` and `plugins/legacy-mappings.ts` imply a discovered, registry-driven integration model rather than hardcoded actions.

9. **Step execution model**
   - `lib/steps/` and `plugins/*/steps/` define the runnable units attached to workflow nodes.
   - The system distinguishes common internal steps such as trigger, condition, database query, HTTP request, and credentials handling from plugin-specific actions.
   - This separation is important for architecture diagrams: the workflow engine invokes step handlers, while plugins supply integration-specific behavior and configuration schemas.

10. **Authentication and user/account management**
    - Authentication is handled through Better Auth, exposed at `app/api/auth/[...all]`.
    - User data is surfaced through `app/api/user/route.ts`, and account/settings UI lives under `components/settings/` and `components/auth/`.
    - Auth is a platform boundary: it gates workflow storage, execution history, and integration credentials.

11. **Integration credential and settings management**
    - Integration CRUD and test endpoints live in `app/api/integrations/**`.
    - `lib/integrations-store.ts`, `lib/credential-fetcher.ts`, and `lib/auth-client.ts` suggest a secure server-side path for storing, resolving, and testing credentials.
    - The settings UI manages connection setup, database settings, and per-integration configuration.

12. **Generated runtime templates and packaging**
    - `lib/mastra-boilerplate/` and `lib/next-boilerplate/` are embedded templates used to generate or ship runnable code artifacts.
    - `app/api/workflows/[workflowId]/download` and the code generation flow likely package workflow code into these boilerplates.
    - This means the repo supports not only editing/executing workflows in-app, but also exporting them as standalone projects.

13. **Infrastructure and deployment assumptions**
    - The app is designed for **Vercel deployment** with **PostgreSQL/Neon** and environment-based configuration.
    - `docker-compose.yml`, Drizzle migrations, and the Vercel template reinforce a deployment model where the app server is stateless and data lives in Postgres.
    - `next.config.ts`, `pnpm-lock.yaml`, and `biome.jsonc` indicate a TypeScript-first, tightly controlled build/tooling setup.

14. **External service boundaries**
    - The platform integrates with external APIs through plugins and generic HTTP/database steps, but the integrations are abstracted behind the workflow engine.
    - In architecture terms, external systems are not embedded into the app UI directly; they are invoked as workflow nodes or step handlers with credentials resolved at runtime.

15. **Overall data flow**
    - A user creates or edits a workflow in the visual editor → the workflow graph is saved to Postgres → the workflow can be executed directly, converted to TypeScript, or generated from AI prompts → execution produces runs and logs → those results are queried back into the UI.
    - This repo is therefore both a **workflow authoring platform** and a **workflow runtime/codegen platform**, with the database as the central system of record.

Main entry points: [`app/workflows/[workflowId]/page.tsx`](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/workflows/[workflowId]/page.tsx) (Workflow editor), [`plugins/registry.ts`](https://github.com/mastra-ai/workflow-builder-template/blob/main/plugins/registry.ts) (Plugin registry), [`lib/workflow-codegen.ts`](https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/workflow-codegen.ts) (Codegen), [`app/api/workflows/route.ts`](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflows/route.ts) (Workflow API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI surfaces"]
  node_app_page["Home<br/>Next.js page<br/>[page.tsx]"]
  node_app_workflows_list["Workflow list<br/>Next.js page<br/>[page.tsx]"]
  node_app_workflow_detail["Workflow editor<br/>Next.js page<br/>[page.tsx]"]
  node_workflow_canvas["Canvas"]
  node_node_config["Node config<br/>Editor panel"]
  node_run_history["Run history<br/>Workflow panel<br/>[workflow-runs.tsx]"]
  node_ai_canvas["AI canvas<br/>AI editor<br/>[canvas.tsx]"]
  node_settings_ui["Settings<br/>[index.tsx]"]
end

subgraph group_api["API boundary"]
  node_auth_route["Auth<br/>API route<br/>[route.ts]"]
  node_workflow_api["Workflow API<br/>API routes<br/>[route.ts]"]
  node_workflow_item_api["Workflow item<br/>API route<br/>[route.ts]"]
  node_execute_api["Execute workflow<br/>API route<br/>[route.ts]"]
  node_code_api["Code export<br/>API route<br/>[route.ts]"]
  node_ai_generate_api["AI generate<br/>API route<br/>[route.ts]"]
  node_ai_codegen_api["AI codegen<br/>API route<br/>[route.ts]"]
  node_integration_api["Integrations API<br/>API routes<br/>[route.ts]"]
end

subgraph group_runtime["Workflow runtime"]
  node_workflow_executor{{"Executor<br/>Runtime"}}
  node_step_handlers["Steps<br/>Step handlers<br/>[index.ts]"]
  node_workflow_compiler{{"Compiler"}}
end

subgraph group_domain["Domain data"]
  node_workflow_store[("Workflow store<br/>Persistence layer<br/>[workflow-store.ts]")]
  node_db_schema[("DB schema<br/>Drizzle schema<br/>[schema.ts]")]
end

subgraph group_integrations["Integrations"]
  node_plugins_registry[("Plugin registry<br/>Integration registry<br/>[registry.ts]")]
  node_plugin_steps["Plugin steps<br/>Integration actions"]
end

subgraph group_templates["Templates and AI"]
  node_workflow_codegen{{"Codegen<br/>Code generation"}}
  node_workflow_generator["Workflow gen<br/>AI agent"]
end

node_app_page -->|"navigate"| node_app_workflows_list
node_app_workflows_list -->|"open"| node_app_workflow_detail
node_app_workflow_detail -->|"renders"| node_workflow_canvas
node_app_workflow_detail -->|"renders"| node_node_config
node_app_workflow_detail -->|"renders"| node_run_history
node_app_workflow_detail -->|"uses"| node_settings_ui
node_workflow_canvas -->|"save/load"| node_workflow_api
node_node_config -->|"update"| node_workflow_api
node_run_history -->|"inspect"| node_execute_api
node_auth_route -->|"gates"| node_workflow_api
node_auth_route -->|"gates"| node_integration_api
node_workflow_api -->|"reads/writes"| node_workflow_store
node_workflow_store -->|"persists"| node_db_schema
node_execute_api -->|"starts"| node_workflow_executor
node_workflow_executor -->|"runs"| node_step_handlers
node_workflow_executor -->|"resolves steps"| node_plugins_registry
node_step_handlers -->|"uses"| node_plugins_registry
node_plugin_steps -->|"registers"| node_plugins_registry
node_code_api -->|"generates"| node_workflow_codegen
node_workflow_codegen -->|"compiles"| node_workflow_compiler
node_ai_generate_api -->|"invokes"| node_workflow_generator
node_ai_codegen_api -->|"invokes"| node_workflow_codegen
node_workflow_generator -->|"samples"| node_plugins_registry
node_workflow_codegen -->|"reads model"| node_db_schema
node_integration_api -->|"manages"| node_plugins_registry
node_settings_ui -->|"configures"| node_integration_api
node_ai_canvas -->|"assists"| node_ai_generate_api

click node_app_page "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/page.tsx"
click node_app_workflows_list "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/workflows/page.tsx"
click node_app_workflow_detail "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/workflows/[workflowId]/page.tsx"
click node_workflow_canvas "https://github.com/mastra-ai/workflow-builder-template/blob/main/components/workflow/workflow-canvas.tsx"
click node_node_config "https://github.com/mastra-ai/workflow-builder-template/blob/main/components/workflow/node-config-panel.tsx"
click node_run_history "https://github.com/mastra-ai/workflow-builder-template/blob/main/components/workflow/workflow-runs.tsx"
click node_ai_canvas "https://github.com/mastra-ai/workflow-builder-template/blob/main/components/ai-elements/canvas.tsx"
click node_auth_route "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/auth/[...all]/route.ts"
click node_workflow_api "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflows/route.ts"
click node_workflow_item_api "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflows/[workflowId]/route.ts"
click node_execute_api "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflow/[workflowId]/execute/route.ts"
click node_code_api "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflows/[workflowId]/code/route.ts"
click node_ai_generate_api "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/ai/generate/route.ts"
click node_ai_codegen_api "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/ai/generate-code/route.ts"
click node_integration_api "https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/integrations/route.ts"
click node_workflow_store "https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/workflow-store.ts"
click node_db_schema "https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/db/schema.ts"
click node_workflow_executor "https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/workflow-executor.workflow.ts"
click node_step_handlers "https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/steps/index.ts"
click node_workflow_compiler "https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/mastra/workflow-compiler.ts"
click node_workflow_codegen "https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/workflow-codegen.ts"
click node_workflow_generator "https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/mastra/agents/workflow-generator.ts"
click node_plugins_registry "https://github.com/mastra-ai/workflow-builder-template/blob/main/plugins/registry.ts"
click node_plugin_steps "https://github.com/mastra-ai/workflow-builder-template/blob/main/plugins/slack/steps/send-slack-message.ts"
click node_settings_ui "https://github.com/mastra-ai/workflow-builder-template/blob/main/components/settings/index.tsx"

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_page,node_app_workflows_list,node_app_workflow_detail,node_workflow_canvas,node_node_config,node_run_history,node_ai_canvas,node_settings_ui toneBlue
class node_auth_route,node_workflow_api,node_workflow_item_api,node_execute_api,node_code_api,node_ai_generate_api,node_ai_codegen_api,node_integration_api toneAmber
class node_workflow_executor,node_step_handlers,node_workflow_compiler toneMint
class node_workflow_store,node_db_schema toneRose
class node_plugins_registry,node_plugin_steps toneIndigo
class node_workflow_codegen,node_workflow_generator toneTeal
```

## Components

### UI surfaces

Next.js pages and reusable workflow/settings components.

- [Home](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/page.tsx): Next.js page · Top-level landing page for the product. · `app/page.tsx`
- [Workflow list](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/workflows/page.tsx): Next.js page · Lists workflows and leads into the editor. · `app/workflows/page.tsx`
- [Workflow editor](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/workflows/[workflowId]/page.tsx): Next.js page · Primary workflow authoring and inspection surface. · `app/workflows/[workflowId]/page.tsx`
- [Canvas](https://github.com/mastra-ai/workflow-builder-template/blob/main/components/workflow/workflow-canvas.tsx): Editor canvas · Visual graph editor for arranging workflow nodes. · `components/workflow/workflow-canvas.tsx`
- [Node config](https://github.com/mastra-ai/workflow-builder-template/blob/main/components/workflow/node-config-panel.tsx): Editor panel · Configures triggers, actions, and conditions. · `components/workflow/node-config-panel.tsx`
- [Run history](https://github.com/mastra-ai/workflow-builder-template/blob/main/components/workflow/workflow-runs.tsx): Workflow panel · Shows executions and logs inside the editor. · `components/workflow/workflow-runs.tsx`
- [AI canvas](https://github.com/mastra-ai/workflow-builder-template/blob/main/components/ai-elements/canvas.tsx): AI editor · Specialized visual layer for AI-assisted flow construction. · `components/ai-elements/canvas.tsx`
- [Settings](https://github.com/mastra-ai/workflow-builder-template/blob/main/components/settings/index.tsx): Settings UI · Manages account, database, and integration configuration. · `components/settings/index.tsx`

### API boundary

Route handlers for auth, workflows, execution, AI, and integrations.

- [Auth](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/auth/[...all]/route.ts): API route · Better Auth boundary for sign-in and session handling. · `app/api/auth/[...all]/route.ts`
- [Workflow API](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflows/route.ts): API routes · CRUD endpoints for workflow records and current workflow state. · `app/api/workflows/route.ts`
- [Workflow item](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflows/[workflowId]/route.ts): API route · Reads and updates one workflow definition. · `app/api/workflows/[workflowId]/route.ts`
- [Execute workflow](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflow/[workflowId]/execute/route.ts): API route · Starts workflow execution for a selected workflow. · `app/api/workflow/[workflowId]/execute/route.ts`
- [Code export](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/workflows/[workflowId]/code/route.ts): API route · Generates TypeScript and packaged code for a workflow. · `app/api/workflows/[workflowId]/code/route.ts`
- [AI generate](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/ai/generate/route.ts): API route · Creates workflows from natural language prompts. · `app/api/ai/generate/route.ts`
- [AI codegen](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/ai/generate-code/route.ts): API route · Creates executable workflow code from prompts. · `app/api/ai/generate-code/route.ts`
- [Integrations API](https://github.com/mastra-ai/workflow-builder-template/blob/main/app/api/integrations/route.ts): API routes · CRUD and test endpoints for integration connections. · `app/api/integrations/route.ts`

### Workflow runtime

Compilation, execution, and step handling for workflows.

- [Executor](https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/workflow-executor.workflow.ts): Runtime · Shared workflow execution flow and orchestration. · `lib/workflow-executor.workflow.ts`
- [Steps](https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/steps/index.ts): Step handlers · Core trigger, condition, HTTP, database, and credential steps. · `lib/steps/index.ts`
- [Compiler](https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/mastra/workflow-compiler.ts): Workflow compiler · Compiles the visual graph into runnable workflow form. · `lib/mastra/workflow-compiler.ts`

### Domain data

Persistence, schema, and workflow state access.

- [Workflow store](https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/workflow-store.ts): Persistence layer · Server-side access to workflow records and state transitions. · `lib/workflow-store.ts`
- [DB schema](https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/db/schema.ts): Drizzle schema · PostgreSQL schema for users, workflows, executions, and logs. · `lib/db/schema.ts`

### Integrations

Plugin registry and provider-specific step implementations.

- [Plugin registry](https://github.com/mastra-ai/workflow-builder-template/blob/main/plugins/registry.ts): Integration registry · Discovers and resolves integration definitions and mappings. · `plugins/registry.ts`
- [Plugin steps](https://github.com/mastra-ai/workflow-builder-template/blob/main/plugins/slack/steps/send-slack-message.ts): Integration actions · Provider-specific runnable steps for external services. · `plugins/slack/steps/send-slack-message.ts`

### Templates and AI

Code generation templates, boilerplates, and AI agents.

- [Codegen](https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/workflow-codegen.ts): Code generation · Transforms workflows into TypeScript and boilerplate outputs. · `lib/workflow-codegen.ts`
- [Workflow gen](https://github.com/mastra-ai/workflow-builder-template/blob/main/lib/mastra/agents/workflow-generator.ts): AI agent · Prompt-to-workflow generation logic. · `lib/mastra/agents/workflow-generator.ts`

## Connections

- Home → Workflow list: navigate · Primary app flow from landing into workflow management.
- Workflow list → Workflow editor: open · Select a workflow to edit or inspect.
- Workflow editor → Canvas: renders · The detail page is centered on the visual editor.
- Workflow editor → Node config: renders · The editor exposes node configuration controls.
- Workflow editor → Run history: renders · The editor shows runs and logs for the workflow.
- Workflow editor → Settings: uses · Editor settings and connection management are reused in the workflow experience.
- Canvas → Workflow API: save/load · Canvas state is persisted and refreshed through workflow APIs.
- Node config → Workflow API: update · Configuration changes are written back through the workflow API.
- Run history → Execute workflow: inspect · Run panels query execution status and logs.
- Auth → Workflow API: gates · Auth protects workflow CRUD and current-workflow access.
- Auth → Integrations API: gates · Auth protects integration management.
- Workflow API → Workflow store: reads/writes · Workflow handlers delegate persistence to the store layer.
- Workflow store → DB schema: persists · Workflow state is stored through the database schema.
- Execute workflow → Executor: starts · Execution routes invoke the runtime executor.
- Executor → Steps: runs · The executor dispatches work to step handlers.
- Executor → Plugin registry: resolves steps · Runtime looks up plugin-provided actions and credentials.
- Steps → Plugin registry: uses · Core steps and plugin steps are unified through the registry.
- Plugin steps → Plugin registry: registers · Provider actions are exposed through plugin registration.
- Code export → Codegen: generates · Code export uses the workflow codegen pipeline.
- Codegen → Compiler: compiles · Code generation builds on compiled workflow structure.
- AI generate → Workflow gen: invokes · Prompt-driven workflow creation uses AI agents.
- AI codegen → Codegen: invokes · Prompt-driven code generation routes into the codegen pipeline.
- Workflow gen → Plugin registry: samples · Generation is constrained by available integrations and steps.
- Codegen → DB schema: reads model · Generated code reflects persisted workflow and execution data shapes.
- Integrations API → Plugin registry: manages · Integration CRUD is centered on the discovered plugin catalog.
- Settings → Integrations API: configures · Settings screens create, test, and update connections.
- AI canvas → AI generate: assists · AI-assisted authoring can create or reshape workflow graphs.