feat: [Booking Audit Stack - 1] Add Booking Audit System foundation (database schema and repositories) (calcom#24838)

* feat: Implement Booking Audit System with database architecture and repository interfaces

- Added `ARCHITECTURE.md` detailing the design and structure of the Booking Audit System, including core tables `AuditActor` and `BookingAudit`.
- Created repository interfaces `IAuditActorRepository` and `IBookingAuditRepository` for managing audit actor and booking audit records.
- Implemented `PrismaAuditActorRepository` and `PrismaBookingAuditRepository` for database interactions.
- Defined enums for `BookingAuditType`, `BookingAuditAction`, and `AuditActorType` in the Prisma schema.
- Added migration scripts to create necessary database tables and enums for the audit system.

This commit establishes a robust framework for tracking booking-related actions, ensuring compliance and data integrity.

* feat(audit): add system actor migration

Author: hariombalhara

packages/features/booking-audit/ARCHITECTURE.md

@@ -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>;
+}
+

packages/features/booking-audit/lib/repository/IAuditActorRepository.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>;
+}
+

packages/features/booking-audit/lib/repository/IBookingAuditRepository.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;
+    }
+}
+

packages/features/booking-audit/lib/repository/PrismaAuditActorRepository.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,
+        });
+    }
+}
+

packages/features/booking-audit/lib/repository/PrismaBookingAuditRepository.ts

@@ -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;

packages/prisma/migrations/20251115043236_add_audit_booking/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;

packages/prisma/migrations/20251115054502_insert_system_actor/migration.sql

@@ -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 {
   ACTIVE
   PAST_DUE