calendar/packages/features/booking-audit/README.md

Booking Audit System

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 Architecture

Core Tables

1. AuditActor: Stores information about entities that perform actions on bookings. Maintains historical records even after users are deleted.
2. BookingAudit: Stores audit records for all booking-related actions.

Key Design Decisions

AuditActor Table:

• Uses UUID primary keys for distributed system compatibility
• Soft references to User (via userUuid) and Attendee (via attendeeId) without foreign key constraints
• Audit trail persists independently even after users/attendees are deleted
• Unique constraints prevent duplicate audit actors
• Supports actor types: USER, GUEST, ATTENDEE, SYSTEM, APP
• Identity fields (email, phone, name) can be anonymized when source records are deleted

BookingAudit Table:

• Uses UUID v7 primary keys for time-sortable IDs
• bookingUid stored as plain string (no foreign key) to preserve audit trail after booking deletion
• onDelete: Restrict prevents actor deletion if audit records exist
• Explicit timestamp field represents business event time (may differ from createdAt if processed asynchronously)
• operationId required field for correlating audit logs from a single user action across different audit types (BookingAudit, UserAudit, etc.)
• JSON data field stores action-specific contextual data
• Indexed for efficient queries by bookingUid, actorId, timestamp, and operationId

Protecting the Audit Trail:

• Database rejects deletion of AuditActor records with associated BookingAudit records
• When a User is deleted, their AuditActor record persists with userUuid set to null

Actor Types

• USER: Registered Cal.com users
• GUEST: Non-registered users (typically booking guests)
• ATTENDEE: Guests who have an Attendee record associated with a booking
• SYSTEM: Automated system actions

Source and Actor Design Pattern

The booking audit system uses two complementary fields:

Source: The Channel

source identifies how the action was initiated:

• WEBAPP: Cal.com web application
• API_V1: API v1 endpoint
• API_V2: API v2 endpoint
• WEBHOOK: External webhook (e.g., Stripe)
• UNKNOWN: Source cannot be determined

Actor: The Entity

actor identifies who or what performed the action:

• User Actor: Registered Cal.com user
• Guest Actor: Non-registered guest
• Attendee Actor: Attendee associated with a booking
• System Actor: Automated system action (generic or named for specific webhooks/services)

This separation enables clear compliance trails, easier debugging, better analytics, and security by distinguishing user-initiated vs automated actions.

Audit Actions

The system tracks various booking actions including:

• CREATED: Initial booking creation
• RESCHEDULED: Booking time/date changed
• ACCEPTED: Booking request approved
• CANCELLED: Booking cancelled
• REJECTED: Booking request declined
• RESCHEDULE_REQUESTED: Request to reschedule
• ATTENDEE_ADDED: New attendee added
• ATTENDEE_REMOVED: Attendee removed
• REASSIGNMENT: Booking reassigned to different host
• LOCATION_CHANGED: Meeting location updated
• HOST_NO_SHOW_UPDATED: Host no-show status changed
• ATTENDEE_NO_SHOW_UPDATED: Attendee no-show status changed
• SEAT_BOOKED: Seat reserved in group booking
• SEAT_RESCHEDULED: Seat rescheduled in group booking

Data Structure Pattern

Most audit actions track changes using a consistent structure:

