Cal.com

# MISSION: Scaffold "Cal.com" 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 **Cal.com**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Cal.com
- **What It Does**: Cal.com is an open-source scheduling infrastructure platform: a Next.js/React booking app and app-store of calendar, video, and payment integrations, backed by a separate NestJS Platform API for programmatic access.
- **Domain & Category**: Scheduling SaaS
- **Production Scale**: 6-20 people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Splitting the tRPC-based web app from an independently versioned NestJS Platform API lets Cal.com serve both its own product and third-party developers from one monorepo, while Turborepo and per-integration app-store packages keep dozens of calendar/payment providers buildable and testable in isolation.
- **Live Website Reference**: https://cal.com
- **Source Repository**: https://github.com/calcom/cal.com
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Next.js, React, PostgreSQL, Prisma, tRPC, NestJS, Tailwind CSS, Turborepo, BullMQ, Redis, Docker
- **Primary Language(s)**: TypeScript, CSS, HTML
- **License of the reference repo**: MIT
- **Frontend**: Next.js — Powers the main booking web app in apps/web, built and started via next build / next start.; React — Component model for the web app and the embeddable booking widgets in packages/embeds.; Tailwind CSS — Utility CSS used across the web app and shared UI packages, referenced by the repo topics.; tRPC — Typed client-server API calls between the Next.js app and its backend, defined in packages/trpc.
- **Backend & APIs**: NestJS — Framework for the standalone Platform API (apps/api/v2), separate from the Next.js app.; tRPC — Server-side procedures backing the web app, built with the @calcom/trpc workspace package.; BullMQ — Redis-backed job queue used by the Platform API via @nestjs/bull for async/background work.; Prisma — ORM and migration tool for the shared @calcom/prisma package used by both the web app and API v2.
- **Data & persistence**: PostgreSQL — Primary relational database, referenced directly in docker-compose.yml and required by the Dockerfile build args.; Redis — Used for caching and as the BullMQ queue backend, wired into docker-compose.yml for local development.; Kysely — Typed SQL query builder used by the shared @calcom/kysely workspace package alongside Prisma.
- **Infrastructure & deploy**: Turborepo — Orchestrates builds, tests, and dev servers across the yarn workspace monorepo.; Docker — Multi-stage Dockerfile builds a standalone Next.js production image for self-hosting.; GitHub Actions — Runs the extensive CI matrix: type checks, unit/e2e/embed tests, bundle analysis, and Docker release builds.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/calcom/cal.com @ 6bc4529)
1. **A single Yarn/Turborepo monorepo houses the web app, API, and app-store integrations**: The root package.json workspaces field lists apps/*, apps/api/*, packages/*, packages/app-store, packages/app-store/*, and example-apps/*, and turbo.json defines the shared build/test/dev pipeline across all of them.
2. **The Platform API is a separate NestJS service, not part of the Next.js app**: apps/api/v2/package.json builds with nest build and depends on @nestjs/common, @nestjs/core, and @nestjs/swagger, giving Cal.com a documented, independently deployable REST API distinct from the tRPC procedures used internally by apps/web.
3. **Two ORMs coexist: Prisma for the main schema, Kysely for typed raw queries**: packages/prisma is the schema-of-record used across the monorepo (referenced from apps/api/v2/package.json), while packages/kysely/package.json adds kysely and pg directly, giving performance-sensitive code paths a typed query builder without going through the Prisma client.
4. **Each of the ~30+ calendar/payment/video integrations ships as its own workspace package**: packages/app-store/* contains one package.json per integration (for example packages/app-store/applecalendar, packages/app-store/dailyvideo, packages/app-store/btcpayserver), each independently versioned and built through packages/app-store-cli.
5. **The self-hosted Docker image is built as a Next.js standalone production bundle**: The root Dockerfile prunes the workspace with npx turbo prune --scope=@calcom/web --scope=@calcom/trpc --docker, builds the tRPC and embed packages first, then runs the Next.js build with BUILD_STANDALONE=true before a second minimal runtime stage.
6. **Background jobs on the Platform API run through BullMQ on Redis**: apps/api/v2/package.json depends on @nestjs/bull and @nest-lab/throttler-storage-redis, giving the NestJS API both a Redis-backed job queue and Redis-backed rate limiting.
7. **The open-source Docker distribution is a separate product line, cal.diy**: docker-compose.yml pulls the image calcom.docker.scarf.sh/calcom/cal.diy and app.json (the Heroku one-click deploy manifest) is titled "Cal.diy", distinguishing the self-hosted Docker/Heroku path from the hosted cal.com service.
---
## 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 (PostgreSQL, Redis, Kysely): 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.