Formbricks

# MISSION: Scaffold "Formbricks" 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 **Formbricks**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Formbricks
- **What It Does**: Formbricks is an open-source survey and experience-management platform: a Next.js/TypeScript monorepo on Prisma and PostgreSQL, with Redis caching, BullMQ jobs, and Authzed/SpiceDB for fine-grained authorization.
- **Domain & Category**: Survey & Feedback SaaS
- **Production Scale**: 2-5 people
- **Development Mode**: AI-AGENT
- **Architectural Rationale**: A pnpm/Turborepo workspace with a shared dependency catalog lets the web app, background jobs, caching, and AI provider config ship as separate packages while a dedicated Authzed service keeps permission logic out of application code.
- **Live Website Reference**: https://formbricks.com
- **Source Repository**: https://github.com/formbricks/formbricks
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Next.js, TypeScript, Prisma, PostgreSQL, Redis, SpiceDB
- **Primary Language(s)**: TypeScript, Shell, JavaScript
- **License of the reference repo**: NOASSERTION
- **Frontend**: Next.js — Serves the dashboard, survey editor, and public survey runtime as one app in apps/web.; Tailwind CSS — Utility-first styling for the shared survey UI components.
- **Backend & APIs**: Better Auth — Session and OAuth authentication for apps/web, replacing the NextAuth/Auth.js setup referenced in the README.; BoxyHQ SAML Jackson — Enterprise SAML/SSO identity provider integration.; Authzed — Zanzibar-style relationship-based authorization service; permission checks run against a committed schema.
- **Data & persistence**: Prisma — ORM and migration tool for the primary database, in a dedicated @formbricks/database package.; PostgreSQL — Primary relational datastore, migrated and queried through Prisma; local dev provisions it via Docker.; Redis — Unified caching layer shared across the web app and background jobs, wrapped in @formbricks/cache.
- **Infrastructure & deploy**: Docker — apps/web ships a production Dockerfile; docker/ compose files and bootstrap scripts stand up Postgres and Authzed for self-hosting.; Helm — Kubernetes deployment ships as a first-class Helm chart, plus a chart for running the SpiceDB/Authzed operator.; GitHub Actions — Runs API contract/spec tests, Docker build and security scans, Helm chart validation, and staged cloud deploys.
- **Tooling, testing & ops**: Vercel AI SDK — Shared AI provider configuration and model resolution (Bedrock, Azure, Vertex) live in @formbricks/ai.; BullMQ — Runs scheduled and background workflow jobs in a dedicated @formbricks/jobs package, over ioredis.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/formbricks/formbricks @ 3387e9d)
1. **Turborepo pnpm workspace with a single dependency version catalog**: pnpm-workspace.yaml scopes the workspace to apps/*, docker, and packages/*, and defines a pnpm catalog (e.g. typescript: 5.9.3) that every workspace references as "catalog:" instead of a literal version; a scripts/check-catalog.mjs check (run by pnpm lint) fails the build if a shared dependency drifts from the catalog or is declared by 2+ packages without a catalog entry.
2. **Fine-grained authorization is delegated to Authzed/SpiceDB, not in-app RBAC**: A committed authzed/schema.zed defines the permission model, apps/web/package.json depends on @authzed/authzed-node, and dedicated scripts (authzed:backfill, authzed:perf, authzed:health, authzed:schema in the root package.json) manage the SpiceDB-based authorization service alongside operational docs in authzed/RUNBOOK.md and authzed/PERFORMANCE.md.
3. **Auth is migrating from NextAuth/Auth.js to Better Auth**: apps/web/package.json depends on @better-auth/core, @better-auth/oauth-provider, and @better-auth/utils, while the README's "Built on Open Source" section still lists Auth.js — the manifest reflects an in-progress migration to Better Auth ahead of the public documentation.
4. **Redis caching is factored into its own shared package**: packages/cache/package.json (@formbricks/cache, described as "Unified Redis cache for Formbricks") depends only on redis and @formbricks/logger, giving apps/web and packages/jobs one shared cache client instead of each implementing its own Redis connection handling.
5. **Background jobs run in a dedicated BullMQ package, separate from the web app**: packages/jobs/package.json (@formbricks/jobs) depends on bullmq and ioredis directly, decoupling scheduled and background workflow execution from the Next.js request/response cycle in apps/web.
6. **Kubernetes deployment ships as a Helm chart with a SpiceDB operator**: The repository tree includes charts/formbricks and charts/spicedb-operator as top-level directories, and a helm-chart-validation.yml GitHub Actions workflow validates them, indicating Helm-based Kubernetes deployment is a first-class, CI-checked deployment target alongside Docker Compose.
7. **AI provider config is centralized to support multiple LLM backends**: packages/ai/package.json (@formbricks/ai, "Shared AI provider configuration and model resolution for Formbricks") depends on @ai-sdk/amazon-bedrock, @ai-sdk/azure, @ai-sdk/google-vertex, and @ai-sdk/openai-compatible together with the Vercel ai package, so AI-backed features are not hard-coded to a single model provider.
---
## 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, Redis): 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.