TypeScript 10,458 FILES 20 FINDINGS

HOW CAL.COM
ACTUALLY WORKS

Open-source scheduling infrastructure. Conventions, patterns, and architecture extracted from the calcom/cal.com repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Validation: Zod schemas Data: React Query Testing: Vitest. Test utilities in: packages/testing/src/lib/fixtures/fixtures.ts. Styling: Tailwind CSS utility classes. Database: Prisma. Schema/models defined in packages/prisma/schema.prisma. Routing: Route definitions live in: packages/trpc/server/routers, packages/trpc/server/routers/viewer/workflows, packages/trpc/server/routers/viewer/webhook. Add new

WHAT_MATTERS

→
This is a monorepo — check workspace dependencies before modifying shared code
→
Generated files detected — editing them directly will break builds
→
packages/trpc/server/types.ts is a hub file (imported by 172 files) — changes here ripple everywhere
→
Circular import chains detected — avoid adding to these cycles

KEY_FINDINGS

This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.

HIGH

Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern -- don't create a separate test/ directory.

HIGH

Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.

HIGH

40 barrel export files found

Environment variables are documented in .env.example. Copy it to .env.local before running the project.

HIGH

Project strongly prefers named exports over default exports. Use `export function` / `export const`, not `export default`.

HIGH

26 named vs 2 default exports in sampled files

Use Zod schemas for validation. This is the project's standard validation approach.

HIGH

7 files use Zod

Tests use Vitest. Test utilities in: packages/testing/src/lib/fixtures/fixtures.ts.

HIGH

12 test files

Styling uses Tailwind CSS utility classes.

HIGH

12 files

Database access uses Prisma. Schema/models defined in packages/prisma/schema.prisma.

HIGH

19 files

Generated files detected (vitest-mocks/tailwind.generated.css, packages/app-store/video.adapters.generated.ts, packages/app-store/redirect-apps.generated.ts, packages/app-store/payment.services.generated.ts, packages/app-store/crm.apps.generated.ts, ...). Do NOT edit these directly — modify the source/schema they are generated from.

HIGH

14 generated files

Route definitions live in: packages/trpc/server/routers, packages/trpc/server/routers/viewer/workflows, packages/trpc/server/routers/viewer/webhook. Add new endpoints here.

HIGH

3 route directories

Third-party integrations live under packages/app-store/ (zoomvideo, zohocrm, zohocalendar, zoho-bigin, zapier, wordpress, ...). Each integration has its own directory with components, lib, and API code.

HIGH

107 integrations found

Hub files (most depended on): packages/trpc/server/types.ts (imported by 172 files); packages/platform/atoms/lib/http.ts (imported by 72 files); packages/features/di/di.ts (imported by 60 files); packages/app-store/_utils/getAppKeysFromSlug.ts (imported by 53 files); packages/emails/src/renderEmail.ts (imported by 51 files). Changes here have the widest blast radius.

HIGH

Circular import chains detected: bookingScenario.ts → getMockRequestDataForBooking.ts; create-event-type.input.ts → CantHaveRecurrenceAndBookerActiveBookingsLimit.ts; handleMarkNoShow.ts → handleSendingAttendeeNoShowDataToApps.ts. Avoid adding to these cycles.

HIGH

+ 3 MORE FINDINGS (MEDIUM CONFIDENCE)

4 env vars detected. Public (browser-exposed): NEXT_PUBLIC_WEBAPP_URL. Private (server-only): CI, PLAYWRIGHT_HEADLESS, PWDEBUG.

MED

Data fetching uses React Query (useQuery/useMutation). Follow this pattern for new data operations.

MED

6 files

UI components live in: packages/ui, packages/ui/components, packages/trpc/components. Add new components here.

MED

3 component directories

smart_toy USING_AI_TOOLS

→avoid editing generated files — modify the source/schema instead
→check file importance before editing hub files
→follow existing patterns listed in quick reference

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **validation:** Use Zod schemas for validation
- **data fetching:** Data fetching uses React Query (useQuery/useMutation)
- **testing:** Tests use Vitest. Test utilities in: packages/testing/src/lib/fixtures/fixtures.ts.
- **styling:** Styling uses Tailwind CSS utility classes.
- **routing:** Route definitions live in: packages/trpc/server/routers, packages/trpc/server/routers/viewer/workflows, packages/trpc/server/routers/viewer/webhook. Add new endpoints here.
- **components:** UI components live in: packages/ui, packages/ui/components, packages/trpc/components. Add new components here.

