Skip to content

README.md

Latest commit

 

History

History
83 lines (57 loc) · 2.44 KB

README.md

File metadata and controls

83 lines (57 loc) · 2.44 KB

Cal.com Development Guide for AI Agents

This directory contains comprehensive documentation for AI agents working on the Cal.com codebase.

Quick Navigation

Getting Started

Cal.com is a monorepo using Yarn workspaces and Turbo for build orchestration. The main application is in apps/web/ with shared packages in packages/.

Key Directories

  • apps/web/ - Main Next.js application
  • packages/prisma/ - Database schema and migrations
  • packages/trpc/ - API layer using tRPC
  • packages/ui/ - Shared UI components
  • packages/features/ - Feature-specific code
  • packages/app-store/ - Third-party app integrations

Architecture Overview

Database Layer

  • Prisma ORM with PostgreSQL
  • Schema in packages/prisma/schema.prisma
  • Always use select instead of include for better performance
  • Never expose credential.key field in API responses

API Layer

  • tRPC for type-safe APIs
  • Routers in packages/trpc/server/routers/
  • Authentication handled via NextAuth.js

Frontend

  • Next.js 13+ with App Router in some areas
  • React 18 with TypeScript
  • Tailwind CSS for styling
  • Internationalization with next-i18next

Common Patterns

Error Handling

  • Use early returns to reduce nesting
  • Throw descriptive errors with proper error codes
  • Prefer composition over prop drilling

Performance

  • Avoid O(n²) logic in backend code
  • Minimize Day.js usage in performance-critical paths
  • Use select queries to only fetch needed data
  • Consider using .utc() for Day.js operations

Security

  • Never commit secrets or API keys
  • Always validate input data
  • Use proper authentication checks
  • Never expose sensitive credential fields

Testing Strategy

  • Unit tests with Vitest
  • Integration tests for complex workflows
  • E2E tests with Playwright
  • Test files use .test.ts or .spec.ts extensions

Pull Request Guidelines

For large PRs (>500 lines or >10 files):

  • Split by feature boundaries
  • Separate database migrations, backend logic, frontend components
  • Create dependency chains that can be merged sequentially
  • Pattern: Database → Backend → Frontend → Tests