• Each field tracks both old and new values: { old: T | null, new: T }
• old: Previous value (null if field didn't exist before)
• new: New value after the change
• Complete before/after state captured in every record

Exception: The CREATED action captures initial booking state at creation using a flat object with initial values.

Schema Versioning

The audit system uses per-action versioning. Each action maintains its own schema version independently.

Benefits:

• Update one action's schema without affecting others
• Old records handled via discriminated unions (no migration required)
• Strongly-typed schemas for input and storage

Storage Structure: Version stored separately from audit data: { version, data: {} }

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 and onDelete: Restrict
2. AuditActor → User: Soft reference (no FK) - nullable to preserve audits after user deletion
3. AuditActor → Attendee: Soft reference (no FK) - nullable to preserve audits after attendee deletion

Indexing Strategy

AuditActor Table:

• Indexed on email, userUuid, attendeeId for fast lookups
• Indexed on pseudonymizedAt for compliance cleanup jobs

BookingAudit Table:

• Indexed on bookingUid (primary query pattern)
• Indexed on actorId (secondary query pattern)
• Indexed on timestamp (time-based sorting and filtering)
• Indexed on operationId (correlating multi-booking operations)

Special Actors

SYSTEM Actor:

• Fixed UUID representing automated actions
• Used for automated status changes, system-generated meeting URLs, scheduled operations
• Single instance across the entire system
• No userUuid, attendeeId, email, or phone

Design Principles

1. Immutability

Audit records are append-only. Once created, they are never modified or deleted. This ensures complete historical accuracy and a tamper-proof audit trail.

2. Historical Preservation

Actor information is preserved even after source records are deleted. AuditActor records persist with anonymized identity fields. The audit trail remains complete and queryable even after user/attendee deletion.

3. Flexibility

The JSON data field provides schema flexibility for action-specific context without database schema changes. Backward compatible with versioning.

4. Traceability

Every action is fully traceable with who (actor), what (action), when (timestamp), and contextual data.

5. Integrity

Database constraints ensure data quality through foreign keys, onDelete: Restrict protection, unique constraints, and strategic indexes.

6. Reality Over Enforcement

The audit system records actual state, not expected state. It captures what actually happened without enforcing business rules:

• Store actual values from the database
• Record all actions, including anomalies
• Business logic layer enforces rules; audit layer records faithfully

Benefits:

• Shows real system behavior including anomalies
• Easier debugging
• No silent failures

7. Compliance & Data Privacy

GDPR & HIPAA Compliance:

• AuditActor records persist with PII fields nullified when users are deleted
• Maintains immutable audit trail as required by HIPAA §164.312(b)
• GDPR Article 17 compliance through anonymization: userUuid, email, phone, name set to null
• Application-level logic handles retention policies

8. Queue Privacy

Zero PII in Queue: The audit system works with third-party queue providers without exposing PII:

• UserActor: Only userUuid is queued
• AttendeeActor: Only attendeeId is queued
• GuestActor: Actor record created before queueing; only actorId is queued

Benefits:

• Safe to use third-party queue providers
• GDPR and HIPAA compliant
• Audit trail remains complete even if queue is compromised

Service Architecture

BookingEventHandlerService is the primary entry point for tracking booking changes. It:

1. Receives booking events from various parts of the application
2. Queues audit tasks via BookingAuditProducerService
3. Handles other side effects such as webhooks and notifications

Queue Payload Structure:

• bookingUid: String identifier for the booking
• actor: ID-only actor object (userUuid, attendeeId, or actorId)
• organizationId: Number (for feature flag checks)
• action: Enum value (e.g., "CREATED", "CANCELLED")
• operationId: Required string for correlating related audit logs
• data: Action-specific data
• timestamp: Number (milliseconds since epoch)
• source: Action source (API_V1, API_V2, WEBAPP, WEBHOOK, UNKNOWN)

BookingAuditTaskConsumer processes audit records:

• Validates queue payload structure
• Resolves actor IDs to AuditActor records
• Routes to appropriate action service for data validation and formatting
• Creates immutable audit records in BookingAudit table

Operation ID

The operationId field correlates audit logs that result from a single user action affecting multiple bookings or across different audit types (BookingAudit, UserAudit, etc.).

Benefits:

• Easy to identify all audits from a single user action
• Track bulk vs individual operations
• Improved debugging and understanding of action scope
• Indexed field for fast lookups

Summary

The Booking Audit System provides a robust, scalable architecture for tracking all booking-related actions:

• 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, UUID v7 for time-sortable IDs
• HIPAA & GDPR Compliant: Immutable audit records, anonymized actors
• Reality-Based Recording: Captures actual state for debugging
• Independent Audit Trail: Persists after booking deletion
• Operation Correlation: Links related audit logs across different audit types

This architecture supports compliance requirements, debugging, analytics, and provides transparency for users and administrators.