Scheduling infrastructure for absolutely everyone.
feat: [Booking Audit Stack - 1] Add Booking Audit System foundation (database schema and repositories) (#24838)
Hariom Balharac04402e7eec0
diff --git a/packages/features/booking-audit/ARCHITECTURE.md b/packages/features/booking-audit/ARCHITECTURE.mdnew file mode 100644index 00000000000..1751bc81964--- /dev/null+++ b/packages/features/booking-audit/ARCHITECTURE.md@@ -0,0 +1,808 @@+# Booking Audit System - Database Architecture+Based on https://github.com/calcom/cal.com/pull/22817++Note: This architecture is not in production yet, so we can make any changes we want to it without worrying about backwards compatibility.++## Overview++The Booking Audit System tracks all actions and changes related to bookings in Cal.com. The architecture is built around two core tables (`AuditActor` and `BookingAudit`) that work together to maintain a complete, immutable audit trail.++## Database Tables++### 1. AuditActor Table++The `AuditActor` table stores information about entities that perform actions on bookings. It maintains historical records even after users are deleted.++```prisma+model AuditActor {+ id String @id @default(uuid())+ type AuditActorType++ // References for different actor types (soft references, no FK constraints)+ userUuid String? @db.Uuid // For USER type (nullable to allow user deletion)+ attendeeId Int? // For ATTENDEE type(nullable to allow attendee deletion)++ // Identity fields - only for GUEST/SYSTEM(System too might not have all) type. Attendee and User maintain their own identity fields.+ // They could be set as anonymized for User/Attendee record as well when they are deleted to preserve the audit trail.+ email String?+ phone String?+ name String?++ createdAt DateTime @default(now())+ bookingAudits BookingAudit[]++ @@unique([userUuid])+ @@unique([attendeeId])+ @@unique([email]) // Prevent duplicate email actors+ @@unique([phone]) // Prevent duplicate phone actors+ @@index([email])+ @@index([userUuid])+ @@index([attendeeId])+ @@index([pseudonymizedAt]) // For compliance cleanup jobs+}+```++**Key Design Decisions:**+- **UUID Primary Key**: Uses UUIDs for distributed system compatibility+- **Soft References**: Both `userUuid` and `attendeeId` are soft references without foreign key constraints, allowing the audit trail to persist independently even after users or attendees are deleted+- **User UUID Reference**: Uses `User.uuid` instead of `User.id` for stable identification across distributed systems+- **Unique Constraints**: Prevents duplicate audit actors for the same user/email/phone+- **Multiple Identity Fields**: Supports different actor types (users, guests, attendees, system)+- **Extensible System Actors**: Architecture supports multiple system actors (e.g., Cron, Webhooks, API integrations, Background Workers) for granular tracking of automated operations+- **Identity Fields for Audit Retention**: Identity fields (email, phone, name) are primarily used for GUEST/SYSTEM actors. For USER and ATTENDEE types, these fields can be anonymized when the source record is deleted to preserve the audit trail while removing PII++---++### 2. BookingAudit Table++The `BookingAudit` table stores audit records for all booking-related actions.++```prisma+model BookingAudit {+ id String @id @default(uuid(7)) @db.Uuid+ // bookingUid is stored as a plain string (not a foreign key relation) to preserve the audit trail+ // even after the booking is deleted. This is intentional for audit log integrity:+ // - Audit logs are immutable historical records that should persist independently+ // - When a booking is deleted, we still need to know which booking the audit log belonged to+ // - Using a plain string instead of a relation prevents bookingUid from becoming NULL on booking deletion+ // - This allows users to view complete audit history for deleted bookings+ bookingUid String++ // Actor who performed the action (USER, GUEST, or SYSTEM)+ // Stored in AuditActor table to maintain audit trail even after user deletion+ actorId String+ // Restrict onDelete to prevent deletion of audit actor if there are any booking audits associated with it+ actor AuditActor @relation(fields: [actorId], references: [id], onDelete: Restrict)++ type BookingAuditType+ action BookingAuditAction++ // Timestamp of the actual booking change (business event time)+ // Important: May differ from createdAt if audit is processed asynchronously+ timestamp DateTime++ // Database record timestamps+ createdAt DateTime @default(now())+ updatedAt DateTime @updatedAt++ data Json?++ @@index([actorId])+ @@index([bookingUid])+}+```++**Key Design Decisions:**+- **UUID v7 Primary Key**: Uses `uuid(7)` for time-sortable IDs, providing chronological ordering and improved database performance+- **No Foreign Key to Booking**: `bookingUid` is stored as a plain string without a foreign key constraint to preserve audit trail integrity even after bookings are deleted+- **Restrict on Delete**: `onDelete: Restrict` prevents actor deletion if audit records exist+- **Required Action**: Every audit record must specify a business action, ensuring explicit tracking of what happened+- **Explicit Timestamp**: The `timestamp` field has no default and must be explicitly provided, representing when the business event actually occurred+- **Separate Database Timestamps**: `createdAt` and `updatedAt` track when the audit record itself was created/modified, distinct from the business event time+- **JSON Data Field**: Flexible schema for storing action-specific contextual data+- **Indexed Fields**: Efficient queries by `bookingUid` and `actorId`+++**Protecting the Audit Trail:**+- **AuditActor Record Deletion Prevention**: The database will reject any attempt to delete an `AuditActor` record that has associated `BookingAudit` records, ensuring audit records never become orphaned+- **User Deletion Unaffected**: When a `User` is deleted from the system, their corresponding `AuditActor` record persists (with `userUuid` set to null), maintaining the complete audit history++++## Enums++### AuditActorType++Defines the type of entity performing an action:++```prisma+enum AuditActorType {+ USER @map("user") // Registered Cal.com user (stored here for audit retention even after user deletion)+ // Considering renaming it to ANONYMOUS to avoid confusion with Guest of a booking+ GUEST @map("guest") // Non-registered user+ ATTENDEE @map("attendee") // Guest who booked (has Attendee record)+ SYSTEM @map("system") // Automated actions+}+```++**Values:**+- **USER**: Registered Cal.com users who perform actions on bookings+- **GUEST**: Non-registered users (typically booking guests)+- **ATTENDEE**: Guests who have an Attendee record associated with a booking+- **SYSTEM**: Automated system actions (scheduled jobs, webhooks, etc.)++---++### BookingAuditType++Defines the category of audit record:++```prisma+enum BookingAuditType {+ RECORD_CREATED @map("record_created")+ RECORD_UPDATED @map("record_updated")+ RECORD_DELETED @map("record_deleted")+}+```++**Usage Pattern:**+- **RECORD_CREATED**: Initial booking creation+- **RECORD_UPDATED**: Any modification to existing booking (most common)+- **RECORD_DELETED**: Permanent deletion (rarely used, as bookings are typically cancelled)++---++### BookingAuditAction++Defines specific actions performed on bookings:++```prisma+enum BookingAuditAction {+ // Booking lifecycle+ CREATED @map("created")++ // Status changes+ CANCELLED @map("cancelled")+ ACCEPTED @map("accepted")+ REJECTED @map("rejected")+ PENDING @map("pending")+ AWAITING_HOST @map("awaiting_host")+ RESCHEDULED @map("rescheduled")++ // Attendee management+ ATTENDEE_ADDED @map("attendee_added")+ ATTENDEE_REMOVED @map("attendee_removed")++ // Assignment/Reassignment+ REASSIGNMENT @map("reassignment")++ // Meeting details+ LOCATION_CHANGED @map("location_changed")++ // No-show tracking+ HOST_NO_SHOW_UPDATED @map("host_no_show_updated")+ ATTENDEE_NO_SHOW_UPDATED @map("attendee_no_show_updated")++ // Rescheduling+ RESCHEDULE_REQUESTED @map("reschedule_requested")+}+```++**Action Categories:**++1. **Booking Lifecycle**: Track creation events+ - `CREATED`++2. **Status Changes**: Track booking lifecycle transitions+ - `CANCELLED`, `ACCEPTED`, `REJECTED`, `PENDING`, `AWAITING_HOST`, `RESCHEDULED`++3. **Attendee Management**: Track changes to booking participants+ - `ATTENDEE_ADDED`, `ATTENDEE_REMOVED`++4. **Assignment/Reassignment**: Track booking host assignment changes+ - `REASSIGNMENT`++5. **Meeting Details**: Track changes to meeting logistics+ - `LOCATION_CHANGED`++6. **No-Show Tracking**: Track attendance issues+ - `HOST_NO_SHOW_UPDATED`, `ATTENDEE_NO_SHOW_UPDATED`++7. **Rescheduling**: Track reschedule requests+ - `RESCHEDULE_REQUESTED`++---++## Schema Structure - Change Tracking++All audit actions follow a consistent structure for tracking changes. This structure ensures complete audit trail coverage by capturing both the old and new values for every tracked field.++### Core Pattern++Each action stores a flat object with all relevant fields. Each field tracks both old and new values:++```typescript+{+ field1: { old: T | null, new: T },+ field2: { old: T | null, new: T },+ field3: { old: T | null, new: T } // Optional fields as needed+}+```++### Change Tracking++**All fields use the same pattern** - `{ old: T | null, new: T }`:+- `old`: The previous value (null if the field didn't exist before)+- `new`: The new value after the change++**Examples:**+```typescript+// Simple field changes+status: { old: "ACCEPTED", new: "CANCELLED" }+location: { old: "Zoom", new: "Google Meet" }++// New fields (old is null)+cancellationReason: { old: null, new: "Client requested" }+```++### Semantic Clarity at Application Layer++**Action Services decide what to display prominently.** Each Action Service has methods like `getDisplayDetails()` that determine:+- Which fields are most important to show by default+- Which fields should be available but not emphasized+- How to format the data for display++This keeps the data structure simple while maintaining semantic clarity where it matters - in the UI.++### Benefits++1. **Complete Audit Trail**: Full before/after state captured for every change+2. **Self-Contained Records**: Each record has complete context without querying previous records+3. **Simple Structure**: Flat object, easy to work with and extend+4. **Better UI**: Action Services decide what to emphasize based on user needs+5. **State Reconstruction**: Can rebuild booking state at any point in the audit timeline+6. **Easier Debugging**: See exact state transitions in each record+7. **Type Safety**: Zod schemas validate the structure while keeping it flexible++### Examples by Action++#### Simple Action+```typescript+// LOCATION_CHANGED+{+ location: { old: "Zoom", new: "Google Meet" }+}+```++#### Action with Multiple Fields+```typescript+// CANCELLED+{+ cancellationReason: { old: null, new: "Client requested" },+ cancelledBy: { old: null, new: "[email protected]" },+ status: { old: "ACCEPTED", new: "CANCELLED" }+}+```++---++## JSON Data Schemas by Action++The `BookingAudit.data` field stores action-specific context. Each action has its own schema defined in a dedicated Action Helper Service using Zod validation.++### Booking Lifecycle Actions++#### CREATED+Used when a booking is initially created. Records the complete state at creation time.++```typescript+{+ startTime: string // ISO 8601 timestamp+ endTime: string // ISO 8601 timestamp+ status: BookingStatus // Actual booking status (any value from BookingStatus enum)+}+```++**Design Decision:** The `status` field accepts any `BookingStatus` value, not just the expected creation statuses (ACCEPTED, PENDING, AWAITING_HOST). This follows the principle of capturing reality rather than enforcing business rules in the audit layer. If a booking is ever created with an unexpected status due to a bug, we want to record that fact for debugging purposes rather than silently skip the audit record.++**Note:** The CREATED action is unique - it captures the initial booking state at creation, so it doesn't use the `{ old, new }` tracking pattern. It's a flat object with just the initial values: `{ startTime, endTime, status }`.++---++### Status Change Actions++#### ACCEPTED+Used when a booking status changes to accepted.++```typescript+{+ status // { old: "PENDING", new: "ACCEPTED" }+}+```++#### CANCELLED+```typescript+{+ cancellationReason, // { old: null, new: "Client requested" }+ cancelledBy, // { old: null, new: "[email protected]" }+ status // { old: "ACCEPTED", new: "CANCELLED" }+}+```++#### REJECTED+```typescript+{+ rejectionReason, // { old: null, new: "Does not meet requirements" }+ status // { old: "PENDING", new: "REJECTED" }+}+```++#### RESCHEDULED+```typescript+{+ startTime, // { old: "2024-01-15T10:00:00Z", new: "2024-01-16T14:00:00Z" }+ endTime // { old: "2024-01-15T11:00:00Z", new: "2024-01-16T15:00:00Z" }+}+```++#### RESCHEDULE_REQUESTED+```typescript+{+ cancellationReason, // { old: null, new: "Need to reschedule" }+ cancelledBy, // { old: null, new: "[email protected]" }+ rescheduled? // { old: false, new: true } - optional+}+```++---++### Attendee Management Actions++#### ATTENDEE_ADDED+```typescript+{+ addedAttendees // { old: null, new: ["[email protected]", ...] }+}+```++Tracks attendee(s) that were added in this action. Old value is null since we're tracking the delta, not full state.++#### ATTENDEE_REMOVED+```typescript+{+ removedAttendees // { old: null, new: ["[email protected]", ...] }+}+```++Tracks attendee(s) that were removed in this action. Old value is null since we're tracking the delta, not full state.++---++### Assignment/Reassignment Actions++#### REASSIGNMENT+```typescript+{+ assignedToId, // { old: 123, new: 456 }+ assignedById, // { old: 789, new: 789 }+ reassignmentReason, // { old: null, new: "Coverage needed" }+ userPrimaryEmail?, // { old: "[email protected]", new: "[email protected]" } - optional+ title? // { old: "Meeting with A", new: "Meeting with B" } - optional+}+```++---++### Meeting Details Actions++#### LOCATION_CHANGED+```typescript+{+ location // { old: "Zoom", new: "Google Meet" }+}+```++---++### No-Show Tracking Actions++#### HOST_NO_SHOW_UPDATED+```typescript+{+ noShowHost // { old: false, new: true }+}+```++#### ATTENDEE_NO_SHOW_UPDATED+```typescript+{+ noShowAttendee // { old: false, new: true }+}+```++---++**Important Notes:**+- Each schema is strictly typed and validated using the corresponding Action Helper Service+- Actor information is **NOT** stored in the JSON data - it's captured through the `actorId` relation linking to the `Actor` table+- All action schemas are defined in `/packages/features/booking-audit/lib/actions/`++---++### Supporting Schemas++#### Change Tracking Pattern++**All changes use the `{ old, new }` pattern:**++Each field tracks both old and new values:+```typescript+fieldName: {+ old: T | null, // Previous value (null if field didn't exist)+ new: T // New value+}+```++**Benefits:**+- Complete before/after state in every record+- Self-contained audit entries (no need to query previous records)+- Clear state transitions+- Easier debugging and UI display+- Simple flat structure that's easy to work with++---++## Table Relationships++```+AuditActor (1) ──────< (many) BookingAudit+ ↑+ │ (soft reference, no FK)+ ├──────────── User (via userUuid)+ │ (soft reference, no FK)+ └──────────── Attendee (via attendeeId)+```++**Relationship Details:**++1. **AuditActor → BookingAudit**: One-to-Many (with FK constraint)+ - Each AuditActor can have multiple audit records+ - Each BookingAudit references exactly one AuditActor+ - `onDelete: Restrict` prevents AuditActor deletion if audits exist++2. **AuditActor → User**: Soft Reference (no FK constraint)+ - `userUuid` references `User.uuid` but without foreign key constraint+ - Nullable to preserve audits after user deletion+ - Unique constraint ensures one AuditActor per User UUID+ - Audit trail persists independently of user lifecycle++3. **AuditActor → Attendee**: Soft Reference (no FK constraint)+ - `attendeeId` references `Attendee.id` but without foreign key constraint+ - Links guest actors to their booking attendee records+ - Nullable to preserve audits after attendee deletion+ - Unique constraint ensures one AuditActor per Attendee+ - Audit trail persists independently of attendee lifecycle++---++## Indexing Strategy++### AuditActor Table Indexes++```prisma+@@index([email]) // Fast lookups by guest email+@@index([userUuid]) // Fast lookups by user UUID+@@index([attendeeId]) // Fast lookups by attendee ID+```++**Query Patterns:**+- Find all actions by a user (via UUID)+- Find all actions by a guest email+- Find all actions by an attendee++---++### BookingAudit Table Indexes++```prisma+@@index([bookingId]) // Primary query pattern+@@index([actorId]) // Secondary query pattern+```++**Query Patterns:**+- **bookingId**: "Show me all audits for this booking" (most common)+- **actorId**: "Show me all actions by this actor"++---++## Special Actors++### SYSTEM Actor++The system actor represents automated actions and has a fixed UUID:++```typescript+const SYSTEM_ACTOR_ID = "00000000-0000-0000-0000-000000000000";+```++**Used For:**+- Automated status changes+- System-generated meeting URLs+- Scheduled operations (cron jobs)+- Webhook-triggered actions+- Any action not directly initiated by a user or guest++**Properties:**+- Type: `ActorType.SYSTEM`+- No userUuid, attendeeId, email, or phone+- Single instance across the entire system++---++## Schema Version Management++The audit system uses **per-action versioning** rather than global versioning. Each `BookingAuditAction` maintains its own schema version independently.++### Why Per-Action Versioning?++Different actions have different data requirements:+- `CANCELLED` needs `cancellationReason`+- `RESCHEDULED` needs new `startTime` and `endTime`+- `ATTENDEE_ADDED` needs `attendee` information+- `REASSIGNMENT` needs assignment context++When we update the schema for one action, we don't want to affect other actions.++### Implementation Approach++Each action has a dedicated Action Service that manages its own versioning independently. The service defines:++1. **Schema Definition**: Zod schemas for data validation+2. **Schema Version**: Each action maintains its own VERSION constant+3. **Nested Structure**: Version stored separately from audit data: `{ version, data: {} }`+4. **Type Separation**: Distinct types for input (no version) and stored format (with version)+5. **Validation**: Type-safe validation of audit data+6. **Display Logic**: How to render the audit record in the UI++**Example Action Services:**+- `CreatedAuditActionService` → Handles `CREATED` action+- `CancelledAuditActionService` → Handles `CANCELLED` action+- `RescheduledAuditActionService` → Handles `RESCHEDULED` action+- `ReassignmentAuditActionService` → Handles `REASSIGNMENT` action++### Version Storage Structure++Audit data is stored with a nested structure that separates version metadata from actual audit data:++```typescript+{+ version: 1,+ data: {+ cancellationReason: { old: null, new: "Client requested" },+ cancelledBy: { old: null, new: "[email protected]" },+ status: { old: "ACCEPTED", new: "CANCELLED" }+ }+}+```++**Benefits of Nested Structure:**+- Clear separation between metadata (version) and actual audit data+- Makes it easy to extract just the data fields for display+- Version handling is transparent to end users+- Schema evolution is self-documenting++**Key Points:**+- Callers pass unversioned data (just the fields)+- `parse()` automatically wraps input with version before storing+- `parseStored()` validates stored data including version+- Display methods receive full stored record but only show data fields+- Type system enforces correct usage (input vs stored types)++### Benefits of Per-Action Versioning++- **Independent Evolution**: Update one action's schema without affecting others+- **Explicit Changes**: Version increments are tied to specific business operations+- **No Migration Required**: Old records handled via discriminated unions+- **Clear History**: Can track schema changes per action type over time+- **Type Safety**: Each action has strongly-typed schemas for input and storage+- **Caller Simplicity**: Callers don't need to know about versioning+- **Display Isolation**: Version handling is internal to Action Services+++When adding a new version (e.g., v2 with a new field):++**Migration Steps:**+1. Create `dataSchemaV2` with new fields+2. Create `schemaV2` with `version: z.literal(2)`+3. Update `schema` to discriminated union supporting both v1 and v2+4. Update `VERSION` constant to 2+5. Update `parse()` to use v2 schema+6. Update display methods to handle both versions+7. No changes needed to callers or database++---++## Design Principles++### 1. Immutability+Audit records are append-only. Once created, they are never modified or deleted. This ensures:+- Complete historical accuracy+- Tamper-proof audit trail+- Compliance with audit requirements++### 2. Historical Preservation+Actor information is preserved even after source records are deleted:+- User deletion doesn't remove AuditActor records - they persist with anonymized identity fields+- AuditActor table maintains historical records by nullifying PII fields (email, phone, name) when source records are deleted+- Audit trail remains complete and queryable even after user/attendee deletion++### 3. Flexibility+The JSON `data` field provides schema flexibility:+- Action-specific context without database schema changes+- Easy addition of new fields for future actions+- Backward compatible with versioning++### 4. Traceability+Every action is fully traceable:+- Who: Actor with type and identity+- What: Type and Action enums+- When: Explicit timestamp+- Why/How: Contextual data in JSON field++### 5. Integrity+Database constraints ensure data quality:+- Foreign key constraints prevent orphaned records+- `onDelete: Restrict` protects audit integrity+- Unique constraints prevent duplicate actors+- Indexes ensure query performance++### 6. Reality Over Enforcement+**The audit system records actual state, not expected state.**++The audit system is designed to capture what actually happened, not to enforce business rules:++- **Store Actual Values**: When recording state (e.g., booking status at creation), store the actual value from the database without validation or filtering+- **No Type Guards for State**: Avoid conditionally creating audit records based on whether the state matches expectations+- **Bug Detection**: If a booking is created with an unexpected status, record it—this becomes valuable debugging information+- **Single Source of Truth**: Let the business logic layer enforce rules; the audit layer's job is faithful recording++**Example:**+```typescript+// ❌ BAD: Enforcing expected values+if (booking.status === 'ACCEPTED' || booking.status === 'PENDING' || booking.status === 'AWAITING_HOST') {+ // Only audit if status is "expected"+ await auditService.onBookingCreated(...);+}++// ✅ GOOD: Recording actual state+await auditService.onBookingCreated(bookingId, userUuid, {+ startTime: booking.startTime.toISOString(),+ endTime: booking.endTime.toISOString(),+ status: booking.status // Whatever it actually is+});+```++**Benefits:**+- Audit trail shows real system behavior, including anomalies+- Easier to debug issues (incomplete audits hide problems)+- Schemas naturally evolve with business requirements+- No silent failures where audits are skipped++**When to Validate:**+- Validate data structure (required fields, types) ✅+- Do NOT validate business logic (expected values, state transitions) ❌++---++## 7. Compliance & Data Privacy++**GDPR & HIPAA Compliance:**+- **AuditActor records are NOT deleted on user deletion** - Instead, AuditActor records persist with PII fields nullified to preserve the immutable audit trail as required by HIPAA §164.312(b)+- **Cal.com's HIPAA compliance** requires audit records to remain immutable and tamper-proof. The AuditActor table design ensures BookingAudit records are never modified, only the referenced AuditActor record has its PII fields anonymized+- **GDPR Article 17 compliance** is achieved through anonymization: When a user/guest requests deletion, set `userUuid=null`, `email=null`, `phone=null`, `name=null` on the AuditActor record+- **Retention Policy**: Application-level logic should handle retention policies and full anonymization after required retention periods++**Implementation Pattern:**+```typescript+// On user deletion: Anonymize PII, don't delete the actor record+await prisma.auditActor.update({+ where: { userUuid: deletedUserUuid },+ data: {+ userUuid: null,+ email: null,+ phone: null,+ name: null,+ pseudonymizedAt: new Date(),+ scheduledDeletionDate: new Date(Date.now() + 7 * 365 * 24 * 60 * 60 * 1000)+ }+});+// Result: All BookingAudit records reference pseudonymized actor - audit trail preserved, immutable+```++---++## Service Layer++### BookingEventHandlerService - Entry Point++`BookingEventHandlerService` is the primary entry point for tracking any booking changes. It acts as a coordinator that:++1. **Receives booking events** from various parts of the application (booking creation, status changes, updates, etc.)+2. **Relays to BookingAuditService** to create audit records+3. **Handles other side effects** such as webhooks, notifications, and workflow triggers+++### BookingAuditService++The audit system is accessed through `BookingAuditService`, which provides:++### Convenience Methods++- `onBookingCreated()` - Track booking creation+- `onBookingAccepted()` - Track acceptance+- `onBookingRejected()` - Track rejection+- `onBookingCancelled()` - Track cancellation+- `onBookingRescheduled()` - Track reschedule+- `onAttendeeAdded()` - Track attendee addition+- `onAttendeeRemoved()` - Track attendee removal+- `onLocationChanged()` - Track location changes+- `onHostNoShowUpdated()` - Track host no-show+- `onAttendeeNoShowUpdated()` - Track attendee no-show+- `onReassignment()` - Track booking reassignment+- `onRescheduleRequested()` - Track reschedule requests++### Actor Management++- `getOrCreateUserActor()` - Ensures User actors exist before creating audits+- Automatic AuditActor creation/lookup for registered users+- System actor for automated actions++### Future: Trigger.dev Task Orchestration++**Current Flow (Synchronous):**+```+Booking Endpoint → BookingEventHandler.onBookingCreated() → await auditService, linkService, webhookService+```++**Future Flow (Async with Trigger.dev):**+```+Booking Endpoint+ ↓+BookingEventHandler.onBookingCreated() [orchestrator]+ ├─ tasks.trigger('bookingAudit', { bookingId, userUuid, data })+ ├─ tasks.trigger('invalidateHashedLink', { bookingId, hashedLink })+ ├─ tasks.trigger('sendNotifications', { bookingId, email, sms })+ ├─ tasks.trigger('triggerWorkflows', { bookingId, event: 'NEW_EVENT' })+ └─ Immediately returns to user (non-blocking)++Trigger.dev Queue+ ├─ Task: Booking Audit (with retries, monitoring)+ ├─ Task: Hashed Link Invalidation (independent)+ ├─ Task: Email & SMS Notifications (independent)+ └─ Task: Workflow Triggers (independent)+```++**Key Principles:**+- **BookingEventHandler remains the single orchestrator** - Entry point for all side effects+- **Each task is independent** - One task failure doesn't block others+- **Persistent queue** - Trigger.dev handles retries, monitoring, and observability+- **Easy to add features** - New side effect = new task definition, no BookingEventHandler complexity+- **Immutable audit records** - Booking audit is just one of many tasks, preserving the immutability principle++---++## Summary++The Booking Audit System provides a robust, scalable architecture for tracking all booking-related actions. Key features include:++- ✅ **Complete Audit Trail**: Every action tracked with full context+- ✅ **Historical Preservation**: Data retained even after deletions through PII anonymization+- ✅ **Flexible Schema**: JSON data supports evolution without migrations+- ✅ **Strong Integrity**: Database constraints ensure data quality+- ✅ **Performance**: Strategic indexes for common query patterns, UUID v7 for time-sortable IDs+- ✅ **HIPAA & GDPR Compliant**: Immutable audit records, anonymized actors, compliance-ready+- ✅ **Reality-Based Recording**: Captures actual state, aiding in debugging and analysis+- ✅ **Independent Audit Trail**: No foreign key to bookings ensures audit history persists after booking deletion++This architecture supports compliance requirements (HIPAA §164.312(b), GDPR Article 17), debugging, analytics, and provides transparency for both users and administrators.+diff --git a/packages/features/booking-audit/lib/repository/IAuditActorRepository.ts b/packages/features/booking-audit/lib/repository/IAuditActorRepository.tsnew file mode 100644index 00000000000..51ff14ec295--- /dev/null+++ b/packages/features/booking-audit/lib/repository/IAuditActorRepository.ts@@ -0,0 +1,17 @@+export type AuditActorType = "USER" | "GUEST" | "ATTENDEE" | "SYSTEM";++type AuditActor = {+ id: string;+ type: AuditActorType;+ userUuid: string | null;+ attendeeId: number | null;+ email: string | null;+ phone: string | null;+ name: string | null;+ createdAt: Date;+}+export interface IAuditActorRepository {+ findByUserUuid(userUuid: string): Promise<AuditActor | null>;+ findSystemActorOrThrow(): Promise<AuditActor>;+}+diff --git a/packages/features/booking-audit/lib/repository/IBookingAuditRepository.ts b/packages/features/booking-audit/lib/repository/IBookingAuditRepository.tsnew file mode 100644index 00000000000..d75d6c7e5a1--- /dev/null+++ b/packages/features/booking-audit/lib/repository/IBookingAuditRepository.ts@@ -0,0 +1,28 @@+export type BookingAuditType = "RECORD_CREATED" | "RECORD_UPDATED" | "RECORD_DELETED"+export type BookingAuditAction = "CREATED" | "CANCELLED" | "ACCEPTED" | "REJECTED" | "PENDING" | "AWAITING_HOST" | "RESCHEDULED" | "ATTENDEE_ADDED" | "ATTENDEE_REMOVED" | "CANCELLATION_REASON_UPDATED" | "REJECTION_REASON_UPDATED" | "ASSIGNMENT_REASON_UPDATED" | "REASSIGNMENT_REASON_UPDATED" | "LOCATION_CHANGED" | "HOST_NO_SHOW_UPDATED" | "ATTENDEE_NO_SHOW_UPDATED" | "RESCHEDULE_REQUESTED"+export type BookingAuditCreateInput = {+ bookingUid: string;+ actorId: string;+ action: BookingAuditAction;+ data: unknown;+ createdAt: Date;+ type: BookingAuditType;+ timestamp: Date;+}++type BookingAudit = {+ id: string;+ bookingUid: string;+ actorId: string;+ action: string;+ data: unknown;+ createdAt: Date;+}++export interface IBookingAuditRepository {+ /**+ * Creates a new booking audit record+ */+ create(bookingAudit: BookingAuditCreateInput): Promise<BookingAudit>;+}+diff --git a/packages/features/booking-audit/lib/repository/PrismaAuditActorRepository.ts b/packages/features/booking-audit/lib/repository/PrismaAuditActorRepository.tsnew file mode 100644index 00000000000..f2718b904d5--- /dev/null+++ b/packages/features/booking-audit/lib/repository/PrismaAuditActorRepository.ts@@ -0,0 +1,29 @@+import type { PrismaClient } from "@calcom/prisma/client";+import type { IAuditActorRepository } from "./IAuditActorRepository";++const SYSTEM_ACTOR_ID = "00000000-0000-0000-0000-000000000000";++type Dependencies = {+ prismaClient: PrismaClient;+}+export class PrismaAuditActorRepository implements IAuditActorRepository {+ constructor(private readonly deps: Dependencies) { }+ async findByUserUuid(userUuid: string) {+ return this.deps.prismaClient.auditActor.findUnique({+ where: { userUuid },+ });+ }++ async findSystemActorOrThrow() {+ const actor = await this.deps.prismaClient.auditActor.findUnique({+ where: { id: SYSTEM_ACTOR_ID },+ });++ if (!actor) {+ throw new Error("System actor not found");+ }++ return actor;+ }+}+diff --git a/packages/features/booking-audit/lib/repository/PrismaBookingAuditRepository.ts b/packages/features/booking-audit/lib/repository/PrismaBookingAuditRepository.tsnew file mode 100644index 00000000000..7a1c29b22b0--- /dev/null+++ b/packages/features/booking-audit/lib/repository/PrismaBookingAuditRepository.ts@@ -0,0 +1,17 @@+import type { PrismaClient } from "@calcom/prisma";++import type { IBookingAuditRepository, BookingAuditCreateInput } from "./IBookingAuditRepository";++type Dependencies = {+ prismaClient: PrismaClient;+}+export class PrismaBookingAuditRepository implements IBookingAuditRepository {+ constructor(private readonly deps: Dependencies) { }++ async create(bookingAudit: BookingAuditCreateInput) {+ return this.deps.prismaClient.bookingAudit.create({+ data: bookingAudit,+ });+ }+}+diff --git a/packages/prisma/migrations/20251115043236_add_audit_booking/migration.sql b/packages/prisma/migrations/20251115043236_add_audit_booking/migration.sqlnew file mode 100644index 00000000000..70633dd858c--- /dev/null+++ b/packages/prisma/migrations/20251115043236_add_audit_booking/migration.sql@@ -0,0 +1,70 @@+-- CreateEnum+CREATE TYPE "public"."BookingAuditType" AS ENUM ('record_created', 'record_updated', 'record_deleted');++-- CreateEnum+CREATE TYPE "public"."BookingAuditAction" AS ENUM ('created', 'cancelled', 'accepted', 'rejected', 'pending', 'awaiting_host', 'rescheduled', 'attendee_added', 'attendee_removed', 'reassignment', 'location_changed', 'host_no_show_updated', 'attendee_no_show_updated', 'reschedule_requested');++-- CreateEnum+CREATE TYPE "public"."AuditActorType" AS ENUM ('user', 'guest', 'attendee', 'system');++-- CreateTable+CREATE TABLE "public"."AuditActor" (+ "id" TEXT NOT NULL,+ "type" "public"."AuditActorType" NOT NULL,+ "userUuid" UUID,+ "attendeeId" INTEGER,+ "email" TEXT,+ "phone" TEXT,+ "name" TEXT,+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,++ CONSTRAINT "AuditActor_pkey" PRIMARY KEY ("id")+);++-- CreateTable+CREATE TABLE "public"."BookingAudit" (+ "id" UUID NOT NULL,+ "bookingUid" TEXT NOT NULL,+ "actorId" TEXT NOT NULL,+ "type" "public"."BookingAuditType" NOT NULL,+ "action" "public"."BookingAuditAction" NOT NULL,+ "timestamp" TIMESTAMP(3) NOT NULL,+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,+ "updatedAt" TIMESTAMP(3) NOT NULL,+ "data" JSONB,++ CONSTRAINT "BookingAudit_pkey" PRIMARY KEY ("id")+);++-- CreateIndex+CREATE INDEX "AuditActor_email_idx" ON "public"."AuditActor"("email");++-- CreateIndex+CREATE INDEX "AuditActor_userUuid_idx" ON "public"."AuditActor"("userUuid");++-- CreateIndex+CREATE INDEX "AuditActor_attendeeId_idx" ON "public"."AuditActor"("attendeeId");++-- CreateIndex+CREATE UNIQUE INDEX "AuditActor_userUuid_key" ON "public"."AuditActor"("userUuid");++-- CreateIndex+CREATE UNIQUE INDEX "AuditActor_attendeeId_key" ON "public"."AuditActor"("attendeeId");++-- CreateIndex+CREATE UNIQUE INDEX "AuditActor_email_key" ON "public"."AuditActor"("email");++-- CreateIndex+CREATE UNIQUE INDEX "AuditActor_phone_key" ON "public"."AuditActor"("phone");++-- CreateIndex+CREATE INDEX "BookingAudit_actorId_idx" ON "public"."BookingAudit"("actorId");++-- CreateIndex+CREATE INDEX "BookingAudit_bookingUid_idx" ON "public"."BookingAudit"("bookingUid");++-- CreateIndex+CREATE INDEX "BookingAudit_timestamp_idx" ON "public"."BookingAudit"("timestamp");++-- AddForeignKey+ALTER TABLE "public"."BookingAudit" ADD CONSTRAINT "BookingAudit_actorId_fkey" FOREIGN KEY ("actorId") REFERENCES "public"."AuditActor"("id") ON DELETE RESTRICT ON UPDATE CASCADE;diff --git a/packages/prisma/migrations/20251115054502_insert_system_actor/migration.sql b/packages/prisma/migrations/20251115054502_insert_system_actor/migration.sqlnew file mode 100644index 00000000000..e0c96276d4a--- /dev/null+++ b/packages/prisma/migrations/20251115054502_insert_system_actor/migration.sql@@ -0,0 +1,23 @@+-- Insert system actor with predefined UUID+-- This actor is used for system-initiated booking actions+INSERT INTO "AuditActor" (+ id,+ type,+ "userUuid",+ "attendeeId",+ email,+ phone,+ name,+ "createdAt"+)+VALUES (+ '00000000-0000-0000-0000-000000000000',+ 'system',+ NULL,+ NULL,+ NULL,+ NULL,+ 'System',+ NOW()+)+ON CONFLICT (id) DO NOTHING;diff --git a/packages/prisma/schema.prisma b/packages/prisma/schema.prismaindex 4aaacf584fc..6b70715756a 100644--- a/packages/prisma/schema.prisma+++ b/packages/prisma/schema.prisma@@ -2627,6 +2627,113 @@ model RolePermission {@@index([action])}+enum BookingAuditType {+ RECORD_CREATED @map("record_created")+ RECORD_UPDATED @map("record_updated")+ RECORD_DELETED @map("record_deleted")+}++enum BookingAuditAction {+ // Booking lifecycle+ CREATED @map("created")++ // Status changes+ CANCELLED @map("cancelled")+ ACCEPTED @map("accepted")+ REJECTED @map("rejected")+ PENDING @map("pending")+ AWAITING_HOST @map("awaiting_host")+ RESCHEDULED @map("rescheduled")++ // Attendee management+ ATTENDEE_ADDED @map("attendee_added")+ ATTENDEE_REMOVED @map("attendee_removed")++ // Assignment/Reassignment (keep integration version - simpler)+ REASSIGNMENT @map("reassignment")++ // Meeting details+ LOCATION_CHANGED @map("location_changed")++ // No-show tracking+ HOST_NO_SHOW_UPDATED @map("host_no_show_updated")+ ATTENDEE_NO_SHOW_UPDATED @map("attendee_no_show_updated")++ // Rescheduling+ RESCHEDULE_REQUESTED @map("reschedule_requested")+}++enum AuditActorType {+ USER @map("user") // Registered Cal.com user (stored here for audit retention even after user deletion)+ GUEST @map("guest") // Non-registered user+ ATTENDEE @map("attendee") // Has Attendee record with us+ SYSTEM @map("system") // Automated actions+}++model AuditActor {+ id String @id @default(uuid())+ type AuditActorType++ // References for different actor types (soft references, no FK constraints)+ // These fields intentionally do NOT have foreign key constraints to preserve audit trail integrity:+ // - When a User or Attendee is deleted, their AuditActor record persists with these IDs intact+ // - This maintains immutable audit history even after source records are removed+ userUuid String? @db.Uuid // For USER type - references User.uuid without FK constraint+ attendeeId Int? // For ATTENDEE type - references Attendee.id without FK constraint++ // Identity fields - only for GUEST/SYSTEM(System too might not have all) type. Attendee and User maintain their own identity fields.+ // They could be set as anonymized for User/Attendee record as well when they are deleted to preserve the audit trail.+ email String?+ phone String?+ name String?++ createdAt DateTime @default(now())+ bookingAudits BookingAudit[]++ // TODO: Add pseudonymizedAt and related fields when we anonymize the data on deletion+ @@unique([userUuid])+ @@unique([attendeeId])+ @@unique([email]) // Prevent duplicate email actors+ @@unique([phone]) // Prevent duplicate phone actors+ @@index([email])+ @@index([userUuid])+ @@index([attendeeId])+}++model BookingAudit {+ id String @id @default(uuid(7)) @db.Uuid+ // bookingUid is stored as a plain string (not a foreign key relation) to preserve the audit trail+ // even after the booking is deleted. This is intentional for audit log integrity:+ // - Audit logs are immutable historical records that should persist independently+ // - When a booking is deleted, we still need to know which booking the audit log belonged to+ // - Using a plain string instead of a relation prevents bookingUid from becoming NULL on booking deletion+ // - This allows users to view complete audit history for deleted bookings+ bookingUid String++ // Actor who performed the action (USER, GUEST, or SYSTEM)+ // Stored in AuditActor table to maintain audit trail even after user deletion+ actorId String+ // Restrict onDelete to prevent deletion of audit actor if there are any booking audits associated with it+ actor AuditActor @relation(fields: [actorId], references: [id], onDelete: Restrict)++ type BookingAuditType+ action BookingAuditAction++ // Timestamp of the actual booking change (business event time)+ // Important: May differ from createdAt if audit is processed asynchronously+ timestamp DateTime++ // Database record timestamps+ createdAt DateTime @default(now())+ updatedAt DateTime @updatedAt++ data Json?++ @@index([actorId])+ @@index([bookingUid])+ @@index([timestamp])+}+enum PhoneNumberSubscriptionStatus {ACTIVEPAST_DUE