Typebot

# MISSION: Scaffold "Typebot" 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 **Typebot**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Typebot
- **What It Does**: Typebot is a chatbot builder: a visual editor for designing conversation flows, a separate runtime that serves the chats, and JavaScript and React embed libraries that put them on websites, with results collected per bot.
- **Domain & Category**: Conversational Form Builder
- **Production Scale**: Solo
- **Development Mode**: AI-AGENT
- **Architectural Rationale**: The editor and the chat runtime are separate Next.js apps built from one Dockerfile, so the public chat runtime scales apart from the editor. Bot logic, Forge integration blocks and the Prisma schema live in shared Bun workspace packages that both apps use.
- **Live Website Reference**: https://typebot.io
- **Source Repository**: https://github.com/baptisteArno/typebot.io
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Next.js, React, Tailwind CSS, Prisma, PostgreSQL, MySQL, Redis, Docker, Bun, Nx, Effect, Zod, TanStack Start, Stripe, Vercel AI SDK, Sentry, OpenTelemetry, Playwright, Biome
- **Primary Language(s)**: TypeScript, MDX, CSS, JavaScript, PHP, Shell
- **License of the reference repo**: NOASSERTION
- **Frontend**: Next.js — Next.js 16 runs both the builder (apps/builder) and the chat runtime (apps/viewer) as separate apps.; React — React 19 renders the builder UI; drag and drop on the flow canvas uses @dnd-kit/react.; Tailwind CSS — Tailwind CSS 4 through @tailwindcss/postcss styles the builder.; Zustand — Client state in the builder, with shared-zustand to sync stores across tabs.; TanStack Start — The marketing site (apps/landing-page) is a separate TanStack Start + Vite 8 app with MDX via content-collections.
- **Backend & APIs**: TypeScript — The only application language; every app and package is a Bun workspace written in TypeScript 5.; oRPC — Typed procedures and OpenAPI output for the builder, viewer, bot engine and billing packages.; Effect — Effect 4 (beta) is used across lib, auth, config, emails, prisma and the Bun workflows app.; NextAuth.js — Sign-in for the builder through next-auth 5 (beta) in packages/auth, with Upstash rate limiting.; Vercel AI SDK — packages/ai wraps the ai package (v5) for AI blocks; the openai client is also used directly.; Stripe — Workspace billing in packages/billing and the payment input that chats can collect.
- **Data & persistence**: Prisma — Prisma 7 schema and migrations in packages/prisma, with pg and PlanetScale driver adapters and read replicas.; PostgreSQL — Default database; docker-compose.yml runs postgres:16 and the workflows app reads it through @effect/sql-pg.; MySQL — Supported as an alternative: packages/prisma has a db:generate:mysql script and a PlanetScale adapter.; Redis — Required by both containers in docker-compose.yml; packages/lib connects with ioredis.; MinIO — packages/lib uses the MinIO client to talk to S3-compatible object storage.
- **Infrastructure & deploy**: Docker — One parameterised Dockerfile (ARG SCOPE) builds either the builder or the viewer image from Next.js standalone output.; Bun — Package manager (bun@1.3.9), Docker base layer and the runtime for apps/workflows.; Nx — Nx 22 orchestrates builds and tests with cached esbuild and Vitest targets.; PartyKit — packages/partykit is deployed by its own workflow; the webhook block, builder and viewer use partysocket.; Sentry — Error reporting in the Next.js apps (@sentry/nextjs) and the Bun workflows app (@sentry/bun).; OpenTelemetry — Tracing through the OpenTelemetry Node SDK, @effect/opentelemetry and @orpc/otel in the builder.
- **Tooling, testing & ops**: Playwright — End-to-end tests in packages/playwright and the root tests/ directory.; Vitest — Unit tests (root vitest.config.ts, Nx Vitest targets); packages/config pulls in Testcontainers for Postgres.; Biome — Formatting and linting (biome.json, format-and-lint scripts) instead of ESLint and Prettier.; GitHub Actions — Typecheck, release, npm publishing of the embeds, PartyKit and workflows deploys, and daily/hourly/monthly jobs.; AGENTS.md — Root AGENTS.md and CLAUDE.md plus skills in .agents/skills, .claude/skills and .github/skills guide coding agents.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/baptisteArno/typebot.io @ b19de80)
1. **Builder and viewer are separate Next.js apps and separate containers**: apps/builder is the editor and apps/viewer serves chats. One Dockerfile builds either through ARG SCOPE, and docker-compose.yml runs them as typebot-builder (8080) and typebot-viewer (8081) against the same Postgres and Redis, so the public chat runtime scales and deploys apart from the editor.
2. **Integrations are workspace packages built on the Forge framework**: The root workspaces include packages/forge/* and packages/forge/blocks/*, and apps/viewer depends on @typebot.io/forge and @typebot.io/forge-repository. Each integration block ships as its own package against one framework, and a create-new-block script scaffolds new ones.
3. **Effect 4 runs through the codebase, and background jobs run on Bun**: packages/lib, auth, config, emails, prisma and shared-core all depend on effect 4.0.0-beta. apps/workflows is a Bun program (@effect/platform-bun, @effect/sql-pg) with its own Dockerfile and deploy-workflows.yml, and daily, hourly and monthly workflows schedule recurring jobs.
4. **One Prisma schema serves PostgreSQL or MySQL**: packages/prisma ships @prisma/adapter-pg and @prisma/adapter-planetscale, a db:generate:mysql script and @prisma/extension-read-replicas, so self-hosters can use Postgres while the same code also runs on MySQL-compatible PlanetScale.
5. **PartyKit is a separately deployed realtime service**: packages/partykit holds the PartyKit server and deploy-partykit.yml ships it on its own. partysocket is a dependency of packages/blocks/webhook, apps/builder and apps/viewer, so realtime traffic goes through PartyKit instead of the Next.js servers.
6. **The repository is set up for coding agents**: The root has AGENTS.md and CLAUDE.md, skills under .agents/skills, .claude/skills and .github/skills, and Codex and Zed config, plus a plans/ directory (plans/biome-off-rules-plan.md) and a setup-worktree script for parallel work.
---
## 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 Next.js 15 App Router: default to React Server Components (RSC) for data fetching. Handle mutations through Server Actions with Zod validation. Keep 'use client' directives restricted strictly to interactive leaf components.
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 (Prisma, PostgreSQL, MySQL, Redis, MinIO): 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.