Activepieces

# MISSION: Scaffold "Activepieces" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Activepieces**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Activepieces
- **What It Does**: Activepieces is an open-source, self-hostable workflow automation platform with a visual flow builder, hundreds of TypeScript integration "pieces", and AI-native features that expose those pieces as MCP servers.
- **Domain & Category**: Workflow Automation & AI Orchestration
- **Production Scale**: 2-5 people
- **Development Mode**: HYBRID
- **Architectural Rationale**: A queue-backed API/worker split on Fastify, PostgreSQL and Redis lets executions scale horizontally, while a typed pieces framework and isolated execution keep community integrations safe to load at runtime.
- **Live Website Reference**: https://www.activepieces.com
- **Source Repository**: https://github.com/activepieces/activepieces
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Node.js, Bun, Turborepo, React, Vite, Tailwind CSS, TanStack Query, Fastify, TypeORM, PostgreSQL, Redis, BullMQ, Socket.IO, Docker, Kubernetes, Vercel AI SDK
- **Primary Language(s)**: TypeScript
- **License of the reference repo**: NOASSERTION
- **Frontend**: React — Single-page flow builder in `packages/web`, routed with `react-router-dom`.; Vite — Builds the web package (`@vitejs/plugin-react`, `vite-plugin-checker`); `web#build` is wired through Turborepo.; Tailwind CSS — Utility styling via `@tailwindcss/vite`, with `class-variance-authority`, `tailwind-merge` and Radix UI primitives.; TanStack Query — Server-state caching plus `@tanstack/react-table`, `react-virtual` and `react-db` for large lists and live collections.; Zustand — Local UI state for the builder alongside `react-hook-form` and `zod` for forms.; React Flow — The visual flow canvas is built on `@xyflow/react`; `@dnd-kit` handles drag-and-drop of steps.; Tiptap — Rich-text and mention editing inside step inputs; CodeMirror powers the code editors.
- **Backend & APIs**: Fastify — HTTP API in `packages/server/api` with `@fastify/swagger`, `rate-limit`, `multipart` and `fastify-type-provider-zod` for typed routes.; Node.js — Runtime for the API, worker and engine containers (`node:24` base image).; isolated-vm — The engine runs user flow code in V8 isolates; the Dockerfile also ships the `isolate` sandbox binary for stronger isolation.; Socket.IO — Realtime channel between API, worker, engine and browser, with `@socket.io/redis-adapter` for multi-instance fan-out.; Vercel AI SDK — AI features use the `ai` package with provider adapters for OpenAI, Anthropic, Google, Azure, Bedrock and OpenRouter.; Model Context Protocol — Pieces are exposed as MCP servers through `@modelcontextprotocol/sdk` in the API and server utils.
- **Data & persistence**: PostgreSQL — Primary database via TypeORM (`pg`); the compose file runs the `pgvector/pgvector` image for embeddings.; TypeORM — Entities and migrations (`db-migration`, `check-migrations` scripts); `typeorm-pglite` and `sqlite3` back lighter local setups.; Redis — Queues, locks (`redlock`) and Socket.IO adapter; `redis-memory-server` provides an embedded Redis for single-container installs.; BullMQ — Job queues for flow runs and scheduled triggers, inspected through `@bull-board/fastify`.; S3 — Optional file and log storage through `@aws-sdk/client-s3` and presigned URLs.
- **Infrastructure & deploy**: Docker — One image (`ghcr.io/activepieces/activepieces`) runs as APP or WORKER via `AP_CONTAINER_TYPE`; a separate `Dockerfile.worker` exists.; Kubernetes — Helm chart and Pulumi program under `deploy/` for cluster installs.; Sentry — Error tracking in both the API (`@sentry/node`) and the web app (`@sentry/react`).; PostHog — Product analytics from the server (`posthog-node`) and the browser (`posthog-js`).
- **Tooling, testing & ops**: Turborepo — Task graph for the Bun workspace (`turbo.json`) with per-package build inputs and pass-through `AP_*` env vars.; Bun — Package manager for the monorepo (`packageManager: bun@1.4.0`, `bun.lock`).; Vitest — Unit tests across core, server and web packages (`test-unit`, `test-api` scripts).; Playwright — End-to-end suites in `packages/tests-e2e`, run for community and enterprise editions in CI.; GitHub Actions — CI, e2e, DAST (OWASP ZAP), benchmark, canary/stage/cloud delivery and rollback workflows.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/activepieces/activepieces @ 70790de)
1. **Integrations are npm packages ("pieces") built on a typed framework**: Every integration lives under `packages/pieces/community/*` or `core/*` and depends on `packages/pieces/framework`. Pieces are published to npm by `release-pieces.yml` and loaded by the server at runtime, which is how a community can contribute connectors without touching the core.
2. **One image, two roles: APP and WORKER**: The compose file runs the same `ghcr.io/activepieces/activepieces` image as an `app` (API + UI) and as `worker` replicas selected by `AP_CONTAINER_TYPE`. Flow executions are queued in BullMQ on Redis and picked up by workers, so capacity scales by adding worker containers.
3. **Flow code executes in isolates, optionally hardened by a sandbox binary**: `packages/server/engine` runs steps with `isolated-vm`, and the Dockerfile compiles the `isolate` sandbox (with `libcap2`) for process-level isolation. `packages/server/sandbox` and the `smoke-test/verify-isolation.sh` script exist specifically to verify these boundaries.
4. **Postgres + Redis are the only required services, with embedded fallbacks**: TypeORM targets PostgreSQL in production, but `typeorm-pglite` (`@electric-sql/pglite`) and `sqlite3` allow database-less trials, and `redis-memory-server` (pinned in the Dockerfile) stands in for Redis when `AP_REDIS_TYPE=MEMORY`.
5. **AI is a first-class subsystem, not a piece**: `packages/core/ai-providers` wraps the Vercel AI SDK with a catalog of providers (OpenAI, Anthropic, Google, Azure, Bedrock, OpenRouter), and the API exposes pieces as MCP servers via `@modelcontextprotocol/sdk`. `sync-model-catalog.yml` keeps the model list current.
6. **Community and enterprise code share one monorepo**: `packages/ee` (for example `ee/embed-sdk`) sits next to the community packages, and CI runs separate `tests-e2e-ce.yml` and `tests-e2e-ee.yml` suites. GitHub reports the repository license as "Other" while the README badge advertises MIT, so check `LICENSE` and the `ee` directory before reusing code.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Vite 6 with TanStack Router for fully type-safe routing. Manage server state and caching via TanStack Query v5 with optimistic UI updates.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (PostgreSQL, TypeORM, Redis, BullMQ, S3): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.