Files
cal.diy/packages/features/booking-audit
5993889616 feat: make impersonatedByUserUuid required across booking audit flows (#26546)
* Integrate creation/rescheduling booking audit

* fix: add missing hostUserUuid to booking audit test data

Co-Authored-By: [email protected] <[email protected]>

* fix-ci

* feat: enhance booking audit with seat reference

- Added support for seat reference in booking audit actions.
- Updated localization for booking creation to include seat information.
- Modified relevant services to pass attendee seat ID during booking creation.

* fix: update test data to match schema requirements

- Add seatReferenceUid: null to default mock audit log data
- Add seatReferenceUid: null to multiple audit logs test case
- Convert SEAT_RESCHEDULED test data to use numeric timestamps instead of ISO strings

Co-Authored-By: [email protected] <[email protected]>

* Allow nullish seatReferenceUid

* feat: enhance booking audit to support rescheduledBy information

- Updated booking audit actions to include rescheduledBy details, allowing tracking of who rescheduled a booking.
- Refactored related services to accommodate the new rescheduledBy parameter in booking events.
- Adjusted type definitions and function signatures to reflect the changes in the booking audit context.

* Avoid possible run time issue

* Fix imoport path

* fix failing test due to merge from main\

* Pass useruuid

* chore: retrigger CI (flaky unit test)

Co-Authored-By: [email protected] <[email protected]>

* feat: add context parameter to bulk audit methods for impersonation support

- Add context parameter to queueBulkCreatedAudit and queueBulkRescheduledAudit in BookingAuditProducerService interface
- Add context parameter to BookingAuditTaskerProducerService implementation
- Add context parameter to onBulkBookingsCreated and onBulkBookingsRescheduled in BookingEventHandlerService
- Update RegularBookingService.fireBookingEvents to accept and pass impersonation context
- Update RecurringBookingService.fireBookingEvents to accept and pass impersonation context
- Update handleSeats to accept and pass impersonation context

Co-Authored-By: [email protected] <[email protected]>

* chore: Integrate mark-no-show booking audit

Co-Authored-By: [email protected] <[email protected]>

* fix: Simplify host no-show audit and add comment for attendee actor

Co-Authored-By: [email protected] <[email protected]>

* feat: make impersonatedByUserUuid required with explicit null for non-impersonation cases

Co-Authored-By: [email protected] <[email protected]>

* feat: integrate impersonatedByUserUuid into booking cancellation audit flow

- Add impersonatedByUserUuid to CancelBookingInput and CancelBookingMeta types
- Pass audit context with impersonatedBy to onBookingCancelled and onBulkBookingsCancelled
- Update all cancel booking call sites to pass impersonatedByUserUuid:
  - Web app cancel route: uses session impersonatedBy
  - API v1 and v2: explicitly set to null (no impersonation support)

Co-Authored-By: [email protected] <[email protected]>

* refactor: make impersonatedByUserUuid optional and remove explicit null assignments

- Changed impersonatedByUserUuid from required (string | null) to optional (string?)
- Removed explicit null assignments from API v1 and v2 endpoints
- Keep impersonatedByUserUuid only where impersonation actually occurs (web app)

Co-Authored-By: [email protected] <[email protected]>

* Apply suggestions from code review

Rfemove unnecessary comment

* fix: restore bookingMeta variable in createBookingForApiV1

Co-Authored-By: [email protected] <[email protected]>

* fix: Make actionSource required with ValidActionSource type and remove unnecessary comments

Co-Authored-By: [email protected] <[email protected]>

* fix: Remove merge conflict markers from bookings.service.ts

Co-Authored-By: [email protected] <[email protected]>

* feat: implement SYSTEM as a booking audit source for background tasks, including no-show triggers.

* refactor: Move prisma query to BookingRepository for audit logging

Co-Authored-By: [email protected] <[email protected]>

* Conflict resolution

* refactor: introduce `handleMarkHostNoShow` for public viewer and standardize actor and action source parameters for no-show actions.

* refactor: Combine HostNoShowUpdatedAuditActionService and AttendeeNoShowUpdatedAuditActionService into NoShowUpdatedActionService

- Create new NoShowUpdatedAuditActionService with combined schema supporting both noShowHost and noShowAttendee as optional fields
- Update BookingAuditActionServiceRegistry to use combined service with NO_SHOW_UPDATED action type
- Update BookingAuditTaskerProducerService with single queueNoShowUpdatedAudit method
- Update BookingAuditProducerService.interface.ts with combined method
- Update BookingEventHandlerService with single onNoShowUpdated method
- Update handleMarkNoShow.ts to use combined audit service
- Update tasker tasks (triggerGuestNoShow, triggerHostNoShow) to use combined service
- Add NO_SHOW_UPDATED to Prisma BookingAuditAction enum
- Remove old separate HostNoShowUpdatedAuditActionService and AttendeeNoShowUpdatedAuditActionService files

This allows a single API action (e.g., API V2 markAbsent) that updates both host and attendee no-show status to be logged as a single audit event.

Co-Authored-By: [email protected] <[email protected]>

* chore: Add migration for NO_SHOW_UPDATED audit action enum value

Co-Authored-By: [email protected] <[email protected]>

* refactor: Update no-show audit schema to use host and attendees array

- Rename noShowHost to host and noShowAttendee to attendees (remove redundant prefix)
- Change attendees from single value to array to support multiple attendees in single audit entry
- Update handleMarkNoShow.ts to create single audit entry for all attendees
- Update tasker tasks (triggerGuestNoShow, triggerHostNoShow) to use new schema
- Update display data types to reflect new schema structure

Co-Authored-By: [email protected] <[email protected]>

* Update schema to be more clear. Call onNoShowUpdated immediately after DB update as audit only cares about DB update, and this would avoid any accidental Audit update on DB change

* chore: accommodate schema changes and fix type errors for no-show audit

Co-Authored-By: [email protected] <[email protected]>

* fix: Update migration to remove old no-show enum values

Co-Authored-By: [email protected] <[email protected]>

* fix: Use updated attendees in webhook payload for guest no-show

Co-Authored-By: [email protected] <[email protected]>

* fix: Remove duplicate imports and fix actor parameter in bookings.service.ts

Co-Authored-By: [email protected] <[email protected]>

* refactor: Move booking query to BookingRepository and remove unused method

Co-Authored-By: [email protected] <[email protected]>

* refactor: centralize no-show audit event firing and attendee fetching within `handleMarkNoShow` for improved clarity.

* fix: Build attendeesNoShow as Record with attendee IDs as keys

Co-Authored-By: [email protected] <[email protected]>

* Fix and add tests for handleMarkBoShow

* refactor: Move prisma queries to AttendeeRepository and BookingRepository

Co-Authored-By: [email protected] <[email protected]>

* fix: Correct return type for updateNoShow method (noShow can be null)

Co-Authored-By: [email protected] <[email protected]>

* fix: Update handleMarkNoShow tests to mock new repository methods

Co-Authored-By: [email protected] <[email protected]>

* fix triggerGuestNoShow

* refactor: Move triggerGuestNoShow queries to AttendeeRepository and add unit tests

- Add new methods to AttendeeRepository:
  - findByBookingId: Get attendees with id, email, noShow
  - findByBookingIdWithDetails: Get full attendee details
  - updateManyNoShowByBookingIdAndEmails: Update specific attendees
  - updateManyNoShowByBookingIdExcludingEmails: Update all except specific emails
- Refactor triggerGuestNoShow.ts to use AttendeeRepository instead of direct Prisma calls
- Add comprehensive unit tests for triggerGuestNoShow following handleMarkNoShow.test.ts pattern:
  - Mock repositories and external services
  - In-memory DB simulation
  - Test core functionality, audit logging, webhook payload, error handling, and edge cases

Co-Authored-By: [email protected] <[email protected]>

* refactor: Move triggerHostNoShow queries to repositories and delete unit test file

Co-Authored-By: [email protected] <[email protected]>

* refactor: Convert repository methods to use named parameters objects

Co-Authored-By: [email protected] <[email protected]>

* refactor: Enhance no-show handling by consolidating audit logging and updating repository interactions

- Refactor `buildResultPayload` to accept a structured argument for better clarity.
- Update `updateAttendees` to use a named parameter object for improved readability.
- Introduce `fireNoShowUpdatedEvent` to centralize no-show audit logging for both hosts and guests.
- Remove redundant methods and streamline attendee retrieval in `AttendeeRepository`.
- Add comprehensive unit tests for no-show event handling, ensuring accurate audit logging and webhook triggering.

* test: Add tests for handleMarkHostNoShow guest actor and unmarking host no-show

Co-Authored-By: [email protected] <[email protected]>

* fix: update attendeesNoShow validation to handle numeric keys

- Changed attendeesNoShow schema to use z.coerce.number() for key validation, ensuring string keys are correctly coerced to numbers.
- Updated test to validate attendeesNoShow data using numeric key comparison, improving robustness of the audit data checks.

* test: Add integration tests for NoShowUpdatedAuditActionService coerce fix

Co-Authored-By: [email protected] <[email protected]>

* feat: add graceful error handling for audit log enrichment

- Add hasError field to EnrichedAuditLog type
- Create buildFallbackAuditLog() method for failed enrichments
- Wrap enrichAuditLog() in try-catch to handle errors gracefully
- Add booking_audit_action.error_processing translation key
- Update BookingHistory.tsx to show warning icon for error logs
- Hide 'Show details' button for logs with hasError
- Add comprehensive test cases for error handling scenarios

Co-Authored-By: [email protected] <[email protected]>

* feat: Enhance booking audit action services with new display fields and improved validation

- Added "attendee_no_show_updated" and "no_show_updated" translations to common.json.
- Updated IAuditActionService to include new methods for handling display fields and migration.
- Enhanced NoShowUpdatedAuditActionService to differentiate between host and attendee no-show updates.
- Improved ReassignmentAuditActionService to ensure consistent handling of audit data.
- Refactored BookingAuditViewerService for better clarity and maintainability.

* refactor: Use attendeeEmail instead of attendeeId as key in audit data and store host's userUuid

- Updated schema to use attendee email as key instead of attendee ID because attendee records can be reused with different person's data
- Store host's userUuid in audit data with format: host: { userUuid, noShow: { old, new } }
- Updated fireNoShowUpdated to accept hostUserUuid parameter
- Added uuid field to BookingRepository.findByUidIncludeEventTypeAttendeesAndUser
- Updated NoShowUpdatedAuditActionService getDisplayFields to work with email-based keys
- Added attendeeRepository to DI modules for BookingAuditTaskConsumer
- Updated tests to match new schema format

Co-Authored-By: [email protected] <[email protected]>

* test: Update integration tests to use new schema format with host.userUuid and email keys

Co-Authored-By: [email protected] <[email protected]>

* fix: correct audit schema for SYSTEM source and ensure attendee lookup by bookingId

- Fix schema inconsistency: use host.userUuid format instead of hostNoShow
- Add user.uuid to getBooking select for audit logging
- Log warning when hostUserUuid is undefined but host no-show is being updated
- Use email as key for attendeesNoShow (not attendee ID) to match schema
- Fetch attendees by bookingId before updating to ensure correct scoping
- Remove unused safeStringify import

* refactor: Change attendeesNoShow schema from Record to Array format

- Update NoShowUpdatedAuditActionService schema to use array format:
  attendeesNoShow: Array<{attendeeEmail: string, noShow: {old, new}}>
- Update handleMarkNoShow.ts to build attendeesNoShow as array
- Update common.ts fireNoShowUpdatedEvent to convert Map to array
- Update all tests to use new array format with attendeeEmail property

Co-Authored-By: [email protected] <[email protected]>

* refactor: Update attendeesNoShow schema to use array format in triggerNoShow tasks

- Refactor `triggerGuestNoShow` and `triggerHostNoShow` to replace Map with array for `attendeesNoShowAudit`.
- Update `fireNoShowUpdatedEvent` to handle the new array format for attendees.
- Ensure consistent data structure across no-show audit logging for better clarity and maintainability.

* fix: Update ReassignmentAuditActionService to use GetDisplayFieldsParams interface

Co-Authored-By: [email protected] <[email protected]>

* fix: Update ReassignmentAuditActionService tests to use GetDisplayFieldsParams interface

Co-Authored-By: [email protected] <[email protected]>

* fix: Use handleMarkAttendeeNoShow for API v2 mark absent endpoint

- Export handleMarkAttendeeNoShow from platform-libraries
- Update API v2 bookings service to use handleMarkAttendeeNoShow with actionSource
- Add validation for userUuid before calling handleMarkAttendeeNoShow

Co-Authored-By: [email protected] <[email protected]>

* refactor: Enhance display fields structure in booking audit components

- Updated `BookingHistory.tsx` to allow for more flexible display fields, including optional raw values and arrays of values.
- Introduced `DisplayFieldValue` component for rendering display fields, improving clarity and maintainability.
- Adjusted `IAuditActionService` and `NoShowUpdatedAuditActionService` to align with the new display fields structure.
- Ensured consistent handling of display fields across the booking audit service for better data representation.

* fix: Remove debug code that duplicated first attendee in display fields

Co-Authored-By: [email protected] <[email protected]>

* refactor: Update attendee repository methods to use structured parameters

- Modified `updateNoShow`, `updateManyNoShowByBookingIdAndEmails`, and `updateManyNoShowByBookingIdExcludingEmails` methods to accept structured `where` and `data` parameters for better clarity and maintainability.
- Updated calls to these methods throughout the codebase to reflect the new parameter structure.
- Removed unused `findByIdWithNoShow` method and adjusted related logic to streamline attendee data retrieval.

* feat: Add infrastructure for no-show audit integration

- Add Prisma migrations for SYSTEM source and NO_SHOW_UPDATED audit action
- Add NoShowUpdatedAuditActionService with array-based attendeesNoShow schema
- Update BookingAuditActionServiceRegistry to include NO_SHOW_UPDATED
- Update BookingAuditTaskConsumer and BookingAuditViewerService
- Add AttendeeRepository methods for no-show queries
- Update IAuditActionService interface with values array support
- Update locales with no-show audit translation keys

Co-Authored-By: [email protected] <[email protected]>

* fix: Add NO_SHOW_UPDATED to BookingAuditAction and SYSTEM to ActionSource types

Co-Authored-By: [email protected] <[email protected]>

* fix: Remove HOST_NO_SHOW_UPDATED and ATTENDEE_NO_SHOW_UPDATED from BookingAuditAction type to match Prisma schema

Co-Authored-By: [email protected] <[email protected]>

* fix: Update BookingAuditActionSchema to use NO_SHOW_UPDATED instead of HOST_NO_SHOW_UPDATED and ATTENDEE_NO_SHOW_UPDATED

Co-Authored-By: [email protected] <[email protected]>

* refactor: Remove deprecated no-show audit services and unify to NoShowUpdatedAuditActionService

- Delete HostNoShowUpdatedAuditActionService and AttendeeNoShowUpdatedAuditActionService
- Update BookingAuditProducerService.interface.ts to use queueNoShowUpdatedAudit
- Update BookingAuditTaskerProducerService.ts to use queueNoShowUpdatedAudit
- Update BookingEventHandlerService.ts to use onNoShowUpdated
- Add integration tests for NoShowUpdatedAuditActionService

Co-Authored-By: [email protected] <[email protected]>

* fix: Update test mock to match new AttendeeRepository.updateNoShow signature

Co-Authored-By: [email protected] <[email protected]>

* refactor: rename handleMarkAttendeeNoShow to handleMarkNoShow and update related types

- Renamed `handleMarkAttendeeNoShow` to `handleMarkNoShow` for clarity.
- Updated type definitions to reflect the new naming convention.
- Modified the `markNoShow` handler to require `userUuid` and adjusted related logic.
- Enhanced the `fireNoShowUpdatedEvent` to accommodate changes in event type structure.
- Updated references across various files to ensure consistency with the new function name.

* handle null value

* fix: add explicit parentheses for operator precedence clarity

Co-Authored-By: [email protected] <[email protected]>

* Fix cubic reported bug

* feat: add impersonation audit support to no-show flow (#27601)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* feat: add impersonatedByUserUuid context to all BookingEventHandler calls (#27602)

- Add context parameter to confirm.handler.ts (onBulkBookingsRejected, onBookingRejected)
- Add context parameter to requestReschedule.handler.ts (onRescheduleRequested)
- Add context parameter to editLocation.handler.ts (onLocationChanged)
- Add context parameter to addGuests.handler.ts (onAttendeeAdded)
- Add context parameter to handleConfirmation.ts (onBulkBookingsAccepted, onBookingAccepted)
- Update _router.tsx to pass impersonatedByUserUuid from session to handlers

This ensures all BookingEventHandler method calls that have loggedInUser context
now properly support impersonation tracking for audit logging.

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix: remove stray merge artifact in RegularBookingService

Co-Authored-By: [email protected] <[email protected]>

* fix: remove duplicate imports in BookingRepository

Co-Authored-By: [email protected] <[email protected]>

* fix: resolve type errors and duplicate declarations from merge

Co-Authored-By: [email protected] <[email protected]>

* fix: remove duplicate test assertions and duplicate test from merge artifacts

Co-Authored-By: [email protected] <[email protected]>

* fix: remove redundant ?? undefined from impersonatedByUserUuid

Co-Authored-By: [email protected] <[email protected]>

* fix: update impersonatedByUserUuid type to string | null for consistency

Co-Authored-By: [email protected] <[email protected]>

* fix: make impersonatedByUserUuid required in booking audit flows

Changes impersonatedByUserUuid from optional (?: string | null) to
required (: string | null) in all booking-related type definitions.
This ensures audit-critical parameters are never accidentally omitted.

Fixed all call sites to explicitly pass the value or null.

Co-Authored-By: [email protected] <[email protected]>

* fix: add impersonatedByUserUuid to remaining callers and tests

Adds impersonatedByUserUuid: null to API v1, API v2, and test callers
of handleCancelBooking that were missing the now-required parameter.

Co-Authored-By: [email protected] <[email protected]>

* fix: require impersonatedByUserUuid in DTOs and pass it across all booking flows (coalesce to null)

Co-Authored-By: [email protected] <[email protected]>

* fix: add impersonatedByUserUuid to remaining call sites (confirm, markNoShow, webhook, tests)

Co-Authored-By: [email protected] <[email protected]>

* fix: add impersonatedByUserUuid to confirm handler test and API v2 confirm/decline calls

Co-Authored-By: [email protected] <[email protected]>

* fix: derive impersonatedByUserUuid from session in reportBooking handler instead of hardcoding null

Co-Authored-By: [email protected] <[email protected]>

* fix: reorder spread to ensure impersonatedByUserUuid null fallback is not overwritten

Co-Authored-By: [email protected] <[email protected]>

* fix: add missing impersonatedByUserUuid to CalendarSyncService cancel and reschedule calls

Co-Authored-By: [email protected] <[email protected]>

* fix: update CalendarSyncService tests to expect impersonatedByUserUuid

Co-Authored-By: [email protected] <[email protected]>

* ci: retrigger failed checks (attempt 1)

Co-Authored-By: [email protected] <[email protected]>

* ci: retrigger failed checks (attempt 2)

Co-Authored-By: [email protected] <[email protected]>

* ci: retrigger failed checks (attempt 3)

Co-Authored-By: [email protected] <[email protected]>

* chore: bust prisma cache with comment change

Co-Authored-By: [email protected] <[email protected]>

* ci: retrigger after cache bust (attempt 2)

Co-Authored-By: [email protected] <[email protected]>

* ci: retrigger after cache bust (attempt 3)

Co-Authored-By: [email protected] <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Udit Takkar <[email protected]>
Co-authored-by: Volnei Munhoz <[email protected]>
2026-03-09 10:53:36 -03:00
..

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)
  • SYSTEM: Background job (e.g., Tasker's task, trigger.dev job for automatic no-show detection)
  • 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
  • NO_SHOW_UPDATED: Host or 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, SYSTEM, 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.