@blackcode_sa/metaestetics-api 1.15.16 → 1.15.17-staging.1

package/src/admin/booking/booking.admin.ts

@@ -1,1073 +1,1330 @@
-import * as admin from "firebase-admin";
-import { Timestamp as FirebaseClientTimestamp } from "@firebase/firestore";
-import {
-  BookingAvailabilityCalculator,
-  BookingAvailabilityRequest,
-  BookingAvailabilityResponse,
-  AvailableSlot,
-} from "./";
-import { CalendarEventStatus, CalendarEventType } from "../../types/calendar";
-import {
-  Clinic,
-  CLINICS_COLLECTION,
-  ClinicGroup,
-  CLINIC_GROUPS_COLLECTION,
-} from "../../types/clinic";
-import {
-  Practitioner,
-  PRACTITIONERS_COLLECTION,
-} from "../../types/practitioner";
-import {
-  Procedure,
-  PROCEDURES_COLLECTION,
-  ProcedureSummaryInfo,
-} from "../../types/procedure";
-import {
-  PatientProfile,
-  PATIENTS_COLLECTION,
-  PatientSensitiveInfo,
-  PATIENT_SENSITIVE_INFO_COLLECTION,
-  Gender,
-} from "../../types/patient";
-import {
-  Appointment,
-  AppointmentStatus,
-  PaymentStatus,
-  APPOINTMENTS_COLLECTION,
-  ProcedureExtendedInfo,
-} from "../../types/appointment";
-import { Currency } from "../../backoffice/types/static/pricing.types";
-import {
-  DocumentTemplate as AppDocumentTemplate,
-  FilledDocument,
-  FilledDocumentStatus,
-  USER_FORMS_SUBCOLLECTION,
-  DOCTOR_FORMS_SUBCOLLECTION,
-} from "../../types/documentation-templates";
-import { TechnologyDocumentationTemplate } from "../../backoffice/types/technology.types";
-import {
-  ClinicInfo,
-  PractitionerProfileInfo,
-  PatientProfileInfo,
-} from "../../types/profile";
-import { Category } from "../../backoffice/types/category.types";
-import { Subcategory } from "../../backoffice/types/subcategory.types";
-import { Technology } from "../../backoffice/types/technology.types";
-import { Product } from "../../backoffice/types/product.types";
-import {
-  CalendarEvent,
-  CalendarEventTime,
-  CalendarSyncStatus,
-  ProcedureInfo as CalendarProcedureInfo,
-  CALENDAR_COLLECTION,
-} from "../../types/calendar";
-import { DocumentManagerAdminService } from "../documentation-templates/document-manager.admin";
-import { LinkedFormInfo } from "../../types/appointment";
-import { TimestampUtils } from "../../utils/TimestampUtils";
-import { Logger } from "../logger";
-
-/**
- * Interface for the data required by orchestrateAppointmentCreation
- */
-export interface OrchestrateAppointmentCreationData {
-  patientId: string;
-  procedureId: string;
-  appointmentStartTime: admin.firestore.Timestamp;
-  appointmentEndTime: admin.firestore.Timestamp;
-  patientNotes?: string | null;
-}
-
-/**
- * Admin service for handling booking-related operations.
- * This is the cloud-based implementation that will be used in Cloud Functions.
- */
-export class BookingAdmin {
-  private db: admin.firestore.Firestore;
-  private documentManagerAdmin: DocumentManagerAdminService;
-
-  /**
-   * Creates a new BookingAdmin instance
-   * @param firestore - Firestore instance provided by the caller
-   */
-  constructor(firestore?: admin.firestore.Firestore) {
-    this.db = firestore || admin.firestore();
-    this.documentManagerAdmin = new DocumentManagerAdminService(this.db);
-  }
-
-  /**
-   * Gets available booking time slots for a specific clinic, practitioner, and procedure
-   *
-   * @param clinicId - ID of the clinic
-   * @param practitionerId - ID of the practitioner
-   * @param procedureId - ID of the procedure
-   * @param timeframe - Time range to check for availability
-   * @returns Promise resolving to an array of available booking slots
-   */
-  async getAvailableBookingSlots(
-    clinicId: string,
-    practitionerId: string,
-    procedureId: string,
-    timeframe: {
-      start: Date | admin.firestore.Timestamp;
-      end: Date | admin.firestore.Timestamp;
-    }
-  ): Promise<{ availableSlots: { start: admin.firestore.Timestamp }[] }> {
-    try {
-      Logger.info("[BookingAdmin] Starting availability calculation", {
-        clinicId,
-        practitionerId,
-        procedureId,
-        timeframeStart:
-          timeframe.start instanceof Date
-            ? timeframe.start.toISOString()
-            : timeframe.start.toDate().toISOString(),
-        timeframeEnd:
-          timeframe.end instanceof Date
-            ? timeframe.end.toISOString()
-            : timeframe.end.toDate().toISOString(),
-      });
-
-      // Convert timeframe dates to Firestore Timestamps if needed
-      const start =
-        timeframe.start instanceof Date
-          ? admin.firestore.Timestamp.fromDate(timeframe.start)
-          : timeframe.start;
-
-      const end =
-        timeframe.end instanceof Date
-          ? admin.firestore.Timestamp.fromDate(timeframe.end)
-          : timeframe.end;
-
-      // 1. Fetch clinic data
-      Logger.debug("[BookingAdmin] Fetching clinic data", { clinicId });
-      const clinicDoc = await this.db.collection("clinics").doc(clinicId).get();
-      if (!clinicDoc.exists) {
-        Logger.error("[BookingAdmin] Clinic not found", { clinicId });
-        throw new Error(`Clinic ${clinicId} not found`);
-      }
-      const clinic = clinicDoc.data() as unknown as Clinic;
-      Logger.debug("[BookingAdmin] Retrieved clinic data", {
-        clinicName: clinic.name,
-        clinicHasWorkingHours: !!clinic.workingHours,
-      });
-
-      // 2. Fetch practitioner data
-      Logger.debug("[BookingAdmin] Fetching practitioner data", {
-        practitionerId,
-      });
-      const practitionerDoc = await this.db
-        .collection("practitioners")
-        .doc(practitionerId)
-        .get();
-      if (!practitionerDoc.exists) {
-        Logger.error("[BookingAdmin] Practitioner not found", {
-          practitionerId,
-        });
-        throw new Error(`Practitioner ${practitionerId} not found`);
-      }
-      const practitioner = practitionerDoc.data() as unknown as Practitioner;
-      Logger.debug("[BookingAdmin] Retrieved practitioner data", {
-        practitionerName: `${practitioner.basicInfo.firstName} ${practitioner.basicInfo.lastName}`,
-        pracWorkingHoursCount: practitioner.clinicWorkingHours?.length || 0,
-      });
-
-      // 3. Fetch procedure data
-      Logger.debug("[BookingAdmin] Fetching procedure data", { procedureId });
-      const procedureDoc = await this.db
-        .collection("procedures")
-        .doc(procedureId)
-        .get();
-      if (!procedureDoc.exists) {
-        Logger.error("[BookingAdmin] Procedure not found", { procedureId });
-        throw new Error(`Procedure ${procedureId} not found`);
-      }
-      const procedure = procedureDoc.data() as unknown as Procedure;
-      Logger.debug("[BookingAdmin] Retrieved procedure data", {
-        procedureName: procedure.name,
-        procedureDuration: procedure.duration,
-      });
-
-      // 4. Fetch clinic calendar events
-      Logger.debug("[BookingAdmin] Fetching clinic calendar events", {
-        clinicId,
-        startTime: start.toDate().toISOString(),
-        endTime: end.toDate().toISOString(),
-      });
-      const clinicCalendarEvents = await this.getClinicCalendarEvents(
-        clinicId,
-        start,
-        end
-      );
-      Logger.debug("[BookingAdmin] Retrieved clinic calendar events", {
-        count: clinicCalendarEvents.length,
-      });
-
-      // 5. Fetch practitioner calendar events
-      Logger.debug("[BookingAdmin] Fetching practitioner calendar events", {
-        practitionerId,
-        startTime: start.toDate().toISOString(),
-        endTime: end.toDate().toISOString(),
-      });
-      const practitionerCalendarEvents =
-        await this.getPractitionerCalendarEvents(practitionerId, start, end);
-      Logger.debug("[BookingAdmin] Retrieved practitioner calendar events", {
-        count: practitionerCalendarEvents.length,
-      });
-
-      // Since we're working with two different Timestamp implementations (admin vs client),
-      // we need to convert our timestamps to the client-side format expected by the calculator
-      // Create client Timestamp objects from admin Timestamp objects
-      const convertedTimeframe = {
-        start: this.adminTimestampToClientTimestamp(start),
-        end: this.adminTimestampToClientTimestamp(end),
-      };
-
-      // Create the request object for the calculator
-      const request: BookingAvailabilityRequest = {
-        clinic,
-        practitioner,
-        procedure,
-        timeframe: convertedTimeframe,
-        clinicCalendarEvents:
-          this.convertEventsTimestamps(clinicCalendarEvents),
-        practitionerCalendarEvents: this.convertEventsTimestamps(
-          practitionerCalendarEvents
-        ),
-        tz: clinic.location.tz || "UTC",
-      };
-
-      Logger.info("[BookingAdmin] Calling availability calculator", {
-        calculatorInputReady: true,
-        timeframeDurationHours: Math.round(
-          (end.toMillis() - start.toMillis()) / (1000 * 60 * 60)
-        ),
-        clinicEventsCount: clinicCalendarEvents.length,
-        practitionerEventsCount: practitionerCalendarEvents.length,
-      });
-
-      // Use the calculator to compute available slots
-      const result = BookingAvailabilityCalculator.calculateSlots(request);
-
-      // Convert the client Timestamps to admin Timestamps before returning
-      const availableSlotsResult = {
-        availableSlots: result.availableSlots.map((slot) => ({
-          start: admin.firestore.Timestamp.fromMillis(slot.start.toMillis()),
-        })),
-      };
-
-      Logger.info(
-        "[BookingAdmin] Availability calculation completed successfully",
-        {
-          availableSlotsCount: availableSlotsResult.availableSlots.length,
-          firstSlotTime:
-            availableSlotsResult.availableSlots.length > 0
-              ? availableSlotsResult.availableSlots[0].start
-                  .toDate()
-                  .toISOString()
-              : "none",
-          lastSlotTime:
-            availableSlotsResult.availableSlots.length > 0
-              ? availableSlotsResult.availableSlots[
-                  availableSlotsResult.availableSlots.length - 1
-                ].start
-                  .toDate()
-                  .toISOString()
-              : "none",
-        }
-      );
-
-      return availableSlotsResult;
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-      Logger.error("[BookingAdmin] Error getting available slots", {
-        errorMessage,
-        clinicId,
-        practitionerId,
-        procedureId,
-        stack: error instanceof Error ? error.stack : undefined,
-      });
-      throw error;
-    }
-  }
-
-  /**
-   * Converts an admin Firestore Timestamp to a client Firestore Timestamp
-   */
-  private adminTimestampToClientTimestamp(
-    timestamp: admin.firestore.Timestamp
-  ): FirebaseClientTimestamp {
-    // Use TimestampUtils instead of custom implementation
-    return TimestampUtils.adminToClient(timestamp) as FirebaseClientTimestamp;
-  }
-
-  /**
-   * Converts timestamps in calendar events from admin Firestore Timestamps to client Firestore Timestamps
-   */
-  private convertEventsTimestamps(events: any[]): any[] {
-    return events.map((event) => ({
-      ...event,
-      eventTime: {
-        start: TimestampUtils.adminToClient(
-          event.eventTime.start
-        ) as FirebaseClientTimestamp,
-        end: TimestampUtils.adminToClient(
-          event.eventTime.end
-        ) as FirebaseClientTimestamp,
-      },
-      // Convert any other timestamps in the event if needed
-    }));
-  }
-
-  /**
-   * Fetches clinic calendar events for a specific time range
-   *
-   * @param clinicId - ID of the clinic
-   * @param start - Start time of the range
-   * @param end - End time of the range
-   * @returns Promise resolving to an array of calendar events
-   */
-  private async getClinicCalendarEvents(
-    clinicId: string,
-    start: admin.firestore.Timestamp,
-    end: admin.firestore.Timestamp
-  ): Promise<any[]> {
-    try {
-      Logger.debug("[BookingAdmin] Querying clinic calendar events", {
-        clinicId,
-        startTime: start.toDate().toISOString(),
-        endTime: end.toDate().toISOString(),
-      });
-
-      // Increased to 30 days to handle long blocking events (e.g., holidays, extended time off)
-      // This ensures we catch blocking events that start before our query range but overlap with it
-      const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000;
-      const queryStart = admin.firestore.Timestamp.fromMillis(
-        start.toMillis() - MAX_EVENT_DURATION_MS
-      );
-
-      // Query for events that:
-      // 1. Start before or during our query range (eventTime.start < end)
-      // 2. We'll post-filter to ensure they overlap (eventTime.end > start)
-      const eventsRef = this.db
-        .collection(`clinics/${clinicId}/calendar`)
-        .where("eventTime.start", ">=", queryStart)
-        .where("eventTime.start", "<=", end)
-        .orderBy("eventTime.start");
-
-      const snapshot = await eventsRef.get();
-
-      // Post-filter to ensure events actually overlap with our query range
-      // An event overlaps if: eventTime.start < queryEnd AND eventTime.end > queryStart
-      const events = snapshot.docs
-        .map((doc) => ({
-          ...doc.data(),
-          id: doc.id,
-        }))
-        .filter((event: any) => {
-          // Event overlaps if it ends after our start time
-          const overlaps = event.eventTime.end.toMillis() > start.toMillis();
-          if (!overlaps) {
-            Logger.debug("[BookingAdmin] Filtered out non-overlapping event", {
-              eventId: event.id,
-              eventStart: event.eventTime.start.toDate().toISOString(),
-              eventEnd: event.eventTime.end.toDate().toISOString(),
-              queryStart: start.toDate().toISOString(),
-              queryEnd: end.toDate().toISOString(),
-            });
-          }
-          return overlaps;
-        });
-
-      Logger.debug("[BookingAdmin] Retrieved clinic calendar events", {
-        clinicId,
-        eventsCount: events.length,
-        eventsTypes: this.summarizeEventTypes(events),
-        queryStartTime: queryStart.toDate().toISOString(),
-      });
-
-      return events;
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-      Logger.error("[BookingAdmin] Error fetching clinic calendar events", {
-        errorMessage,
-        clinicId,
-        startTime: start.toDate().toISOString(),
-        endTime: end.toDate().toISOString(),
-        stack: error instanceof Error ? error.stack : undefined,
-      });
-      return [];
-    }
-  }
-
-  /**
-   * Fetches practitioner calendar events for a specific time range
-   *
-   * @param practitionerId - ID of the practitioner
-   * @param start - Start time of the range
-   * @param end - End time of the range
-   * @returns Promise resolving to an array of calendar events
-   */
-  private async getPractitionerCalendarEvents(
-    practitionerId: string,
-    start: admin.firestore.Timestamp,
-    end: admin.firestore.Timestamp
-  ): Promise<any[]> {
-    try {
-      Logger.debug("[BookingAdmin] Querying practitioner calendar events", {
-        practitionerId,
-        startTime: start.toDate().toISOString(),
-        endTime: end.toDate().toISOString(),
-      });
-
-      // Increased to 30 days to handle long blocking events (e.g., holidays, extended time off)
-      // This ensures we catch blocking events that start before our query range but overlap with it
-      const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000;
-      const queryStart = admin.firestore.Timestamp.fromMillis(
-        start.toMillis() - MAX_EVENT_DURATION_MS
-      );
-
-      // Query for events that:
-      // 1. Start before or during our query range (eventTime.start <= end)
-      // 2. We'll post-filter to ensure they overlap (eventTime.end > start)
-      const eventsRef = this.db
-        .collection(`practitioners/${practitionerId}/calendar`)
-        .where("eventTime.start", ">=", queryStart)
-        .where("eventTime.start", "<=", end)
-        .orderBy("eventTime.start");
-
-      const snapshot = await eventsRef.get();
-
-      // Post-filter to ensure events actually overlap with our query range
-      // An event overlaps if: eventTime.start < queryEnd AND eventTime.end > queryStart
-      const events = snapshot.docs
-        .map((doc) => ({
-          ...doc.data(),
-          id: doc.id,
-        }))
-        .filter((event: any) => {
-          // Event overlaps if it ends after our start time
-          const overlaps = event.eventTime.end.toMillis() > start.toMillis();
-          if (!overlaps) {
-            Logger.debug("[BookingAdmin] Filtered out non-overlapping practitioner event", {
-              eventId: event.id,
-              eventStart: event.eventTime.start.toDate().toISOString(),
-              eventEnd: event.eventTime.end.toDate().toISOString(),
-              queryStart: start.toDate().toISOString(),
-              queryEnd: end.toDate().toISOString(),
-            });
-          }
-          return overlaps;
-        });
-
-      Logger.debug("[BookingAdmin] Retrieved practitioner calendar events", {
-        practitionerId,
-        eventsCount: events.length,
-        eventsTypes: this.summarizeEventTypes(events),
-        queryStartTime: queryStart.toDate().toISOString(),
-      });
-
-      return events;
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-      Logger.error(
-        "[BookingAdmin] Error fetching practitioner calendar events",
-        {
-          errorMessage,
-          practitionerId,
-          startTime: start.toDate().toISOString(),
-          endTime: end.toDate().toISOString(),
-          stack: error instanceof Error ? error.stack : undefined,
-        }
-      );
-      return [];
-    }
-  }
-
-  /**
-   * Summarizes event types for logging purposes
-   * @param events Array of calendar events
-   * @returns Object with counts of each event type
-   */
-  private summarizeEventTypes(events: any[]): Record<string, number> {
-    const typeCounts: Record<string, number> = {};
-
-    events.forEach((event) => {
-      const eventType = event.eventType || "unknown";
-      typeCounts[eventType] = (typeCounts[eventType] || 0) + 1;
-    });
-
-    return typeCounts;
-  }
-
-  private _generateCalendarProcedureInfo(
-    procedure: Procedure
-  ): CalendarProcedureInfo {
-    return {
-      name: procedure.name,
-      description: procedure.description,
-      duration: procedure.duration, // in minutes
-      price: procedure.price,
-      currency: procedure.currency,
-    };
-  }
-
-  /**
-   * Orchestrates the creation of a new appointment, including data aggregation.
-   * This method is intended to be called from a trusted backend environment (e.g., an Express route handler in a Cloud Function).
-   *
-   * @param data - Data required to create the appointment.
-   * @param authenticatedUserId - The ID of the user making the request (for auditing, and usually is the patientId).
-   * @returns Promise resolving to an object indicating success, and appointmentId or an error message.
-   */
-  async orchestrateAppointmentCreation(
-    data: OrchestrateAppointmentCreationData,
-    authenticatedUserId: string
-  ): Promise<{
-    success: boolean;
-    appointmentId?: string;
-    appointmentData?: Appointment;
-    calendarEventId?: string;
-    error?: string;
-  }> {
-    console.log(
-      `[BookingAdmin] Orchestrating appointment creation for patient ${data.patientId} by user ${authenticatedUserId}`
-    );
-    const batch = this.db.batch();
-    const adminTsNow = admin.firestore.Timestamp.now();
-    const serverTimestampValue = admin.firestore.FieldValue.serverTimestamp();
-
-    try {
-      // --- 1. Input Validation ---
-      if (
-        !data.patientId ||
-        !data.procedureId ||
-        !data.appointmentStartTime ||
-        !data.appointmentEndTime
-      ) {
-        return {
-          success: false,
-          error:
-            "Missing required fields: patientId, procedureId, appointmentStartTime, or appointmentEndTime.",
-        };
-      }
-      if (
-        data.appointmentEndTime.toMillis() <=
-        data.appointmentStartTime.toMillis()
-      ) {
-        return {
-          success: false,
-          error: "Appointment end time must be after start time.",
-        };
-      }
-      if (authenticatedUserId !== data.patientId) {
-        console.warn(
-          `[BookingAdmin] Authenticated user ${authenticatedUserId} is booking for a different patient ${data.patientId}. Review authorization if this is not intended.`
-        );
-      }
-
-      // --- 2. Fetch Core Procedure Data ---
-      const procedureRef = this.db
-        .collection(PROCEDURES_COLLECTION)
-        .doc(data.procedureId);
-      const procedureDoc = await procedureRef.get();
-      if (!procedureDoc.exists) {
-        return {
-          success: false,
-          error: `Procedure ${data.procedureId} not found.`,
-        };
-      }
-      const procedure = procedureDoc.data() as Procedure;
-
-      // --- 3. Fetch Clinic and then other Primary Documents ---
-      // Fetch clinic first to get its clinicGroupId
-      const clinicRef = this.db
-        .collection(CLINICS_COLLECTION)
-        .doc(procedure.clinicBranchId);
-      const clinicSnap = await clinicRef.get(); // Await here directly
-      if (!clinicSnap.exists) {
-        return {
-          success: false,
-          error: `Clinic ${procedure.clinicBranchId} not found.`,
-        };
-      }
-      const clinicData = clinicSnap.data() as Clinic; // Now clinicData is available
-
-      // Define other refs using clinicData for clinicGroupRef
-      const practitionerRef = this.db
-        .collection(PRACTITIONERS_COLLECTION)
-        .doc(procedure.practitionerId);
-      const patientProfileRef = this.db
-        .collection(PATIENTS_COLLECTION)
-        .doc(data.patientId);
-      const patientSensitiveRef = this.db
-        .collection(PATIENTS_COLLECTION)
-        .doc(data.patientId)
-        .collection(PATIENT_SENSITIVE_INFO_COLLECTION)
-        .doc(data.patientId);
-      const clinicGroupRef = this.db
-        .collection(CLINIC_GROUPS_COLLECTION)
-        .doc(clinicData.clinicGroupId); // Use clinicData here
-
-      const [
-        practitionerSnap,
-        patientProfileSnap,
-        patientSensitiveSnap,
-        clinicGroupSnap,
-      ] = await Promise.all([
-        // clinicRef.get() is already done via clinicSnap
-        practitionerRef.get(),
-        patientProfileRef.get(),
-        patientSensitiveRef.get(),
-        clinicGroupRef.get(), // Fetch the defined clinicGroupRef
-      ]);
-
-      if (!practitionerSnap.exists)
-        return {
-          success: false,
-          error: `Practitioner ${procedure.practitionerId} not found.`,
-        };
-      if (!patientProfileSnap.exists)
-        return {
-          success: false,
-          error: `PatientProfile ${data.patientId} not found.`,
-        };
-      if (!clinicGroupSnap.exists)
-        return {
-          success: false,
-          error: `ClinicGroup for clinic ${procedure.clinicBranchId} not found.`,
-        };
-
-      const practitionerData = practitionerSnap.data() as Practitioner;
-      const patientProfileData = patientProfileSnap.data() as PatientProfile;
-      const patientSensitiveData = patientSensitiveSnap.exists
-        ? (patientSensitiveSnap.data() as PatientSensitiveInfo)
-        : undefined;
-      const clinicGroupData = clinicGroupSnap.data() as ClinicGroup;
-
-      // --- 4. Determine initialStatus (based on clinic settings) ---
-      const autoConfirm = clinicGroupData.autoConfirmAppointments || false;
-      const initialAppointmentStatus = autoConfirm
-        ? AppointmentStatus.CONFIRMED
-        : AppointmentStatus.PENDING;
-      const initialCalendarEventStatus = autoConfirm
-        ? CalendarEventStatus.CONFIRMED
-        : CalendarEventStatus.PENDING;
-
-      // --- 5. Aggregate Information (Snapshots) ---
-      const clinicInfo: ClinicInfo = {
-        id: clinicSnap.id,
-        name: clinicData.name,
-        featuredPhoto:
-          (typeof clinicData.coverPhoto === "string"
-            ? clinicData.coverPhoto
-            : "") ||
-          (typeof clinicData.logo === "string" ? clinicData.logo : "") ||
-          "",
-        description: clinicData.description,
-        location: clinicData.location,
-        contactInfo: clinicData.contactInfo,
-      };
-      const practitionerInfo: PractitionerProfileInfo = {
-        id: practitionerSnap.id,
-        practitionerPhoto:
-          typeof practitionerData.basicInfo.profileImageUrl === "string"
-            ? practitionerData.basicInfo.profileImageUrl
-            : null,
-        name: `${practitionerData.basicInfo.firstName} ${practitionerData.basicInfo.lastName}`,
-        email: practitionerData.basicInfo.email,
-        phone: practitionerData.basicInfo.phoneNumber || null,
-        certification: practitionerData.certification,
-      };
-      const patientInfo: PatientProfileInfo = {
-        id: patientProfileSnap.id,
-        fullName:
-          `${patientSensitiveData?.firstName || ""} ${
-            patientSensitiveData?.lastName || ""
-          }`.trim() || patientProfileData.displayName,
-        email: patientSensitiveData?.email || "",
-        phone:
-          patientSensitiveData?.phoneNumber ||
-          patientProfileData.phoneNumber ||
-          null,
-        dateOfBirth:
-          patientSensitiveData?.dateOfBirth ||
-          patientProfileData.dateOfBirth ||
-          admin.firestore.Timestamp.now(),
-        gender: patientSensitiveData?.gender || Gender.OTHER,
-      };
-      // const procedureCategory = procedure.category as Category;
-      // const procedureSubCategory = procedure.subcategory as Subcategory;
-      // const procedureTechnology = procedure.technology as Technology;
-      // const procedureProduct = procedure.product as Product;
-
-      // const procedureExtendedInfo: ProcedureExtendedInfo = {
-      //   id: procedure.id,
-      //   name: procedure.name,
-      //   description: procedure.description,
-      //   cost: procedure.price,
-      //   duration: procedure.duration,
-      //   procedureFamily: procedure.family,
-      //   procedureCategoryId: procedureCategory?.id || "",
-      //   procedureCategoryName: procedureCategory?.name || "",
-      //   procedureSubCategoryId: procedureSubCategory?.id || "",
-      //   procedureSubCategoryName: procedureSubCategory?.name || "",
-      //   procedureTechnologyId: procedureTechnology?.id || "",
-      //   procedureTechnologyName: procedureTechnology?.name || "",
-      //   procedureProductBrandId: procedureProduct.brandId || "",
-      //   procedureProductBrandName: procedureProduct.brandName || "",
-      //   procedureProductId: procedureProduct.id || "",
-      //   procedureProductName: procedureProduct.name || "",
-      // };
-
-      // // --- 6. Determine pendingUserFormsIds and linkedFormIds ---
-      // let pendingUserFormsIds: string[] = [];
-      // let linkedFormIds: string[] = [];
-      // if (
-      //   procedure.documentationTemplates &&
-      //   Array.isArray(procedure.documentationTemplates)
-      // ) {
-      //   pendingUserFormsIds = procedure.documentationTemplates
-      //     .filter(
-      //       (template: TechnologyDocumentationTemplate) =>
-      //         template.isUserForm && template.isRequired
-      //     )
-      //     .map(
-      //       (template: TechnologyDocumentationTemplate) => template.templateId
-      //     );
-      //   linkedFormIds = procedure.documentationTemplates.map(
-      //     (template: TechnologyDocumentationTemplate) => template.templateId
-      //   );
-      // }
-
-      // --- 7. Construct New Appointment Object ---
-      const newAppointmentId = this.db
-        .collection(APPOINTMENTS_COLLECTION)
-        .doc().id;
-
-      const eventTimeForCalendarEvents: CalendarEventTime = {
-        start: data.appointmentStartTime as any,
-        end: data.appointmentEndTime as any,
-      };
-
-      // Practitioner Calendar Event
-      const practitionerCalendarEventId = this.db
-        .collection(PRACTITIONERS_COLLECTION)
-        .doc(practitionerData.id)
-        .collection(CALENDAR_COLLECTION)
-        .doc().id;
-      const practitionerCalendarEventData: CalendarEvent = {
-        id: practitionerCalendarEventId,
-        appointmentId: newAppointmentId,
-        clinicBranchId: clinicData.id,
-        clinicBranchInfo: clinicInfo,
-        practitionerProfileId: practitionerData.id,
-        practitionerProfileInfo: practitionerInfo,
-        patientProfileId: patientProfileData.id,
-        patientProfileInfo: patientInfo,
-        procedureId: procedure.id,
-        procedureInfo: this._generateCalendarProcedureInfo(procedure),
-        eventName: `Appointment: ${procedure.name} with ${patientInfo.fullName}`,
-        eventLocation: clinicData.location,
-        eventTime: eventTimeForCalendarEvents,
-        description: procedure.description || "",
-        status: initialCalendarEventStatus,
-        syncStatus: CalendarSyncStatus.INTERNAL,
-        eventType: CalendarEventType.APPOINTMENT,
-        createdAt: serverTimestampValue as any,
-        updatedAt: serverTimestampValue as any,
-      };
-      batch.set(
-        this.db
-          .collection(PRACTITIONERS_COLLECTION)
-          .doc(practitionerData.id)
-          .collection(CALENDAR_COLLECTION)
-          .doc(practitionerCalendarEventId),
-        practitionerCalendarEventData
-      );
-
-      // Patient Calendar Event
-      // Use same ID as practitionerCalendarEventId
-      const patientCalendarEventData: CalendarEvent = {
-        id: practitionerCalendarEventId,
-        appointmentId: newAppointmentId,
-        clinicBranchId: clinicData.id,
-        clinicBranchInfo: clinicInfo,
-        practitionerProfileId: practitionerData.id,
-        practitionerProfileInfo: practitionerInfo,
-        procedureId: procedure.id,
-        procedureInfo: this._generateCalendarProcedureInfo(procedure),
-        eventName: `Appointment: ${procedure.name} at ${clinicData.name}`,
-        eventLocation: clinicData.location,
-        eventTime: eventTimeForCalendarEvents,
-        description: data.patientNotes || "",
-        status: initialCalendarEventStatus,
-        syncStatus: CalendarSyncStatus.INTERNAL,
-        eventType: CalendarEventType.APPOINTMENT,
-        createdAt: serverTimestampValue as any,
-        updatedAt: serverTimestampValue as any,
-      };
-      batch.set(
-        this.db
-          .collection(PATIENTS_COLLECTION)
-          .doc(patientProfileData.id)
-          .collection(CALENDAR_COLLECTION)
-          .doc(practitionerCalendarEventId),
-        patientCalendarEventData
-      );
-
-      // Clinic Calendar Event
-      // Use same ID as practitionerCalendarEventId
-      const clinicCalendarEventData: CalendarEvent = {
-        id: practitionerCalendarEventId,
-        appointmentId: newAppointmentId,
-        clinicBranchId: clinicData.id,
-        clinicBranchInfo: clinicInfo,
-        practitionerProfileId: practitionerData.id,
-        practitionerProfileInfo: practitionerInfo,
-        patientProfileId: patientProfileData.id,
-        patientProfileInfo: patientInfo,
-        procedureId: procedure.id,
-        procedureInfo: this._generateCalendarProcedureInfo(procedure),
-        eventName: `Appointment: ${procedure.name} for ${patientInfo.fullName} with ${practitionerInfo.name}`,
-        eventLocation: clinicData.location,
-        eventTime: eventTimeForCalendarEvents,
-        description: data.patientNotes || "",
-        status: initialCalendarEventStatus,
-        syncStatus: CalendarSyncStatus.INTERNAL,
-        eventType: CalendarEventType.APPOINTMENT,
-        createdAt: serverTimestampValue as any,
-        updatedAt: serverTimestampValue as any,
-      };
-      batch.set(
-        this.db
-          .collection(CLINICS_COLLECTION)
-          .doc(clinicData.id)
-          .collection(CALENDAR_COLLECTION)
-          .doc(practitionerCalendarEventId),
-        clinicCalendarEventData
-      );
-
-      // --- Initialize Pending/Draft Filled Documents and get form IDs ---
-      let initializedFormsInfo: LinkedFormInfo[] = [];
-      let pendingUserFormTemplateIds: string[] = [];
-      let allLinkedFormTemplateIds: string[] = [];
-
-      if (
-        procedure.documentationTemplates &&
-        Array.isArray(procedure.documentationTemplates) &&
-        procedure.documentationTemplates.length > 0
-      ) {
-        const formInitResult =
-          await this.documentManagerAdmin.batchInitializeAppointmentFormsFromTechnologyTemplates(
-            batch,
-            newAppointmentId,
-            procedure.id, // Pass the actual procedureId for the forms
-            procedure.documentationTemplates,
-            data.patientId,
-            procedure.practitionerId,
-            procedure.clinicBranchId,
-            adminTsNow.toMillis()
-          );
-        initializedFormsInfo = formInitResult.initializedFormsInfo;
-        pendingUserFormTemplateIds = formInitResult.pendingUserFormsIds;
-        allLinkedFormTemplateIds = formInitResult.allLinkedTemplateIds;
-      }
-
-      // --- Generate appointment products from procedure ---
-      const appointmentProducts = this._generateAppointmentProductsFromProcedure(procedure);
-
-      // --- Construct Appointment Object ---
-      const newAppointmentData: Appointment = {
-        id: newAppointmentId,
-        calendarEventId: practitionerCalendarEventId,
-        clinicBranchId: procedure.clinicBranchId,
-        clinicInfo,
-        clinic_tz: clinicData.location.tz || "UTC",
-        practitionerId: procedure.practitionerId,
-        practitionerInfo,
-        patientId: data.patientId,
-        patientInfo,
-        procedureId: data.procedureId,
-        procedureInfo: this._generateProcedureSummaryInfo(
-          procedure,
-          clinicData,
-          practitionerData
-        ),
-        procedureExtendedInfo: this._generateProcedureExtendedInfo(procedure),
-        status: initialAppointmentStatus,
-        bookingTime: adminTsNow as any,
-        confirmationTime:
-          initialAppointmentStatus === AppointmentStatus.CONFIRMED
-            ? (adminTsNow as any)
-            : null,
-        appointmentStartTime: data.appointmentStartTime as any,
-        appointmentEndTime: data.appointmentEndTime as any,
-        cost: procedure.price,
-        currency: procedure.currency,
-        paymentStatus:
-          procedure.price > 0
-            ? PaymentStatus.UNPAID
-            : PaymentStatus.NOT_APPLICABLE,
-        patientNotes: data.patientNotes || null,
-        blockingConditions: procedure.blockingConditions || [],
-        contraindications: (procedure as any).contraindications || [],
-        preProcedureRequirements: procedure.preRequirements || [],
-        postProcedureRequirements: procedure.postRequirements || [],
-        pendingUserFormsIds: pendingUserFormTemplateIds,
-        linkedFormIds: allLinkedFormTemplateIds,
-        completedPreRequirements: [],
-        completedPostRequirements: [],
-        linkedForms: initializedFormsInfo,
-        media: [],
-        reviewInfo: null,
-        metadata: {
-          selectedZones: null,
-          zonePhotos: null,
-          zonesData: null,
-          appointmentProducts: appointmentProducts,
-          extendedProcedures: [],
-          recommendedProcedures: [],
-          finalbilling: null,
-          finalizationNotes: null,
-        },
-        finalizedDetails: {
-          by: "",
-          at: adminTsNow as any,
-          notes: "",
-        },
-        internalNotes: null,
-        cancellationReason: null,
-        cancellationTime: null,
-        canceledBy: undefined,
-        rescheduleTime: null,
-        procedureActualStartTime: null,
-        actualDurationMinutes: undefined,
-        isRecurring: false,
-        recurringAppointmentId: null,
-        isArchived: false,
-        createdAt: adminTsNow as any,
-        updatedAt: adminTsNow as any,
-      };
-
-      batch.set(
-        this.db.collection(APPOINTMENTS_COLLECTION).doc(newAppointmentId),
-        newAppointmentData
-      );
-
-      // Commit Batch
-      await batch.commit();
-
-      console.log(
-        `[BookingAdmin] Appointment ${newAppointmentId} and associated calendar events created successfully.`
-      );
-      return {
-        success: true,
-        appointmentId: newAppointmentId,
-        appointmentData: newAppointmentData,
-        calendarEventId: practitionerCalendarEventId,
-      };
-    } catch (error) {
-      console.error(
-        "[BookingAdmin] Critical error in orchestrateAppointmentCreation:",
-        error
-      );
-      const errorMessage =
-        error instanceof Error
-          ? error.message
-          : "Unknown server error during appointment creation.";
-      return { success: false, error: errorMessage };
-    }
-  }
-
-  private _generateProcedureSummaryInfo(
-    procedure: Procedure,
-    clinicData: Clinic,
-    practitionerData: Practitioner
-  ): ProcedureSummaryInfo {
-    const procedureCategory = procedure.category as Category;
-    const procedureSubCategory = procedure.subcategory as Subcategory;
-    const procedureTechnology = procedure.technology as Technology;
-    const procedureProduct = procedure.product as Product;
-    return {
-      id: procedure.id,
-      name: procedure.name,
-      description: procedure.description,
-      family: procedure.family,
-      categoryName: procedureCategory?.name || "",
-      subcategoryName: procedureSubCategory?.name || "",
-      technologyName: procedureTechnology?.name || "",
-      price: procedure.price,
-      pricingMeasure: procedure.pricingMeasure,
-      currency: procedure.currency,
-      duration: procedure.duration,
-      clinicId: procedure.clinicBranchId,
-      clinicName: clinicData.name,
-      practitionerId: procedure.practitionerId,
-      practitionerName: `${practitionerData.basicInfo.firstName} ${practitionerData.basicInfo.lastName}`,
-      photo:
-        (procedureTechnology as any)?.photos?.[0]?.url ||
-        (procedureProduct as any)?.photos?.[0]?.url ||
-        "",
-      brandName: (procedureProduct as any)?.brand?.name || "",
-      productName: procedureProduct?.name || "",
-    };
-  }
-
-  private _generateProcedureExtendedInfo(
-    procedure: Procedure
-  ): ProcedureExtendedInfo {
-    const procedureCategory = procedure.category as Category;
-    const procedureSubCategory = procedure.subcategory as Subcategory;
-    const procedureTechnology = procedure.technology as Technology;
-    const procedureProduct = procedure.product as Product;
-    const productsMetadata = procedure.productsMetadata || [];
-    
-    return {
-      id: procedure.id,
-      name: procedure.name,
-      description: procedure.description,
-      cost: procedure.price,
-      duration: procedure.duration,
-      procedureFamily: procedure.family,
-      procedureCategoryId: procedureCategory?.id || "",
-      procedureCategoryName: procedureCategory?.name || "",
-      procedureSubCategoryId: procedureSubCategory?.id || "",
-      procedureSubCategoryName: procedureSubCategory?.name || "",
-      procedureTechnologyId: procedureTechnology?.id || "",
-      procedureTechnologyName: procedureTechnology?.name || "",
-      procedureProductBrandId: procedureProduct?.brandId || "",
-      procedureProductBrandName: procedureProduct?.brandName || "",
-      procedureProducts: productsMetadata
-        .filter((pp: any) => pp && pp.product) // Safety check for product-free procedures
-        .map((pp: any) => ({
-        productId: pp.product.id,
-        productName: pp.product.name,
-        brandId: pp.product.brandId,
-        brandName: pp.product.brandName,
-      })),
-    };
-  }
-
-  private _generateAppointmentProductsFromProcedure(procedure: Procedure): any[] {
-    const productsMetadata = procedure.productsMetadata || [];
-    
-    return productsMetadata
-      .filter((pp: any) => pp && pp.product) // Safety check for product-free procedures
-      .map((pp: any) => {
-      const product = pp.product;
-      return {
-        productId: product.id,
-        productName: product.name,
-        brandId: product.brandId,
-        brandName: product.brandName,
-        procedureId: procedure.id,
-        price: pp.price,
-        currency: pp.currency,
-        unitOfMeasurement: pp.pricingMeasure,
-      };
-    });
-  }
-}
+import * as admin from "firebase-admin";
+import { Timestamp as FirebaseClientTimestamp } from "@firebase/firestore";
+import {
+  BookingAvailabilityCalculator,
+  BookingAvailabilityRequest,
+  BookingAvailabilityResponse,
+  AvailableSlot,
+} from "./";
+import { CalendarEventStatus, CalendarEventType } from "../../types/calendar";
+import {
+  Clinic,
+  CLINICS_COLLECTION,
+  ClinicGroup,
+  CLINIC_GROUPS_COLLECTION,
+} from "../../types/clinic";
+import {
+  Practitioner,
+  PRACTITIONERS_COLLECTION,
+} from "../../types/practitioner";
+import {
+  Procedure,
+  PROCEDURES_COLLECTION,
+  ProcedureSummaryInfo,
+} from "../../types/procedure";
+import {
+  PatientProfile,
+  PATIENTS_COLLECTION,
+  PatientSensitiveInfo,
+  PATIENT_SENSITIVE_INFO_COLLECTION,
+  Gender,
+} from "../../types/patient";
+import {
+  Appointment,
+  AppointmentStatus,
+  PaymentStatus,
+  APPOINTMENTS_COLLECTION,
+  ProcedureExtendedInfo,
+} from "../../types/appointment";
+import { Currency } from "../../backoffice/types/static/pricing.types";
+import {
+  DocumentTemplate as AppDocumentTemplate,
+  FilledDocument,
+  FilledDocumentStatus,
+  USER_FORMS_SUBCOLLECTION,
+  DOCTOR_FORMS_SUBCOLLECTION,
+} from "../../types/documentation-templates";
+import { TechnologyDocumentationTemplate } from "../../backoffice/types/technology.types";
+import {
+  ClinicInfo,
+  PractitionerProfileInfo,
+  PatientProfileInfo,
+} from "../../types/profile";
+import { Category } from "../../backoffice/types/category.types";
+import { Subcategory } from "../../backoffice/types/subcategory.types";
+import { Technology } from "../../backoffice/types/technology.types";
+import { Product } from "../../backoffice/types/product.types";
+import {
+  CalendarEvent,
+  CalendarEventTime,
+  CalendarSyncStatus,
+  ProcedureInfo as CalendarProcedureInfo,
+  CALENDAR_COLLECTION,
+} from "../../types/calendar";
+import { DocumentManagerAdminService } from "../documentation-templates/document-manager.admin";
+import { LinkedFormInfo } from "../../types/appointment";
+import { TimestampUtils } from "../../utils/TimestampUtils";
+import { Logger } from "../logger";
+import {
+  Resource,
+  ResourceInstance,
+  ResourceCalendarEvent,
+  ResourceBookingInfo,
+  ResourceStatus,
+  RESOURCES_COLLECTION,
+  RESOURCE_INSTANCES_SUBCOLLECTION,
+  RESOURCE_CALENDAR_SUBCOLLECTION,
+} from "../../types/resource";
+
+/**
+ * Interface for the data required by orchestrateAppointmentCreation
+ */
+export interface OrchestrateAppointmentCreationData {
+  patientId: string;
+  procedureId: string;
+  appointmentStartTime: admin.firestore.Timestamp;
+  appointmentEndTime: admin.firestore.Timestamp;
+  patientNotes?: string | null;
+}
+
+/**
+ * Admin service for handling booking-related operations.
+ * This is the cloud-based implementation that will be used in Cloud Functions.
+ */
+export class BookingAdmin {
+  private db: admin.firestore.Firestore;
+  private documentManagerAdmin: DocumentManagerAdminService;
+
+  /**
+   * Creates a new BookingAdmin instance
+   * @param firestore - Firestore instance provided by the caller
+   */
+  constructor(firestore?: admin.firestore.Firestore) {
+    this.db = firestore || admin.firestore();
+    this.documentManagerAdmin = new DocumentManagerAdminService(this.db);
+  }
+
+  /**
+   * Gets available booking time slots for a specific clinic, practitioner, and procedure
+   *
+   * @param clinicId - ID of the clinic
+   * @param practitionerId - ID of the practitioner
+   * @param procedureId - ID of the procedure
+   * @param timeframe - Time range to check for availability
+   * @returns Promise resolving to an array of available booking slots
+   */
+  async getAvailableBookingSlots(
+    clinicId: string,
+    practitionerId: string,
+    procedureId: string,
+    timeframe: {
+      start: Date | admin.firestore.Timestamp;
+      end: Date | admin.firestore.Timestamp;
+    }
+  ): Promise<{ availableSlots: { start: admin.firestore.Timestamp }[] }> {
+    try {
+      Logger.info("[BookingAdmin] Starting availability calculation", {
+        clinicId,
+        practitionerId,
+        procedureId,
+        timeframeStart:
+          timeframe.start instanceof Date
+            ? timeframe.start.toISOString()
+            : timeframe.start.toDate().toISOString(),
+        timeframeEnd:
+          timeframe.end instanceof Date
+            ? timeframe.end.toISOString()
+            : timeframe.end.toDate().toISOString(),
+      });
+
+      // Convert timeframe dates to Firestore Timestamps if needed
+      const start =
+        timeframe.start instanceof Date
+          ? admin.firestore.Timestamp.fromDate(timeframe.start)
+          : timeframe.start;
+
+      const end =
+        timeframe.end instanceof Date
+          ? admin.firestore.Timestamp.fromDate(timeframe.end)
+          : timeframe.end;
+
+      // 1. Fetch clinic data
+      Logger.debug("[BookingAdmin] Fetching clinic data", { clinicId });
+      const clinicDoc = await this.db.collection("clinics").doc(clinicId).get();
+      if (!clinicDoc.exists) {
+        Logger.error("[BookingAdmin] Clinic not found", { clinicId });
+        throw new Error(`Clinic ${clinicId} not found`);
+      }
+      const clinic = clinicDoc.data() as unknown as Clinic;
+      Logger.debug("[BookingAdmin] Retrieved clinic data", {
+        clinicName: clinic.name,
+        clinicHasWorkingHours: !!clinic.workingHours,
+      });
+
+      // 2. Fetch practitioner data
+      Logger.debug("[BookingAdmin] Fetching practitioner data", {
+        practitionerId,
+      });
+      const practitionerDoc = await this.db
+        .collection("practitioners")
+        .doc(practitionerId)
+        .get();
+      if (!practitionerDoc.exists) {
+        Logger.error("[BookingAdmin] Practitioner not found", {
+          practitionerId,
+        });
+        throw new Error(`Practitioner ${practitionerId} not found`);
+      }
+      const practitioner = practitionerDoc.data() as unknown as Practitioner;
+      Logger.debug("[BookingAdmin] Retrieved practitioner data", {
+        practitionerName: `${practitioner.basicInfo.firstName} ${practitioner.basicInfo.lastName}`,
+        pracWorkingHoursCount: practitioner.clinicWorkingHours?.length || 0,
+      });
+
+      // 3. Fetch procedure data
+      Logger.debug("[BookingAdmin] Fetching procedure data", { procedureId });
+      const procedureDoc = await this.db
+        .collection("procedures")
+        .doc(procedureId)
+        .get();
+      if (!procedureDoc.exists) {
+        Logger.error("[BookingAdmin] Procedure not found", { procedureId });
+        throw new Error(`Procedure ${procedureId} not found`);
+      }
+      const procedure = procedureDoc.data() as unknown as Procedure;
+      Logger.debug("[BookingAdmin] Retrieved procedure data", {
+        procedureName: procedure.name,
+        procedureDuration: procedure.duration,
+      });
+
+      // 4. Fetch clinic calendar events
+      Logger.debug("[BookingAdmin] Fetching clinic calendar events", {
+        clinicId,
+        startTime: start.toDate().toISOString(),
+        endTime: end.toDate().toISOString(),
+      });
+      const clinicCalendarEvents = await this.getClinicCalendarEvents(
+        clinicId,
+        start,
+        end
+      );
+      Logger.debug("[BookingAdmin] Retrieved clinic calendar events", {
+        count: clinicCalendarEvents.length,
+      });
+
+      // 5. Fetch practitioner calendar events
+      Logger.debug("[BookingAdmin] Fetching practitioner calendar events", {
+        practitionerId,
+        startTime: start.toDate().toISOString(),
+        endTime: end.toDate().toISOString(),
+      });
+      const practitionerCalendarEvents =
+        await this.getPractitionerCalendarEvents(practitionerId, start, end);
+      Logger.debug("[BookingAdmin] Retrieved practitioner calendar events", {
+        count: practitionerCalendarEvents.length,
+      });
+
+      // 6. Fetch resource calendar events (if procedure requires resources)
+      let resourceCalendarEventsMap:
+        | BookingAvailabilityRequest["resourceCalendarEventsMap"]
+        | undefined;
+      if (
+        procedure.resourceRequirements &&
+        procedure.resourceRequirements.length > 0
+      ) {
+        Logger.debug(
+          "[BookingAdmin] Procedure has resource requirements, fetching resource data",
+          {
+            resourceRequirementCount: procedure.resourceRequirements.length,
+            resourceIds: procedure.resourceRequirements.map(
+              (r) => r.resourceId
+            ),
+          }
+        );
+
+        resourceCalendarEventsMap = {};
+
+        for (const requirement of procedure.resourceRequirements) {
+          // Fetch resource document
+          const resourceDoc = await this.db
+            .collection(CLINICS_COLLECTION)
+            .doc(clinicId)
+            .collection(RESOURCES_COLLECTION)
+            .doc(requirement.resourceId)
+            .get();
+
+          if (!resourceDoc.exists) {
+            Logger.warn(
+              "[BookingAdmin] Required resource not found, skipping",
+              {
+                resourceId: requirement.resourceId,
+                resourceName: requirement.resourceName,
+              }
+            );
+            continue;
+          }
+
+          const resource = resourceDoc.data() as Resource;
+          if (resource.status !== ResourceStatus.ACTIVE) {
+            Logger.warn(
+              "[BookingAdmin] Required resource is not active, skipping",
+              {
+                resourceId: requirement.resourceId,
+                resourceStatus: resource.status,
+              }
+            );
+            continue;
+          }
+
+          // Fetch all active instances
+          const instancesSnapshot = await this.db
+            .collection(CLINICS_COLLECTION)
+            .doc(clinicId)
+            .collection(RESOURCES_COLLECTION)
+            .doc(requirement.resourceId)
+            .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+            .where("status", "==", ResourceStatus.ACTIVE)
+            .get();
+
+          const instanceEvents: Record<string, ResourceCalendarEvent[]> = {};
+
+          for (const instanceDoc of instancesSnapshot.docs) {
+            const instanceId = instanceDoc.id;
+
+            // Fetch calendar events for this instance in the timeframe
+            const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000;
+            const queryStart = admin.firestore.Timestamp.fromMillis(
+              start.toMillis() - MAX_EVENT_DURATION_MS
+            );
+
+            const eventsSnapshot = await this.db
+              .collection(CLINICS_COLLECTION)
+              .doc(clinicId)
+              .collection(RESOURCES_COLLECTION)
+              .doc(requirement.resourceId)
+              .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+              .doc(instanceId)
+              .collection(RESOURCE_CALENDAR_SUBCOLLECTION)
+              .where("eventTime.start", ">=", queryStart)
+              .where("eventTime.start", "<=", end)
+              .orderBy("eventTime.start")
+              .get();
+
+            // Post-filter for overlapping events and convert timestamps
+            const events = eventsSnapshot.docs
+              .map((doc) => ({ ...doc.data(), id: doc.id } as any))
+              .filter(
+                (event: any) =>
+                  event.eventTime.end.toMillis() > start.toMillis()
+              );
+
+            // Convert admin timestamps to client timestamps
+            instanceEvents[instanceId] = this.convertEventsTimestamps(
+              events
+            ) as unknown as ResourceCalendarEvent[];
+          }
+
+          resourceCalendarEventsMap[requirement.resourceId] = {
+            resourceId: requirement.resourceId,
+            resourceName: requirement.resourceName,
+            quantity: resource.quantity,
+            instanceEvents,
+          };
+
+          Logger.debug("[BookingAdmin] Fetched resource calendar data", {
+            resourceId: requirement.resourceId,
+            resourceName: requirement.resourceName,
+            instanceCount: instancesSnapshot.size,
+            totalEvents: Object.values(instanceEvents).reduce(
+              (sum, events) => sum + events.length,
+              0
+            ),
+          });
+        }
+      }
+
+      // Since we're working with two different Timestamp implementations (admin vs client),
+      // we need to convert our timestamps to the client-side format expected by the calculator
+      // Create client Timestamp objects from admin Timestamp objects
+      const convertedTimeframe = {
+        start: this.adminTimestampToClientTimestamp(start),
+        end: this.adminTimestampToClientTimestamp(end),
+      };
+
+      // Create the request object for the calculator
+      const request: BookingAvailabilityRequest = {
+        clinic,
+        practitioner,
+        procedure,
+        timeframe: convertedTimeframe,
+        clinicCalendarEvents:
+          this.convertEventsTimestamps(clinicCalendarEvents),
+        practitionerCalendarEvents: this.convertEventsTimestamps(
+          practitionerCalendarEvents
+        ),
+        tz: clinic.location.tz || "UTC",
+        ...(resourceCalendarEventsMap && { resourceCalendarEventsMap }),
+      };
+
+      Logger.info("[BookingAdmin] Calling availability calculator", {
+        calculatorInputReady: true,
+        timeframeDurationHours: Math.round(
+          (end.toMillis() - start.toMillis()) / (1000 * 60 * 60)
+        ),
+        clinicEventsCount: clinicCalendarEvents.length,
+        practitionerEventsCount: practitionerCalendarEvents.length,
+        resourceRequirementCount:
+          procedure.resourceRequirements?.length || 0,
+        hasResourceData: !!resourceCalendarEventsMap,
+      });
+
+      // Use the calculator to compute available slots
+      const result = BookingAvailabilityCalculator.calculateSlots(request);
+
+      // Convert the client Timestamps to admin Timestamps before returning
+      const availableSlotsResult = {
+        availableSlots: result.availableSlots.map((slot) => ({
+          start: admin.firestore.Timestamp.fromMillis(slot.start.toMillis()),
+        })),
+      };
+
+      Logger.info(
+        "[BookingAdmin] Availability calculation completed successfully",
+        {
+          availableSlotsCount: availableSlotsResult.availableSlots.length,
+          firstSlotTime:
+            availableSlotsResult.availableSlots.length > 0
+              ? availableSlotsResult.availableSlots[0].start
+                  .toDate()
+                  .toISOString()
+              : "none",
+          lastSlotTime:
+            availableSlotsResult.availableSlots.length > 0
+              ? availableSlotsResult.availableSlots[
+                  availableSlotsResult.availableSlots.length - 1
+                ].start
+                  .toDate()
+                  .toISOString()
+              : "none",
+        }
+      );
+
+      return availableSlotsResult;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      Logger.error("[BookingAdmin] Error getting available slots", {
+        errorMessage,
+        clinicId,
+        practitionerId,
+        procedureId,
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Converts an admin Firestore Timestamp to a client Firestore Timestamp
+   */
+  private adminTimestampToClientTimestamp(
+    timestamp: admin.firestore.Timestamp
+  ): FirebaseClientTimestamp {
+    // Use TimestampUtils instead of custom implementation
+    return TimestampUtils.adminToClient(timestamp) as FirebaseClientTimestamp;
+  }
+
+  /**
+   * Converts timestamps in calendar events from admin Firestore Timestamps to client Firestore Timestamps
+   */
+  private convertEventsTimestamps(events: any[]): any[] {
+    return events.map((event) => ({
+      ...event,
+      eventTime: {
+        start: TimestampUtils.adminToClient(
+          event.eventTime.start
+        ) as FirebaseClientTimestamp,
+        end: TimestampUtils.adminToClient(
+          event.eventTime.end
+        ) as FirebaseClientTimestamp,
+      },
+      // Convert any other timestamps in the event if needed
+    }));
+  }
+
+  /**
+   * Fetches clinic calendar events for a specific time range
+   *
+   * @param clinicId - ID of the clinic
+   * @param start - Start time of the range
+   * @param end - End time of the range
+   * @returns Promise resolving to an array of calendar events
+   */
+  private async getClinicCalendarEvents(
+    clinicId: string,
+    start: admin.firestore.Timestamp,
+    end: admin.firestore.Timestamp
+  ): Promise<any[]> {
+    try {
+      Logger.debug("[BookingAdmin] Querying clinic calendar events", {
+        clinicId,
+        startTime: start.toDate().toISOString(),
+        endTime: end.toDate().toISOString(),
+      });
+
+      // Increased to 30 days to handle long blocking events (e.g., holidays, extended time off)
+      // This ensures we catch blocking events that start before our query range but overlap with it
+      const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000;
+      const queryStart = admin.firestore.Timestamp.fromMillis(
+        start.toMillis() - MAX_EVENT_DURATION_MS
+      );
+
+      // Query for events that:
+      // 1. Start before or during our query range (eventTime.start < end)
+      // 2. We'll post-filter to ensure they overlap (eventTime.end > start)
+      const eventsRef = this.db
+        .collection(`clinics/${clinicId}/calendar`)
+        .where("eventTime.start", ">=", queryStart)
+        .where("eventTime.start", "<=", end)
+        .orderBy("eventTime.start");
+
+      const snapshot = await eventsRef.get();
+
+      // Post-filter to ensure events actually overlap with our query range
+      // An event overlaps if: eventTime.start < queryEnd AND eventTime.end > queryStart
+      const events = snapshot.docs
+        .map((doc) => ({
+          ...doc.data(),
+          id: doc.id,
+        }))
+        .filter((event: any) => {
+          // Event overlaps if it ends after our start time
+          const overlaps = event.eventTime.end.toMillis() > start.toMillis();
+          if (!overlaps) {
+            Logger.debug("[BookingAdmin] Filtered out non-overlapping event", {
+              eventId: event.id,
+              eventStart: event.eventTime.start.toDate().toISOString(),
+              eventEnd: event.eventTime.end.toDate().toISOString(),
+              queryStart: start.toDate().toISOString(),
+              queryEnd: end.toDate().toISOString(),
+            });
+          }
+          return overlaps;
+        });
+
+      Logger.debug("[BookingAdmin] Retrieved clinic calendar events", {
+        clinicId,
+        eventsCount: events.length,
+        eventsTypes: this.summarizeEventTypes(events),
+        queryStartTime: queryStart.toDate().toISOString(),
+      });
+
+      return events;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      Logger.error("[BookingAdmin] Error fetching clinic calendar events", {
+        errorMessage,
+        clinicId,
+        startTime: start.toDate().toISOString(),
+        endTime: end.toDate().toISOString(),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+      return [];
+    }
+  }
+
+  /**
+   * Fetches practitioner calendar events for a specific time range
+   *
+   * @param practitionerId - ID of the practitioner
+   * @param start - Start time of the range
+   * @param end - End time of the range
+   * @returns Promise resolving to an array of calendar events
+   */
+  private async getPractitionerCalendarEvents(
+    practitionerId: string,
+    start: admin.firestore.Timestamp,
+    end: admin.firestore.Timestamp
+  ): Promise<any[]> {
+    try {
+      Logger.debug("[BookingAdmin] Querying practitioner calendar events", {
+        practitionerId,
+        startTime: start.toDate().toISOString(),
+        endTime: end.toDate().toISOString(),
+      });
+
+      // Increased to 30 days to handle long blocking events (e.g., holidays, extended time off)
+      // This ensures we catch blocking events that start before our query range but overlap with it
+      const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000;
+      const queryStart = admin.firestore.Timestamp.fromMillis(
+        start.toMillis() - MAX_EVENT_DURATION_MS
+      );
+
+      // Query for events that:
+      // 1. Start before or during our query range (eventTime.start <= end)
+      // 2. We'll post-filter to ensure they overlap (eventTime.end > start)
+      const eventsRef = this.db
+        .collection(`practitioners/${practitionerId}/calendar`)
+        .where("eventTime.start", ">=", queryStart)
+        .where("eventTime.start", "<=", end)
+        .orderBy("eventTime.start");
+
+      const snapshot = await eventsRef.get();
+
+      // Post-filter to ensure events actually overlap with our query range
+      // An event overlaps if: eventTime.start < queryEnd AND eventTime.end > queryStart
+      const events = snapshot.docs
+        .map((doc) => ({
+          ...doc.data(),
+          id: doc.id,
+        }))
+        .filter((event: any) => {
+          // Event overlaps if it ends after our start time
+          const overlaps = event.eventTime.end.toMillis() > start.toMillis();
+          if (!overlaps) {
+            Logger.debug("[BookingAdmin] Filtered out non-overlapping practitioner event", {
+              eventId: event.id,
+              eventStart: event.eventTime.start.toDate().toISOString(),
+              eventEnd: event.eventTime.end.toDate().toISOString(),
+              queryStart: start.toDate().toISOString(),
+              queryEnd: end.toDate().toISOString(),
+            });
+          }
+          return overlaps;
+        });
+
+      Logger.debug("[BookingAdmin] Retrieved practitioner calendar events", {
+        practitionerId,
+        eventsCount: events.length,
+        eventsTypes: this.summarizeEventTypes(events),
+        queryStartTime: queryStart.toDate().toISOString(),
+      });
+
+      return events;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      Logger.error(
+        "[BookingAdmin] Error fetching practitioner calendar events",
+        {
+          errorMessage,
+          practitionerId,
+          startTime: start.toDate().toISOString(),
+          endTime: end.toDate().toISOString(),
+          stack: error instanceof Error ? error.stack : undefined,
+        }
+      );
+      return [];
+    }
+  }
+
+  /**
+   * Summarizes event types for logging purposes
+   * @param events Array of calendar events
+   * @returns Object with counts of each event type
+   */
+  private summarizeEventTypes(events: any[]): Record<string, number> {
+    const typeCounts: Record<string, number> = {};
+
+    events.forEach((event) => {
+      const eventType = event.eventType || "unknown";
+      typeCounts[eventType] = (typeCounts[eventType] || 0) + 1;
+    });
+
+    return typeCounts;
+  }
+
+  private _generateCalendarProcedureInfo(
+    procedure: Procedure
+  ): CalendarProcedureInfo {
+    return {
+      name: procedure.name,
+      description: procedure.description,
+      duration: procedure.duration, // in minutes
+      price: procedure.price,
+      currency: procedure.currency,
+    };
+  }
+
+  /**
+   * Orchestrates the creation of a new appointment, including data aggregation.
+   * This method is intended to be called from a trusted backend environment (e.g., an Express route handler in a Cloud Function).
+   *
+   * @param data - Data required to create the appointment.
+   * @param authenticatedUserId - The ID of the user making the request (for auditing, and usually is the patientId).
+   * @returns Promise resolving to an object indicating success, and appointmentId or an error message.
+   */
+  async orchestrateAppointmentCreation(
+    data: OrchestrateAppointmentCreationData,
+    authenticatedUserId: string
+  ): Promise<{
+    success: boolean;
+    appointmentId?: string;
+    appointmentData?: Appointment;
+    calendarEventId?: string;
+    error?: string;
+  }> {
+    console.log(
+      `[BookingAdmin] Orchestrating appointment creation for patient ${data.patientId} by user ${authenticatedUserId}`
+    );
+    const batch = this.db.batch();
+    const adminTsNow = admin.firestore.Timestamp.now();
+    const serverTimestampValue = admin.firestore.FieldValue.serverTimestamp();
+
+    try {
+      // --- 1. Input Validation ---
+      if (
+        !data.patientId ||
+        !data.procedureId ||
+        !data.appointmentStartTime ||
+        !data.appointmentEndTime
+      ) {
+        return {
+          success: false,
+          error:
+            "Missing required fields: patientId, procedureId, appointmentStartTime, or appointmentEndTime.",
+        };
+      }
+      if (
+        data.appointmentEndTime.toMillis() <=
+        data.appointmentStartTime.toMillis()
+      ) {
+        return {
+          success: false,
+          error: "Appointment end time must be after start time.",
+        };
+      }
+      if (authenticatedUserId !== data.patientId) {
+        console.warn(
+          `[BookingAdmin] Authenticated user ${authenticatedUserId} is booking for a different patient ${data.patientId}. Review authorization if this is not intended.`
+        );
+      }
+
+      // --- 2. Fetch Core Procedure Data ---
+      const procedureRef = this.db
+        .collection(PROCEDURES_COLLECTION)
+        .doc(data.procedureId);
+      const procedureDoc = await procedureRef.get();
+      if (!procedureDoc.exists) {
+        return {
+          success: false,
+          error: `Procedure ${data.procedureId} not found.`,
+        };
+      }
+      const procedure = procedureDoc.data() as Procedure;
+
+      // --- 3. Fetch Clinic and then other Primary Documents ---
+      // Fetch clinic first to get its clinicGroupId
+      const clinicRef = this.db
+        .collection(CLINICS_COLLECTION)
+        .doc(procedure.clinicBranchId);
+      const clinicSnap = await clinicRef.get(); // Await here directly
+      if (!clinicSnap.exists) {
+        return {
+          success: false,
+          error: `Clinic ${procedure.clinicBranchId} not found.`,
+        };
+      }
+      const clinicData = clinicSnap.data() as Clinic; // Now clinicData is available
+
+      // Define other refs using clinicData for clinicGroupRef
+      const practitionerRef = this.db
+        .collection(PRACTITIONERS_COLLECTION)
+        .doc(procedure.practitionerId);
+      const patientProfileRef = this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(data.patientId);
+      const patientSensitiveRef = this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(data.patientId)
+        .collection(PATIENT_SENSITIVE_INFO_COLLECTION)
+        .doc(data.patientId);
+      const clinicGroupRef = this.db
+        .collection(CLINIC_GROUPS_COLLECTION)
+        .doc(clinicData.clinicGroupId); // Use clinicData here
+
+      const [
+        practitionerSnap,
+        patientProfileSnap,
+        patientSensitiveSnap,
+        clinicGroupSnap,
+      ] = await Promise.all([
+        // clinicRef.get() is already done via clinicSnap
+        practitionerRef.get(),
+        patientProfileRef.get(),
+        patientSensitiveRef.get(),
+        clinicGroupRef.get(), // Fetch the defined clinicGroupRef
+      ]);
+
+      if (!practitionerSnap.exists)
+        return {
+          success: false,
+          error: `Practitioner ${procedure.practitionerId} not found.`,
+        };
+      if (!patientProfileSnap.exists)
+        return {
+          success: false,
+          error: `PatientProfile ${data.patientId} not found.`,
+        };
+      if (!clinicGroupSnap.exists)
+        return {
+          success: false,
+          error: `ClinicGroup for clinic ${procedure.clinicBranchId} not found.`,
+        };
+
+      const practitionerData = practitionerSnap.data() as Practitioner;
+      const patientProfileData = patientProfileSnap.data() as PatientProfile;
+      const patientSensitiveData = patientSensitiveSnap.exists
+        ? (patientSensitiveSnap.data() as PatientSensitiveInfo)
+        : undefined;
+      const clinicGroupData = clinicGroupSnap.data() as ClinicGroup;
+
+      // --- 4. Determine initialStatus (based on clinic settings) ---
+      const autoConfirm = clinicGroupData.autoConfirmAppointments || false;
+      const initialAppointmentStatus = autoConfirm
+        ? AppointmentStatus.CONFIRMED
+        : AppointmentStatus.PENDING;
+      const initialCalendarEventStatus = autoConfirm
+        ? CalendarEventStatus.CONFIRMED
+        : CalendarEventStatus.PENDING;
+
+      // --- 5. Aggregate Information (Snapshots) ---
+      const clinicInfo: ClinicInfo = {
+        id: clinicSnap.id,
+        name: clinicData.name,
+        featuredPhoto:
+          (typeof clinicData.coverPhoto === "string"
+            ? clinicData.coverPhoto
+            : "") ||
+          (typeof clinicData.logo === "string" ? clinicData.logo : "") ||
+          "",
+        description: clinicData.description,
+        location: clinicData.location,
+        contactInfo: clinicData.contactInfo,
+      };
+      const practitionerInfo: PractitionerProfileInfo = {
+        id: practitionerSnap.id,
+        practitionerPhoto:
+          typeof practitionerData.basicInfo.profileImageUrl === "string"
+            ? practitionerData.basicInfo.profileImageUrl
+            : null,
+        name: `${practitionerData.basicInfo.firstName} ${practitionerData.basicInfo.lastName}`,
+        email: practitionerData.basicInfo.email,
+        phone: practitionerData.basicInfo.phoneNumber || null,
+        certification: practitionerData.certification,
+      };
+      const patientInfo: PatientProfileInfo = {
+        id: patientProfileSnap.id,
+        fullName:
+          `${patientSensitiveData?.firstName || ""} ${
+            patientSensitiveData?.lastName || ""
+          }`.trim() || patientProfileData.displayName,
+        email: patientSensitiveData?.email || "",
+        phone:
+          patientSensitiveData?.phoneNumber ||
+          patientProfileData.phoneNumber ||
+          null,
+        dateOfBirth:
+          patientSensitiveData?.dateOfBirth ||
+          patientProfileData.dateOfBirth ||
+          admin.firestore.Timestamp.now(),
+        gender: patientSensitiveData?.gender || Gender.OTHER,
+      };
+      // const procedureCategory = procedure.category as Category;
+      // const procedureSubCategory = procedure.subcategory as Subcategory;
+      // const procedureTechnology = procedure.technology as Technology;
+      // const procedureProduct = procedure.product as Product;
+
+      // const procedureExtendedInfo: ProcedureExtendedInfo = {
+      //   id: procedure.id,
+      //   name: procedure.name,
+      //   description: procedure.description,
+      //   cost: procedure.price,
+      //   duration: procedure.duration,
+      //   procedureFamily: procedure.family,
+      //   procedureCategoryId: procedureCategory?.id || "",
+      //   procedureCategoryName: procedureCategory?.name || "",
+      //   procedureSubCategoryId: procedureSubCategory?.id || "",
+      //   procedureSubCategoryName: procedureSubCategory?.name || "",
+      //   procedureTechnologyId: procedureTechnology?.id || "",
+      //   procedureTechnologyName: procedureTechnology?.name || "",
+      //   procedureProductBrandId: procedureProduct.brandId || "",
+      //   procedureProductBrandName: procedureProduct.brandName || "",
+      //   procedureProductId: procedureProduct.id || "",
+      //   procedureProductName: procedureProduct.name || "",
+      // };
+
+      // // --- 6. Determine pendingUserFormsIds and linkedFormIds ---
+      // let pendingUserFormsIds: string[] = [];
+      // let linkedFormIds: string[] = [];
+      // if (
+      //   procedure.documentationTemplates &&
+      //   Array.isArray(procedure.documentationTemplates)
+      // ) {
+      //   pendingUserFormsIds = procedure.documentationTemplates
+      //     .filter(
+      //       (template: TechnologyDocumentationTemplate) =>
+      //         template.isUserForm && template.isRequired
+      //     )
+      //     .map(
+      //       (template: TechnologyDocumentationTemplate) => template.templateId
+      //     );
+      //   linkedFormIds = procedure.documentationTemplates.map(
+      //     (template: TechnologyDocumentationTemplate) => template.templateId
+      //   );
+      // }
+
+      // --- 7. Construct New Appointment Object ---
+      const newAppointmentId = this.db
+        .collection(APPOINTMENTS_COLLECTION)
+        .doc().id;
+
+      const eventTimeForCalendarEvents: CalendarEventTime = {
+        start: data.appointmentStartTime as any,
+        end: data.appointmentEndTime as any,
+      };
+
+      // Practitioner Calendar Event
+      const practitionerCalendarEventId = this.db
+        .collection(PRACTITIONERS_COLLECTION)
+        .doc(practitionerData.id)
+        .collection(CALENDAR_COLLECTION)
+        .doc().id;
+      const practitionerCalendarEventData: CalendarEvent = {
+        id: practitionerCalendarEventId,
+        appointmentId: newAppointmentId,
+        clinicBranchId: clinicData.id,
+        clinicBranchInfo: clinicInfo,
+        practitionerProfileId: practitionerData.id,
+        practitionerProfileInfo: practitionerInfo,
+        patientProfileId: patientProfileData.id,
+        patientProfileInfo: patientInfo,
+        procedureId: procedure.id,
+        procedureInfo: this._generateCalendarProcedureInfo(procedure),
+        eventName: `Appointment: ${procedure.name} with ${patientInfo.fullName}`,
+        eventLocation: clinicData.location,
+        eventTime: eventTimeForCalendarEvents,
+        description: procedure.description || "",
+        status: initialCalendarEventStatus,
+        syncStatus: CalendarSyncStatus.INTERNAL,
+        eventType: CalendarEventType.APPOINTMENT,
+        createdAt: serverTimestampValue as any,
+        updatedAt: serverTimestampValue as any,
+      };
+      batch.set(
+        this.db
+          .collection(PRACTITIONERS_COLLECTION)
+          .doc(practitionerData.id)
+          .collection(CALENDAR_COLLECTION)
+          .doc(practitionerCalendarEventId),
+        practitionerCalendarEventData
+      );
+
+      // Patient Calendar Event
+      // Use same ID as practitionerCalendarEventId
+      const patientCalendarEventData: CalendarEvent = {
+        id: practitionerCalendarEventId,
+        appointmentId: newAppointmentId,
+        clinicBranchId: clinicData.id,
+        clinicBranchInfo: clinicInfo,
+        practitionerProfileId: practitionerData.id,
+        practitionerProfileInfo: practitionerInfo,
+        procedureId: procedure.id,
+        procedureInfo: this._generateCalendarProcedureInfo(procedure),
+        eventName: `Appointment: ${procedure.name} at ${clinicData.name}`,
+        eventLocation: clinicData.location,
+        eventTime: eventTimeForCalendarEvents,
+        description: data.patientNotes || "",
+        status: initialCalendarEventStatus,
+        syncStatus: CalendarSyncStatus.INTERNAL,
+        eventType: CalendarEventType.APPOINTMENT,
+        createdAt: serverTimestampValue as any,
+        updatedAt: serverTimestampValue as any,
+      };
+      batch.set(
+        this.db
+          .collection(PATIENTS_COLLECTION)
+          .doc(patientProfileData.id)
+          .collection(CALENDAR_COLLECTION)
+          .doc(practitionerCalendarEventId),
+        patientCalendarEventData
+      );
+
+      // Clinic Calendar Event
+      // Use same ID as practitionerCalendarEventId
+      const clinicCalendarEventData: CalendarEvent = {
+        id: practitionerCalendarEventId,
+        appointmentId: newAppointmentId,
+        clinicBranchId: clinicData.id,
+        clinicBranchInfo: clinicInfo,
+        practitionerProfileId: practitionerData.id,
+        practitionerProfileInfo: practitionerInfo,
+        patientProfileId: patientProfileData.id,
+        patientProfileInfo: patientInfo,
+        procedureId: procedure.id,
+        procedureInfo: this._generateCalendarProcedureInfo(procedure),
+        eventName: `Appointment: ${procedure.name} for ${patientInfo.fullName} with ${practitionerInfo.name}`,
+        eventLocation: clinicData.location,
+        eventTime: eventTimeForCalendarEvents,
+        description: data.patientNotes || "",
+        status: initialCalendarEventStatus,
+        syncStatus: CalendarSyncStatus.INTERNAL,
+        eventType: CalendarEventType.APPOINTMENT,
+        createdAt: serverTimestampValue as any,
+        updatedAt: serverTimestampValue as any,
+      };
+      batch.set(
+        this.db
+          .collection(CLINICS_COLLECTION)
+          .doc(clinicData.id)
+          .collection(CALENDAR_COLLECTION)
+          .doc(practitionerCalendarEventId),
+        clinicCalendarEventData
+      );
+
+      // --- Resource Allocation (if procedure requires resources) ---
+      let resourceBookings: ResourceBookingInfo[] = [];
+      if (
+        procedure.resourceRequirements &&
+        procedure.resourceRequirements.length > 0
+      ) {
+        console.log(
+          `[BookingAdmin] Allocating resources for appointment ${newAppointmentId}, ` +
+            `${procedure.resourceRequirements.length} resource(s) required`
+        );
+
+        for (const requirement of procedure.resourceRequirements) {
+          // Fetch all active instances of this resource, sorted by index
+          const instancesSnapshot = await this.db
+            .collection(CLINICS_COLLECTION)
+            .doc(clinicData.id)
+            .collection(RESOURCES_COLLECTION)
+            .doc(requirement.resourceId)
+            .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+            .where("status", "==", ResourceStatus.ACTIVE)
+            .orderBy("index")
+            .get();
+
+          if (instancesSnapshot.empty) {
+            return {
+              success: false,
+              error: `Resource "${requirement.resourceName}" has no active instances available.`,
+            };
+          }
+
+          let allocatedInstance: ResourceInstance | null = null;
+
+          for (const instanceDoc of instancesSnapshot.docs) {
+            const instance = {
+              ...instanceDoc.data(),
+              id: instanceDoc.id,
+            } as ResourceInstance;
+
+            // Check if this instance has overlapping active events during appointment time
+            const overlappingEventsSnapshot = await this.db
+              .collection(CLINICS_COLLECTION)
+              .doc(clinicData.id)
+              .collection(RESOURCES_COLLECTION)
+              .doc(requirement.resourceId)
+              .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+              .doc(instance.id)
+              .collection(RESOURCE_CALENDAR_SUBCOLLECTION)
+              .where("eventTime.start", "<", data.appointmentEndTime)
+              .where("status", "in", [
+                CalendarEventStatus.PENDING,
+                CalendarEventStatus.CONFIRMED,
+                CalendarEventStatus.CHECKED_IN,
+                CalendarEventStatus.IN_PROGRESS,
+              ])
+              .get();
+
+            // Post-filter: event must end after appointment start to truly overlap
+            const hasOverlap = overlappingEventsSnapshot.docs.some((doc) => {
+              const event = doc.data();
+              return (
+                event.eventTime.end.toMillis() >
+                data.appointmentStartTime.toMillis()
+              );
+            });
+
+            if (!hasOverlap) {
+              allocatedInstance = instance;
+              break;
+            }
+          }
+
+          if (!allocatedInstance) {
+            return {
+              success: false,
+              error: `Resource "${requirement.resourceName}" is not available at the selected time. All instances are booked.`,
+            };
+          }
+
+          // Create ResourceCalendarEvent on the allocated instance's calendar
+          const resourceCalendarEventRef = this.db
+            .collection(CLINICS_COLLECTION)
+            .doc(clinicData.id)
+            .collection(RESOURCES_COLLECTION)
+            .doc(requirement.resourceId)
+            .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+            .doc(allocatedInstance.id)
+            .collection(RESOURCE_CALENDAR_SUBCOLLECTION)
+            .doc();
+
+          const resourceCalendarEventData = {
+            id: resourceCalendarEventRef.id,
+            resourceId: requirement.resourceId,
+            resourceInstanceId: allocatedInstance.id,
+            clinicBranchId: clinicData.id,
+            eventType: CalendarEventType.RESOURCE_BOOKING,
+            appointmentId: newAppointmentId,
+            procedureId: procedure.id,
+            practitionerId: practitionerData.id,
+            patientId: data.patientId,
+            eventTime: eventTimeForCalendarEvents,
+            status: initialCalendarEventStatus,
+            eventName: `${procedure.name} - ${allocatedInstance.label}`,
+            createdAt: serverTimestampValue,
+            updatedAt: serverTimestampValue,
+          };
+
+          batch.set(resourceCalendarEventRef, resourceCalendarEventData);
+
+          resourceBookings.push({
+            resourceId: requirement.resourceId,
+            resourceName: requirement.resourceName,
+            resourceInstanceId: allocatedInstance.id,
+            resourceInstanceLabel: allocatedInstance.label,
+            calendarEventId: resourceCalendarEventRef.id,
+          });
+
+          console.log(
+            `[BookingAdmin] Allocated resource "${requirement.resourceName}" → ` +
+              `instance "${allocatedInstance.label}" (${allocatedInstance.id})`
+          );
+        }
+      }
+
+      // --- Initialize Pending/Draft Filled Documents and get form IDs ---
+      let initializedFormsInfo: LinkedFormInfo[] = [];
+      let pendingUserFormTemplateIds: string[] = [];
+      let allLinkedFormTemplateIds: string[] = [];
+
+      if (
+        procedure.documentationTemplates &&
+        Array.isArray(procedure.documentationTemplates) &&
+        procedure.documentationTemplates.length > 0
+      ) {
+        const formInitResult =
+          await this.documentManagerAdmin.batchInitializeAppointmentFormsFromTechnologyTemplates(
+            batch,
+            newAppointmentId,
+            procedure.id, // Pass the actual procedureId for the forms
+            procedure.documentationTemplates,
+            data.patientId,
+            procedure.practitionerId,
+            procedure.clinicBranchId,
+            adminTsNow.toMillis()
+          );
+        initializedFormsInfo = formInitResult.initializedFormsInfo;
+        pendingUserFormTemplateIds = formInitResult.pendingUserFormsIds;
+        allLinkedFormTemplateIds = formInitResult.allLinkedTemplateIds;
+      }
+
+      // --- Generate appointment products from procedure ---
+      const appointmentProducts = this._generateAppointmentProductsFromProcedure(procedure);
+
+      // --- Construct Appointment Object ---
+      const newAppointmentData: Appointment = {
+        id: newAppointmentId,
+        calendarEventId: practitionerCalendarEventId,
+        clinicBranchId: procedure.clinicBranchId,
+        clinicInfo,
+        clinic_tz: clinicData.location.tz || "UTC",
+        practitionerId: procedure.practitionerId,
+        practitionerInfo,
+        patientId: data.patientId,
+        patientInfo,
+        procedureId: data.procedureId,
+        procedureInfo: this._generateProcedureSummaryInfo(
+          procedure,
+          clinicData,
+          practitionerData
+        ),
+        procedureExtendedInfo: this._generateProcedureExtendedInfo(procedure),
+        status: initialAppointmentStatus,
+        bookingTime: adminTsNow as any,
+        confirmationTime:
+          initialAppointmentStatus === AppointmentStatus.CONFIRMED
+            ? (adminTsNow as any)
+            : null,
+        appointmentStartTime: data.appointmentStartTime as any,
+        appointmentEndTime: data.appointmentEndTime as any,
+        cost: procedure.price,
+        currency: procedure.currency,
+        paymentStatus:
+          procedure.price > 0
+            ? PaymentStatus.UNPAID
+            : PaymentStatus.NOT_APPLICABLE,
+        patientNotes: data.patientNotes || null,
+        blockingConditions: procedure.blockingConditions || [],
+        contraindications: (procedure as any).contraindications || [],
+        preProcedureRequirements: procedure.preRequirements || [],
+        postProcedureRequirements: procedure.postRequirements || [],
+        pendingUserFormsIds: pendingUserFormTemplateIds,
+        linkedFormIds: allLinkedFormTemplateIds,
+        completedPreRequirements: [],
+        completedPostRequirements: [],
+        linkedForms: initializedFormsInfo,
+        media: [],
+        reviewInfo: null,
+        metadata: {
+          selectedZones: null,
+          zonePhotos: null,
+          zonesData: null,
+          appointmentProducts: appointmentProducts,
+          extendedProcedures: [],
+          recommendedProcedures: [],
+          finalbilling: null,
+          finalizationNotes: null,
+        },
+        finalizedDetails: {
+          by: "",
+          at: adminTsNow as any,
+          notes: "",
+        },
+        internalNotes: null,
+        cancellationReason: null,
+        cancellationTime: null,
+        canceledBy: undefined,
+        rescheduleTime: null,
+        procedureActualStartTime: null,
+        actualDurationMinutes: undefined,
+        isRecurring: false,
+        recurringAppointmentId: null,
+        isArchived: false,
+        ...(resourceBookings.length > 0 && { resourceBookings }),
+        createdAt: adminTsNow as any,
+        updatedAt: adminTsNow as any,
+      };
+
+      batch.set(
+        this.db.collection(APPOINTMENTS_COLLECTION).doc(newAppointmentId),
+        newAppointmentData
+      );
+
+      // Commit Batch
+      await batch.commit();
+
+      console.log(
+        `[BookingAdmin] Appointment ${newAppointmentId} and associated calendar events created successfully.`
+      );
+      return {
+        success: true,
+        appointmentId: newAppointmentId,
+        appointmentData: newAppointmentData,
+        calendarEventId: practitionerCalendarEventId,
+      };
+    } catch (error) {
+      console.error(
+        "[BookingAdmin] Critical error in orchestrateAppointmentCreation:",
+        error
+      );
+      const errorMessage =
+        error instanceof Error
+          ? error.message
+          : "Unknown server error during appointment creation.";
+      return { success: false, error: errorMessage };
+    }
+  }
+
+  private _generateProcedureSummaryInfo(
+    procedure: Procedure,
+    clinicData: Clinic,
+    practitionerData: Practitioner
+  ): ProcedureSummaryInfo {
+    const procedureCategory = procedure.category as Category;
+    const procedureSubCategory = procedure.subcategory as Subcategory;
+    const procedureTechnology = procedure.technology as Technology;
+    const procedureProduct = procedure.product as Product;
+    return {
+      id: procedure.id,
+      name: procedure.name,
+      description: procedure.description,
+      family: procedure.family,
+      categoryName: procedureCategory?.name || "",
+      subcategoryName: procedureSubCategory?.name || "",
+      technologyName: procedureTechnology?.name || "",
+      price: procedure.price,
+      pricingMeasure: procedure.pricingMeasure,
+      currency: procedure.currency,
+      duration: procedure.duration,
+      clinicId: procedure.clinicBranchId,
+      clinicName: clinicData.name,
+      practitionerId: procedure.practitionerId,
+      practitionerName: `${practitionerData.basicInfo.firstName} ${practitionerData.basicInfo.lastName}`,
+      photo:
+        (procedureTechnology as any)?.photos?.[0]?.url ||
+        (procedureProduct as any)?.photos?.[0]?.url ||
+        "",
+      brandName: (procedureProduct as any)?.brand?.name || "",
+      productName: procedureProduct?.name || "",
+    };
+  }
+
+  private _generateProcedureExtendedInfo(
+    procedure: Procedure
+  ): ProcedureExtendedInfo {
+    const procedureCategory = procedure.category as Category;
+    const procedureSubCategory = procedure.subcategory as Subcategory;
+    const procedureTechnology = procedure.technology as Technology;
+    const procedureProduct = procedure.product as Product;
+    const productsMetadata = procedure.productsMetadata || [];
+    
+    return {
+      id: procedure.id,
+      name: procedure.name,
+      description: procedure.description,
+      cost: procedure.price,
+      duration: procedure.duration,
+      procedureFamily: procedure.family,
+      procedureCategoryId: procedureCategory?.id || "",
+      procedureCategoryName: procedureCategory?.name || "",
+      procedureSubCategoryId: procedureSubCategory?.id || "",
+      procedureSubCategoryName: procedureSubCategory?.name || "",
+      procedureTechnologyId: procedureTechnology?.id || "",
+      procedureTechnologyName: procedureTechnology?.name || "",
+      procedureProductBrandId: procedureProduct?.brandId || "",
+      procedureProductBrandName: procedureProduct?.brandName || "",
+      procedureProducts: productsMetadata
+        .filter((pp: any) => pp && pp.product) // Safety check for product-free procedures
+        .map((pp: any) => ({
+        productId: pp.product.id,
+        productName: pp.product.name,
+        brandId: pp.product.brandId,
+        brandName: pp.product.brandName,
+      })),
+    };
+  }
+
+  private _generateAppointmentProductsFromProcedure(procedure: Procedure): any[] {
+    const productsMetadata = procedure.productsMetadata || [];
+    
+    return productsMetadata
+      .filter((pp: any) => pp && pp.product) // Safety check for product-free procedures
+      .map((pp: any) => {
+      const product = pp.product;
+      return {
+        productId: product.id,
+        productName: product.name,
+        brandId: product.brandId,
+        brandName: product.brandName,
+        procedureId: procedure.id,
+        price: pp.price,
+        currency: pp.currency,
+        unitOfMeasurement: pp.pricingMeasure,
+      };
+    });
+  }
+}