Knowledge Base - Domain & Product-Specific Information
This file contains domain knowledge about the Cal.diy product and codebase. For coding guidelines and rules, see rules/.
When working with managed event types
When a managed event type is created, we create:
- A parent managed event type for the team (has
teamId set in EventType table)
- A child managed event type for each assigned user (has
userId set in EventType table)
Example: If we create a managed event type and assign Alice and Bob, three rows will be inserted in the EventType table (1 parent + 2 children).
Important: Only child managed event types can be booked.
When working with organizations and teams
Both organizations and teams are stored in the Team table:
- Organizations: Have
isOrganization set to true
- Teams within an organization: Have
parentId set (pointing to the organization)
When working with OAuth clients
There are two types of OAuth clients:
| Type | Table | Purpose |
|---|
| OAuth client | OAuthClient | Allows 3rd party apps to connect users' cal.com accounts |
| Platform OAuth client | PlatformOAuthClient | Used by platform customers integrating cal.com scheduling directly in their platforms |
If someone says "platform OAuth client" they mean the one in the PlatformOAuthClient table.
When you need product or codebase context
Monorepo Structure
The whole repository is a monorepo. The main web app is in apps/web folder.
Local Development Database
When setting up local development database, it creates test users. The passwords are the same as the username:
Logging Levels
Control logging verbosity by setting NEXT_PUBLIC_LOGGER_LEVEL in .env:
- 0: silly
- 1: trace
- 2: debug
- 3: info
- 4: warn
- 5: error
- 6: fatal
Cal.diy Event Identification
Cal.diy events in Google Calendar can be identified by checking if the iCalUID ends with @Cal.diy (e.g., [email protected]). This identifier is used to distinguish Cal.diy bookings from other calendar events for data storage and privacy purposes.
UI Component Locations
- Event types page:
apps/web/modules/event-types/views/event-types-listing-view.tsx
- Bookings page:
apps/web/modules/bookings/views/bookings-view.tsx
- Shared elements (tabs, search bars, filter buttons) should maintain consistent alignment across views
DataTable
Refer to the DataTable guide at packages/features/data-table/GUIDE.md for implementation patterns and best practices.
Round-Robin Scheduling
Reuse existing code in packages/features/bookings/lib/getLuckyUser.ts which handles:
- Weight-based selection
- Priority ranking
- Round-robin fairness algorithms
Check if existing functions can be extended before creating new implementations.
Calendar Cache System
The calendar cache system follows specific patterns in packages/features/calendar-cache-sql. When implementing provider-specific calendar cache services (like for Outlook/Office365), place the provider-specific code in the corresponding provider directory (e.g., packages/app-store/office365calendar).
API Documentation
The OpenAPI specification at docs/api-reference/v2/openapi.json is auto-generated from NestJS controllers. Manual edits will be wiped out.
To make persistent changes to API documentation, use NestJS decorators (@ApiQuery, @ApiOperation, etc.) in the controller files at apps/api/v2/src/modules/*/controllers/*.controller.ts.
Workflows vs Webhooks
Workflows and webhooks are two completely separate features in Cal.diy with different implementations and file structures:
- Workflow constants:
packages/features/ee/workflows/lib/constants.ts
- NOT in the webhooks directory
When working on workflow triggers, do not reference or use webhook trigger implementations - they are distinct systems.