83 lines
2.4 KiB
Markdown
83 lines
2.4 KiB
Markdown
# Cal.com Development Guide for AI Agents
|
|
|
|
This directory contains comprehensive documentation for AI agents working on the Cal.com codebase.
|
|
|
|
## Quick Navigation
|
|
|
|
- **[Commands](commands.md)** - Build, test, and development commands
|
|
- **[Knowledge Base](knowledge-base.md)** - Knowledge base & best practices
|
|
- **[Architecture Overview](#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 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
|