Architecture Overview

​

Monorepo Structure

cal.com/
├── apps/
│   ├── web/              # Main Next.js application
│   └── api/              # API applications
│       ├── v1/           # Legacy API (v1)
│       └── v2/           # Platform API (v2)
├── packages/
│   ├── app-store/        # Third-party integrations
│   ├── features/         # Feature-specific code (73 features)
│   ├── prisma/           # Database schema and migrations
│   ├── trpc/             # tRPC API layer
│   ├── ui/               # Shared UI components
│   ├── lib/              # Shared utilities (32 libraries)
│   ├── platform/         # Platform SDK and libraries
│   ├── emails/           # Email templates
│   ├── embeds/           # Embed packages
│   └── i18n/             # Internationalization
└── turbo.json            # Turborepo configuration

​

Key Directories

​

Apps

​

apps/web/

• app/ - App Router pages and layouts
• pages/ - Legacy Pages Router routes
• public/ - Static assets
• components/ - Web-specific components

​

apps/api/v1/

​

apps/api/v2/

​

Packages

​

packages/prisma/

• schema.prisma - Database schema definition
• migrations/ - Database migration files
• seed.ts - Database seeding script

​

packages/trpc/

• server/routers/ - API endpoint definitions
• react/ - React hooks for tRPC

​

packages/features/

• bookings/ - Booking logic
• ee/ - Enterprise features
• auth/ - Authentication
• calendars/ - Calendar integrations
• webhooks/ - Webhook handling

​

packages/app-store/

• Each app has its own directory
• config.json - App configuration
• api/ - API endpoints
• lib/ - Business logic
• components/ - UI components

​

packages/ui/

• Buttons, forms, modals
• Design system primitives
• Tailwind-based styling

​

packages/lib/

• Date/time utilities
• Validation helpers
• Type definitions
• Constants

​

Tech Stack

​

Frontend

• Framework: Next.js 13+ (App Router + Pages Router)
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS
• UI Library: Custom component library (@calcom/ui)
• State Management: React hooks + tRPC
• Forms: React Hook Form
• Internationalization: next-i18next

​

Backend

• API: tRPC for type-safe APIs
• Database: PostgreSQL
• ORM: Prisma
• Authentication: NextAuth.js
• Validation: Zod schemas
• Email: SendGrid, Nodemailer
• SMS: Twilio

​

Testing

• Unit Tests: Vitest
• E2E Tests: Playwright
• Mocking: Prismock (Prisma), vitest-mock-extended

​

Build & Development

• Monorepo: Turborepo
• Package Manager: Yarn (v4.12.0)
• Linting: Biome
• Formatting: Biome
• Type Checking: TypeScript compiler

​

Infrastructure

• Deployment: Vercel, Docker
• CI/CD: GitHub Actions
• Monitoring: Sentry
• Analytics: PostHog
• Rate Limiting: Unkey (optional)

​

Database Architecture

​

Schema Location

packages/prisma/schema.prisma

​

Key Models

• User - User accounts
• Team - Team/organization data
• EventType - Event type configurations
• Booking - Booking records
• Availability - User availability schedules
• Credential - Integration credentials
• Webhook - Webhook configurations
• Payment - Payment records
• Workflow - Automation workflows

​

API Architecture

​

tRPC Routers

// Example router structure
router/
├── viewer/
│   ├── bookings.router.ts
│   ├── eventTypes.router.ts
│   ├── availability.router.ts
│   └── auth.router.ts
└── public/
    └── slots.router.ts

​

Error Handling

• tRPC Routers: Use TRPCError
• Services/Repositories: Use ErrorWithCode
• Always provide descriptive error messages with context

​

Routing

​

App Router (Next.js 13+)

app/
├── (public)/
│   └── [user]/[type]/page.tsx    # Booking page
├── (dashboard)/
│   ├── event-types/page.tsx
│   ├── bookings/page.tsx
│   └── settings/page.tsx
└── api/
    └── trpc/[trpc]/route.ts

​

Pages Router (Legacy)

pages/
├── api/
│   ├── auth/[...nextauth].ts
│   └── trpc/[trpc].ts
└── [user]/[type].tsx              # Legacy booking page

​

Component Organization

​

Shared Components

packages/ui/components/
├── button/
├── form/
├── dialog/
├── tooltip/
└── ...

// Good
import { Button } from "@calcom/ui/components/button";

// Bad - don't use barrel imports
import { Button } from "@calcom/ui";

​

Feature Components

packages/features/<feature>/components/

​

Service Layer

​

Architecture Pattern

Controller (tRPC Router)
  ↓
Service Layer (Business Logic)
  ↓
Repository Layer (Data Access)
  ↓
Database (Prisma)

​

File Naming Conventions

​

Services

// File: MembershipService.ts
export class MembershipService { ... }

// File: HashedLinkService.ts
export class HashedLinkService { ... }

​

Repositories

// File: PrismaAppRepository.ts
export class PrismaAppRepository { ... }

// File: PrismaMembershipRepository.ts
export class PrismaMembershipRepository { ... }

​

Build System (Turborepo)

​

Key Commands

• build - Build all packages and apps
• dev - Start development servers
• lint - Run linters
• type-check - Type check all packages
• test - Run unit tests
• db-migrate - Run database migrations

​

Task Dependencies

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    }
  }
}

​

Configuration Files

​

Key Files

• package.json - Root package configuration
• turbo.json - Turborepo configuration
• tsconfig.json - TypeScript base configuration
• .env.example - Environment variable template
• .env.appStore.example - App Store environment variables
• biome.json - Biome linting/formatting config

​

TypeScript Configuration

• base.json - Base TypeScript config
• nextjs.json - Next.js specific config
• react-library.json - React library config

​

Deployment Architecture

​

Vercel Deployment

• Main app: apps/web
• API routes: Serverless functions
• Static assets: CDN

​

Docker Deployment

docker-compose.yml
├── calcom (web app)
├── database (PostgreSQL)
└── studio (Prisma Studio)

​

Environment Variables

• DATABASE_URL - Database connection
• NEXTAUTH_SECRET - Auth secret
• CALENDSO_ENCRYPTION_KEY - Encryption key
• NEXT_PUBLIC_WEBAPP_URL - Base URL

​

Next Steps

• Learn about Coding Guidelines
• Explore Testing Practices
• Review Development Setup