## Commands

- **Dev:** `turbo run dev --filter="@calcom/web"`
- **Build:** `turbo run build --filter=@calcom/web...`
- **Test:** `TZ=UTC vitest run`
- **Lint:** `turbo lint`
- **db-deploy:** `turbo run db-deploy`
- **db-seed:** `turbo run db-seed`
- **deploy:** `turbo run deploy`
- **deploy:trigger:prod:** `turbo run deploy:trigger:prod --filter="@calcom/features"`
- **deploy:trigger:staging:** `turbo run deploy:trigger:staging --filter="@calcom/features"`

## Critical Constraints

- **Testing:** Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern -- don't create a separate test/ directory.
- **Critical constraints:** Generated files detected (vitest-mocks/tailwind.generated.css, packages/app-store/video.adapters.generated.ts, packages/app-store/redirect-apps.generated.ts, packages/app-store/payment.services.generated.ts, packages/app-store/crm.apps.generated.ts, ...). Do NOT edit these directly — modify the source/schema they are generated from.
- **Core modules:** Hub files (most depended on): packages/trpc/server/types.ts (imported by 172 files); packages/platform/atoms/lib/http.ts (imported by 72 files); packages/features/di/di.ts (imported by 60 files); packages/app-store/_utils/getAppKeysFromSlug.ts (imported by 53 files); packages/emails/src/renderEmail.ts (imported by 51 files). Changes here have the widest blast radius.
- **Circular dependencies:** Circular import chains detected: bookingScenario.ts → getMockRequestDataForBooking.ts; create-event-type.input.ts → CantHaveRecurrenceAndBookerActiveBookingsLimit.ts; handleMarkNoShow.ts → handleSendingAttendeeNoShowDataToApps.ts. Avoid adding to these cycles.

## Stack

Next.js, Tailwind CSS, TypeScript

## Project Structure

- `scripts/` — Build / utility scripts
- `docs/` — Documentation

## Core Modules (by structural importance)

- `packages/trpc/server/types.ts`
- `packages/features/webhooks/lib/dto/types.ts`
- `packages/features/webhooks/lib/interface/IWebhookRepository.ts`
- `packages/platform/atoms/lib/http.ts`
- `packages/app-store/_utils/getAppKeysFromSlug.ts`

## Conventions & Patterns

- **Project structure:** This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.
- **Import conventions:** Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.
- **Environment:** Environment variables are documented in .env.example. Copy it to .env.local before running the project.
- **Export conventions:** Project strongly prefers named exports over default exports. Use `export function` / `export const`, not `export default`.
- **Dominant patterns:**
  - Use Zod schemas for validation. This is the project's standard validation approach.
  - Tests use Vitest. Test utilities in: packages/testing/src/lib/fixtures/fixtures.ts.
  - Styling uses Tailwind CSS utility classes.
  - Database access uses Prisma. Schema/models defined in packages/prisma/schema.prisma.
  - Route definitions live in: packages/trpc/server/routers, packages/trpc/server/routers/viewer/workflows, packages/trpc/server/routers/viewer/webhook. Add new endpoints here.
  - Third-party integrations live under packages/app-store/ (zoomvideo, zohocrm, zohocalendar, zoho-bigin, zapier, wordpress, ...). Each integration has its own directory with components, lib, and API code.

## Additional Context

- **Environment:** 4 env vars detected. Public (browser-exposed): NEXT_PUBLIC_WEBAPP_URL. Private (server-only): CI, PLAYWRIGHT_HEADLESS, PWDEBUG.
- **Dominant patterns:**
  - Data fetching uses React Query (useQuery/useMutation). Follow this pattern for new data operations.
  - UI components live in: packages/ui, packages/ui/components, packages/trpc/components. Add new components here.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

RELATED_REPOS

NEXT.JS SUPABASE

HOW CAL.COMACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

RELATED_REPOS

HOW CAL.COM
ACTUALLY WORKS