calendar/agents/knowledge-base.md

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:

• free:free
• pro:pro

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.