41b71d845c
* docs: add ErrorWithCode vs TRPCError guidelines and packages/features import restrictions Co-Authored-By: [email protected] <[email protected]> * fix: correct ErrorWithCode syntax with proper imports and Factory pattern Co-Authored-By: [email protected] <[email protected]> * docs: update AGENTS.md with ErrorWithCode guidance for non-tRPC files Co-Authored-By: [email protected] <[email protected]> * docs: reduce duplication by linking to knowledge-base.md for error handling details Co-Authored-By: [email protected] <[email protected]> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Cal.com Development Guide for AI Agents
This directory contains comprehensive documentation for AI agents working on the Cal.com codebase.
Quick Navigation
- Commands - Build, test, and development commands
- Knowledge Base - Knowledge base & best practices
- Architecture Overview - System structure and patterns
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 applicationpackages/prisma/- Database schema and migrationspackages/trpc/- API layer using tRPCpackages/ui/- Shared UI componentspackages/features/- Feature-specific codepackages/app-store/- Third-party app integrations
Architecture Overview
Database Layer
- Prisma ORM with PostgreSQL
- Schema in
packages/prisma/schema.prisma - Always use
selectinstead ofincludefor better performance - Never expose
credential.keyfield 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
selectqueries 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.tsor.spec.tsextensions
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