How mastra-ai/workflow-builder-template works
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: page.tsx Workflow editor · registry.ts Plugin registry · workflow-codegen.ts Codegen · route.ts Workflow API
Components 25
UI surfaces
Next.js pages and reusable workflow/settings components.
- Home · Top-level landing page for the product.
app/page.tsx - Workflow list · Lists workflows and leads into the editor.
app/workflows/page.tsx - Workflow editor · Primary workflow authoring and inspection surface.
app/workflows/[workflowId]/page.tsx - Canvas · Visual graph editor for arranging workflow nodes.
components/workflow/workflow-canvas.tsx - Node config · Configures triggers, actions, and conditions.
components/workflow/node-config-panel.tsx - Run history · Shows executions and logs inside the editor.
components/workflow/workflow-runs.tsx - AI canvas · Specialized visual layer for AI-assisted flow construction.
components/ai-elements/canvas.tsx - Settings · Manages account, database, and integration configuration.
components/settings/index.tsx
API boundary
Route handlers for auth, workflows, execution, AI, and integrations.
- Auth · Better Auth boundary for sign-in and session handling.
app/api/auth/[...all]/route.ts - Workflow API · CRUD endpoints for workflow records and current workflow state.
app/api/workflows/route.ts - Workflow item · Reads and updates one workflow definition.
app/api/workflows/[workflowId]/route.ts - Execute workflow · Starts workflow execution for a selected workflow.
app/api/workflow/[workflowId]/execute/route.ts - Code export · Generates TypeScript and packaged code for a workflow.
app/api/workflows/[workflowId]/code/route.ts - AI generate · Creates workflows from natural language prompts.
app/api/ai/generate/route.ts - AI codegen · Creates executable workflow code from prompts.
app/api/ai/generate-code/route.ts - Integrations API · CRUD and test endpoints for integration connections.
app/api/integrations/route.ts
Workflow runtime
Compilation, execution, and step handling for workflows.
Domain data
Persistence, schema, and workflow state access.
- Workflow store · Server-side access to workflow records and state transitions.
lib/workflow-store.ts - DB schema · PostgreSQL schema for users, workflows, executions, and logs.
lib/db/schema.ts
Integrations
Plugin registry and provider-specific step implementations.
- Plugin registry · Discovers and resolves integration definitions and mappings.
plugins/registry.ts - Plugin steps · 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 · Transforms workflows into TypeScript and boilerplate outputs.
lib/workflow-codegen.ts - Workflow gen · Prompt-to-workflow generation logic.
lib/mastra/agents/workflow-generator.ts
Connections 27
- 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.