activepieces/activepieces
AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
12 hidden assumptions · 7-stage pipeline · 10 components
Like any codebase, this repository makes assumptions it never checks — most are routine. The ones worth your attention are below.
Orchestrates AI workflows and agent automation through extensible pieces and MCPs
Data flows through distinct pipelines: workflow execution (API→Worker→Engine→Pieces), AI agent interactions (Agent→Tools→LLM→Execution), piece development (CLI→Build→Publish→Registry), and real-time UI updates (Builder→API→Database→WebSocket). Each pipeline maintains strict data contracts and error boundaries.
Under the hood, the system uses 4 feedback loops, 5 data pools, 5 control points to manage its runtime behavior.
A 10-component repository. 10197 files analyzed. Data flows through 7 distinct pipeline stages.
Hidden Assumptions
Most of what this code assumes is routine. These 3 are the ones most likely to cause trouble here. The rest are minor; they're under "Show everything".
Wrong operation handlers execute with mismatched data, causing runtime errors deep in execution flow or producing corrupt results without clear error messages
If AgentPieceTool objects have malformed or missing metadata fields, pieceLoader throws unclear errors during LLM tool construction, causing agent workflows to fail with confusing stack traces
Invalid model names pass validation but cause API failures during agent execution, with errors surfacing only when LLM calls are made, not during configuration
Show everything (9 more)
oauth2Handler assumes OAuth2 tokens stored in AppConnection remain valid throughout piece execution, but doesn't account for token expiration during long-running workflows
If this fails: Multi-step workflows that take longer than OAuth token lifetime (typically 1 hour) will fail mid-execution when pieces attempt to authenticate, requiring manual re-authentication
packages/server/api/src/app/app-connection/app-connection-service/oauth2/index.ts:oauth2Handler
buildPiece assumes sufficient disk space exists for npm pack operation and TypeScript compilation outputs, never checking available disk space before starting build process
If this fails: Large piece compilation fails with 'ENOSPC' errors when disk space is exhausted, leaving partially built artifacts and corrupted build directories that require manual cleanup
packages/cli/src/lib/utils/piece-utils.ts:buildPiece
dataSelectorUtils.traverseStep assumes step output data structures are reasonably sized for frontend rendering, with no limits on nesting depth or object size
If this fails: Workflows with large JSON outputs (megabytes) or deeply nested structures (100+ levels) cause browser memory exhaustion and UI freezing during data selector tree construction
packages/web/src/app/builder/data-selector/utils.ts:dataSelectorUtils.traverseStep
Worker startup assumes API and socket URLs from getApiUrl() and getSocketUrl() are immediately reachable, but doesn't implement retry logic for connection failures during initialization
If this fails: Workers fail to start in environments with slow network initialization or temporary DNS issues, requiring manual restarts rather than automatic recovery
packages/server/worker/src/lib/main.ts:main
Embed SDK assumes parent window implements message handlers for all ActivepiecesClientEventName events, but doesn't validate the parent's readiness to receive events before posting messages
If this fails: Iframe-to-parent communication fails silently when parent application hasn't initialized message listeners, causing authentication flows and navigation events to be lost
packages/ee/embed-sdk/src/index.ts:ActivepiecesClientEventName
Component assumes flowVersion.state and flow.publishedVersionId are always consistent with database state, but doesn't handle race conditions where flow state changes between renders
If this fails: UI shows incorrect flow status when rapid state changes occur (e.g., concurrent publish operations), displaying draft flows as published or vice versa until next page refresh
packages/web/src/app/builder/builder-header/flow-status/index.tsx:BuilderFlowStatusSection
E2E test fixture assumes authentication always succeeds with provided credentials and doesn't handle cases where auth server is unavailable or credentials are invalid
If this fails: All E2E tests fail with unclear 'page not ready' errors when authentication service is down, making it impossible to distinguish between test failures and infrastructure issues
packages/tests-e2e/fixtures/index.ts:page fixture
aiProviders registry assumes each provider name maps to exactly one implementation strategy, with no support for provider versioning or fallback providers when primary provider fails
If this fails: When a specific AI provider (e.g., OpenAI) experiences outages, all agent workflows using that provider fail completely rather than falling back to alternative providers with compatible models
packages/server/api/src/app/ai/providers/index.ts:aiProviders
getDataSelectorStructure assumes step output sample data remains static while building data selector tree, but outputSampleData can change asynchronously as users modify workflow steps
If this fails: Data selector shows outdated or inconsistent variable references when users rapidly modify workflow steps, leading to invalid data mappings that cause runtime errors during flow execution
packages/web/src/app/builder/data-selector/index.tsx:getDataSelectorStructure
Open the standalone hidden-assumptions report for activepieces →
How Data Flows Through the System
Data flows through distinct pipelines: workflow execution (API→Worker→Engine→Pieces), AI agent interactions (Agent→Tools→LLM→Execution), piece development (CLI→Build→Publish→Registry), and real-time UI updates (Builder→API→Database→WebSocket). Each pipeline maintains strict data contracts and error boundaries.
- Workflow Creation — User designs flow in web builder, defining triggers and actions through drag-and-drop interface. FlowVersion objects are created with step definitions, validation occurs client-side, and draft versions are persisted to database [UserInput → FlowVersion]
- Flow Publication — Draft FlowVersion is validated server-side, piece metadata is verified, connections are checked, and version state transitions from DRAFT to LOCKED with publishedVersionId updated on parent Flow [FlowVersion → FlowVersion]
- Execution Trigger — Flow execution initiated by webhook, schedule, or manual trigger. FlowRun record created with RUNNING status, execution context prepared, and job queued for worker processing [TriggerPayload → FlowRun]
- Worker Processing — Background worker dequeues job, loads FlowVersion definition, initializes execution context with project data and connections, then dispatches to execution engine [FlowRun → ExecutionContext]
- Step Execution — Engine processes each step sequentially, loads piece modules dynamically, resolves input properties from previous step outputs, executes piece action with sandboxed context, and captures ExecutionOutput [ExecutionContext → ExecutionOutput]
- AI Agent Processing — When agent piece executes, tools are constructed from available pieces, LLM generates tool calls based on prompt, each tool call resolves to piece execution, and structured output is extracted from agent result [AgentPrompt → AgentResult]
- Result Aggregation — All step ExecutionOutputs are collected into execution journal, FlowRun status updated to SUCCESS or FAILED, duration calculated, and logs persisted to file storage [ExecutionOutput → FlowRun]
Data Models
The data structures that flow between stages — the contracts that hold the system together.
packages/shared/src/lib/automation/flows/flow-version.tsObject with id: string, flowId: string, displayName: string, trigger: Trigger, valid: boolean, state: FlowVersionState (DRAFT|LOCKED), updatedBy: string, created: string, updated: string
Created when flows are modified, locked when published, referenced during execution to determine which version to run
packages/shared/src/lib/automation/flow-run/flow-run.tsObject with id: FlowRunId, projectId: string, flowVersionId: string, status: FlowRunStatus, startTime: string, finishTime?: string, logsFileId?: string, tasks?: number, tags?: string[]
Created when flow execution starts, updated with status changes, archived when complete with execution logs
packages/shared/src/lib/automation/flow-run/execution/execution-output.tsObject with stepName: string, status: StepOutputStatus, input?: unknown, output?: unknown, errorMessage?: string, duration?: number
Generated during each workflow step execution, aggregated into execution journal, persisted for debugging and flow testing
packages/shared/src/lib/automation/app-connection/app-connection.tsObject with id: string, name: string, pieceName: string, type: AppConnectionType, value: AppConnectionValue (OAuth2|BasicAuth|SecretText|CustomAuth), projectId: string
Created during connection setup, refreshed for OAuth tokens, referenced during piece execution for authentication
packages/shared/src/lib/automation/agents/index.tsObject with provider: AIProviderName (OPENAI|ANTHROPIC|GOOGLE|etc), model: string
Configured during agent setup, resolved to specific AI provider during execution, used to route requests to correct LLM
packages/shared/src/lib/automation/pieces/piece-metadata.tsObject with name: string, version: string, displayName: string, description: string, auth?: PieceAuth, actions: Record<string, Action>, triggers: Record<string, Trigger>
Extracted during piece compilation, cached in registry, served to frontend for flow building and validated during execution
packages/shared/src/lib/automation/engine/index.tsUnion type of ExecuteFlowOperation | ExtractPieceMetadataOperation | ExecuteTriggerOperation | ExecuteValidateAuthOperation with type discriminator and operation-specific payload
Created by API or worker, sent to execution engine, processed based on operation type, results returned to caller
System Behavior
How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.
Data Pools
Over 600 compiled piece packages containing action/trigger definitions, each exposing metadata and executable code for workflow integration
Persistent storage for flow definitions, versions, runs, connections, and project data with relational integrity and audit trails
In-memory collection of step execution results during workflow run, later serialized to logs for debugging and audit purposes
Background job queue managing workflow executions, webhook deliveries, and scheduled tasks with retry logic and priority handling
Encrypted storage for OAuth tokens, API keys, and authentication credentials used by pieces during execution
Feedback Loops
- OAuth Token Refresh (refresh-loop, balancing) — Trigger: Expired OAuth token detected during piece execution. Action: OAuth2Handler attempts token refresh using stored refresh token, updates AppConnection with new tokens. Exit: Valid tokens obtained or refresh fails permanently.
- Piece Hot Reload (development-loop, reinforcing) — Trigger: File changes detected in piece source during CLI development mode. Action: CLI rebuilds piece, updates local registry, triggers engine reload of piece metadata. Exit: Development server stopped or build errors occur.
- Agent Tool Execution (recursive, reinforcing) — Trigger: LLM generates tool calls in response to agent prompt. Action: Each tool call executes piece action, result fed back to LLM, potentially triggering more tool calls. Exit: Agent reaches conclusion or max steps limit exceeded.
- Worker Health Check (heartbeat, balancing) — Trigger: Periodic health check timer in worker process. Action: Reports worker status to API, updates last seen timestamp, checks for graceful shutdown signals. Exit: Worker process terminates or health endpoint becomes unavailable.
Delays
- Piece Compilation (build-time, ~5-30 seconds per piece) — TypeScript compilation and npm packaging blocks piece development workflow until build completes
- OAuth Authorization Flow (async-processing, ~User-dependent (seconds to minutes)) — Flow execution waits for user to complete OAuth consent in external provider before connection can be used
- Agent Tool Execution (llm-processing, ~1-10 seconds per tool call) — Each LLM inference adds latency to agent workflow execution, multiplied by number of tool calls required
- Queue Processing (batch-window, ~100ms-5s depending on queue load) — Flow execution may be delayed waiting for available worker or queue processing depending on system load
Control Points
- AI Provider Selection (runtime-toggle) — Controls: Which LLM provider and model is used for agent processing (OpenAI, Anthropic, Google, etc). Default: AgentProviderModel
- Execution Environment (architecture-switch) — Controls: Whether pieces execute in sandboxed Node.js process or isolated container environment. Default: SANDBOXED_NODE
- Worker Concurrency (scaling-parameter) — Controls: Number of concurrent jobs a worker can process simultaneously. Default: process.env.WORKER_CONCURRENCY || 10
- Piece Development Mode (feature-flag) — Controls: Enables hot reload and local piece registry for development vs production piece loading. Default: EngineConstants.DEV_PIECES
- OAuth Provider Config (env-var) — Controls: Client IDs, secrets, and endpoints for OAuth integrations with external services. Default: process.env.OAUTH_*_CLIENT_ID
Technology Stack
Primary language providing type safety across piece development, API contracts, and execution engine
Frontend framework powering visual flow builder with drag-and-drop interfaces and real-time updates
High-performance Node.js API server handling REST endpoints, authentication, and WebSocket connections
Primary database storing flow definitions, execution history, user accounts, and encrypted connection credentials
Background job queue managing workflow execution, webhook delivery, and scheduled tasks with retry logic
Unified interface for multiple LLM providers (OpenAI, Anthropic, Google) enabling agent tool execution
Monorepo build orchestration managing 600+ piece packages with incremental builds and caching
End-to-end testing framework validating workflow execution and UI interactions across browser environments
Key Components
- execute (dispatcher) — Routes engine operations to appropriate handlers based on operation type (flow execution, metadata extraction, trigger hooks, auth validation)
packages/server/engine/src/lib/operations/index.ts - flowExecutor (executor) — Executes workflow steps sequentially, manages step context, handles branching logic, and collects execution outputs in sandboxed environment
packages/server/engine/src/lib/handler/flow-executor.ts - pieceLoader (loader) — Dynamically loads and instantiates piece modules, resolves piece metadata, and manages piece versioning during execution
packages/server/engine/src/lib/helper/piece-loader.ts - aiProviders (registry) — Maps AI provider names to implementation strategies, handles provider-specific authentication, model selection, and request routing
packages/server/api/src/app/ai/providers/index.ts - oauth2Handler (adapter) — Manages OAuth2 flows by routing connection types to appropriate OAuth services (cloud, credentials, or platform-specific)
packages/server/api/src/app/app-connection/app-connection-service/oauth2/index.ts - agentTools (factory) — Converts piece actions into AI agent tools, generates dynamic schemas, and executes tool calls with proper context and error handling
packages/server/engine/src/lib/tools/index.ts - worker (orchestrator) — Manages background job processing, handles flow execution queues, webhook delivery, and scheduled tasks with graceful shutdown
packages/server/worker/src/lib/worker.ts - dataSelectorUtils (processor) — Traverses workflow steps to build data selection tree, extracts available variables, and manages step output references for flow builder
packages/web/src/app/builder/data-selector/utils.ts - pieceUtils (processor) — Handles piece discovery, compilation, packaging, and publishing workflows including TypeScript building and npm package creation
packages/cli/src/lib/utils/piece-utils.ts - ActivepiecesClientEventName (adapter) — Defines event-driven communication protocol between embedded Activepieces iframe and parent application for authentication and navigation
packages/ee/embed-sdk/src/index.ts
Package Structure
Core data models, types, and utilities shared across all services including flow definitions, authentication models, and execution state management
Command-line tool for creating, building, and publishing pieces with hot-reload development support
Execution engine that runs workflow steps, validates piece metadata, and executes AI agent tools in sandboxed environments
React-based visual flow builder with drag-and-drop interface for creating workflows and configuring AI agents
FastifyJS REST API server providing workflow management, authentication, and AI provider integration endpoints
Shared utilities for file system operations, cryptography, database migrations, and system monitoring
Background job processor that executes workflows, handles webhooks, and manages queue-based task scheduling
Embeddable SDK allowing third parties to integrate Activepieces flow builder into their applications
TypeScript framework for building reusable workflow pieces with type-safe property definitions and execution contexts
Shared utilities and helpers used across multiple pieces for common operations like HTTP requests and data transformation
Explore the interactive analysis
See the full architecture map, data flow, and code patterns visualization.
Analyze on CodeSeaRelated Repository Repositories
Frequently Asked Questions
What is activepieces used for?
Orchestrates AI workflows and agent automation through extensible pieces and MCPs activepieces/activepieces is a 10-component repository written in TypeScript. Data flows through 7 distinct pipeline stages. The codebase contains 10197 files.
How is activepieces architected?
activepieces is organized into 5 architecture layers: Frontend Layer, API Layer, Execution Layer, Worker Layer, and 1 more. Data flows through 7 distinct pipeline stages. This layered structure keeps concerns separated and modules independent.
How does data flow through activepieces?
Data moves through 7 stages: Workflow Creation → Flow Publication → Execution Trigger → Worker Processing → Step Execution → .... Data flows through distinct pipelines: workflow execution (API→Worker→Engine→Pieces), AI agent interactions (Agent→Tools→LLM→Execution), piece development (CLI→Build→Publish→Registry), and real-time UI updates (Builder→API→Database→WebSocket). Each pipeline maintains strict data contracts and error boundaries. This pipeline design reflects a complex multi-stage processing system.
What technologies does activepieces use?
The core stack includes TypeScript (Primary language providing type safety across piece development, API contracts, and execution engine), React (Frontend framework powering visual flow builder with drag-and-drop interfaces and real-time updates), Fastify (High-performance Node.js API server handling REST endpoints, authentication, and WebSocket connections), PostgreSQL (Primary database storing flow definitions, execution history, user accounts, and encrypted connection credentials), Redis/Bull (Background job queue managing workflow execution, webhook delivery, and scheduled tasks with retry logic), AI SDK (Unified interface for multiple LLM providers (OpenAI, Anthropic, Google) enabling agent tool execution), and 2 more. A focused set of dependencies that keeps the build manageable.
What system dynamics does activepieces have?
activepieces exhibits 5 data pools (Piece Registry, Flow Database), 4 feedback loops, 5 control points, 4 delays. The feedback loops handle refresh-loop and development-loop. These runtime behaviors shape how the system responds to load, failures, and configuration changes.
What design patterns does activepieces use?
5 design patterns detected: Plugin Architecture, Multi-Role Components, Event-Driven Communication, Execution Isolation, State Machine Workflows.
Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.