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

package/src/services/calendar/calendar.v2.service.ts

@@ -1,1693 +1,1693 @@
-import { Auth } from "firebase/auth";
-import { Firestore, Timestamp, serverTimestamp } from "firebase/firestore";
-import { FirebaseApp } from "firebase/app";
-import { BaseService } from "../base.service";
-import {
-  CalendarEvent,
-  CalendarEventStatus,
-  CalendarEventTime,
-  CalendarEventType,
-  CalendarSyncStatus,
-  CreateCalendarEventData,
-  UpdateCalendarEventData,
-  CALENDAR_COLLECTION,
-  SyncedCalendarEvent,
-  ProcedureInfo,
-  TimeSlot,
-  CreateAppointmentParams,
-  UpdateAppointmentParams,
-  SearchCalendarEventsParams,
-  SearchLocationEnum,
-  DateRange,
-} from "../../types/calendar";
-import {
-  PRACTITIONERS_COLLECTION,
-  PractitionerClinicWorkingHours,
-} from "../../types/practitioner";
-import {
-  PATIENTS_COLLECTION,
-  Gender,
-  PATIENT_SENSITIVE_INFO_COLLECTION,
-} from "../../types/patient";
-import { CLINICS_COLLECTION } from "../../types/clinic";
-import { SyncedCalendarProvider } from "../../types/calendar/synced-calendar.types";
-import {
-  ClinicInfo,
-  PatientProfileInfo,
-  PractitionerProfileInfo,
-} from "../../types/profile";
-import {
-  doc,
-  getDoc,
-  collection,
-  query,
-  where,
-  getDocs,
-  setDoc,
-  updateDoc,
-  QueryConstraint,
-  CollectionReference,
-  DocumentData,
-} from "firebase/firestore";
-import {
-  createAppointmentSchema,
-  updateAppointmentSchema,
-} from "../../validations/appointment.schema";
-
-// Import utility functions
-import {
-  createAppointmentUtil,
-  updateAppointmentUtil,
-  deleteAppointmentUtil,
-} from "./utils/appointment.utils";
-import { searchCalendarEventsUtil } from "./utils/calendar-event.utils";
-import { SyncedCalendarsService } from "./synced-calendars.service";
-import { Timestamp as FirestoreTimestamp } from "firebase-admin/firestore";
-
-/**
- * Minimum appointment duration in minutes
- */
-const MIN_APPOINTMENT_DURATION = 15;
-
-/**
- * Refactored Calendar Service
- * Provides streamlined calendar management with proper access control and scheduling rules
- */
-export class CalendarServiceV2 extends BaseService {
-  private syncedCalendarsService: SyncedCalendarsService;
-
-  /**
-   * Creates a new CalendarService instance
-   * @param db - Firestore instance
-   * @param auth - Firebase Auth instance
-   * @param app - Firebase App instance
-   */
-  constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
-    super(db, auth, app);
-    this.syncedCalendarsService = new SyncedCalendarsService(db, auth, app);
-  }
-
-  // #region Public API Methods
-
-  /**
-   * Creates a new appointment with proper validation and scheduling rules
-   * @param params - Appointment creation parameters
-   * @returns Created calendar event
-   */
-  async createAppointment(
-    params: CreateAppointmentParams
-  ): Promise<CalendarEvent> {
-    // Validate input parameters
-    await this.validateAppointmentParams(params);
-
-    // Check clinic working hours
-    await this.validateClinicWorkingHours(params.clinicId, params.eventTime);
-
-    // Check doctor availability
-    await this.validateDoctorAvailability(
-      params.doctorId,
-      params.eventTime,
-      params.clinicId
-    );
-
-    // Fetch profile info cards
-    const { clinicInfo, practitionerInfo, patientInfo } =
-      await this.fetchProfileInfoCards(
-        params.clinicId,
-        params.doctorId,
-        params.patientId
-      );
-
-    // Create the appointment
-    const appointmentData: Omit<
-      CreateCalendarEventData,
-      "id" | "createdAt" | "updatedAt"
-    > = {
-      clinicBranchId: params.clinicId,
-      clinicBranchInfo: clinicInfo,
-      practitionerProfileId: params.doctorId,
-      practitionerProfileInfo: practitionerInfo,
-      patientProfileId: params.patientId,
-      patientProfileInfo: patientInfo,
-      procedureId: params.procedureId,
-      eventLocation: params.eventLocation,
-      eventName: "Appointment", // TODO: Add procedure name when procedure model is available
-      eventTime: params.eventTime,
-      description: params.description || "",
-      status: CalendarEventStatus.PENDING,
-      syncStatus: CalendarSyncStatus.INTERNAL,
-      eventType: CalendarEventType.APPOINTMENT,
-    };
-
-    const appointment = await createAppointmentUtil(
-      this.db,
-      params.clinicId,
-      params.doctorId,
-      params.patientId,
-      appointmentData,
-      this.generateId.bind(this)
-    );
-
-    // Sync with external calendars if needed
-    await this.syncAppointmentWithExternalCalendars(appointment);
-
-    return appointment;
-  }
-
-  /**
-   * Updates an existing appointment
-   * @param params - Appointment update parameters
-   * @returns Updated calendar event
-   */
-  async updateAppointment(
-    params: UpdateAppointmentParams
-  ): Promise<CalendarEvent> {
-    // Validate permissions
-    await this.validateUpdatePermissions(params);
-
-    const updateData: Omit<UpdateCalendarEventData, "updatedAt"> = {
-      eventTime: params.eventTime,
-      description: params.description,
-      status: params.status,
-    };
-
-    const appointment = await updateAppointmentUtil(
-      this.db,
-      params.clinicId,
-      params.doctorId,
-      params.patientId,
-      params.appointmentId,
-      updateData
-    );
-
-    // Sync with external calendars if needed
-    await this.syncAppointmentWithExternalCalendars(appointment);
-
-    return appointment;
-  }
-
-  /**
-   * Gets available appointment slots for a doctor at a clinic
-   * @param clinicId - ID of the clinic
-   * @param doctorId - ID of the doctor
-   * @param date - Date to check availability for
-   * @returns Array of available time slots
-   */
-  async getAvailableSlots(
-    clinicId: string,
-    doctorId: string,
-    date: Date
-  ): Promise<TimeSlot[]> {
-    // Get clinic working hours
-    const workingHours = await this.getClinicWorkingHours(clinicId, date);
-
-    // Get doctor's schedule
-    const doctorSchedule = await this.getDoctorSchedule(doctorId, date);
-
-    // Get existing appointments
-    const existingAppointments = await this.getDoctorAppointments(
-      doctorId,
-      date
-    );
-
-    // Calculate available slots
-    return this.calculateAvailableSlots(
-      workingHours,
-      doctorSchedule,
-      existingAppointments
-    );
-  }
-
-  /**
-   * Confirms an appointment
-   * @param appointmentId - ID of the appointment
-   * @param clinicId - ID of the clinic
-   * @returns Confirmed calendar event
-   */
-  async confirmAppointment(
-    appointmentId: string,
-    clinicId: string
-  ): Promise<CalendarEvent> {
-    return this.updateAppointmentStatus(
-      appointmentId,
-      clinicId,
-      CalendarEventStatus.CONFIRMED
-    );
-  }
-
-  /**
-   * Rejects an appointment
-   * @param appointmentId - ID of the appointment
-   * @param clinicId - ID of the clinic
-   * @returns Rejected calendar event
-   */
-  async rejectAppointment(
-    appointmentId: string,
-    clinicId: string
-  ): Promise<CalendarEvent> {
-    return this.updateAppointmentStatus(
-      appointmentId,
-      clinicId,
-      CalendarEventStatus.REJECTED
-    );
-  }
-
-  /**
-   * Cancels an appointment
-   * @param appointmentId - ID of the appointment
-   * @param clinicId - ID of the clinic
-   * @returns Canceled calendar event
-   */
-  async cancelAppointment(
-    appointmentId: string,
-    clinicId: string
-  ): Promise<CalendarEvent> {
-    return this.updateAppointmentStatus(
-      appointmentId,
-      clinicId,
-      CalendarEventStatus.CANCELED
-    );
-  }
-
-  /**
-   * Imports events from external calendars
-   * @param entityType - Type of entity (practitioner or patient)
-   * @param entityId - ID of the entity
-   * @param startDate - Start date for fetching events
-   * @param endDate - End date for fetching events
-   * @returns Number of events imported
-   */
-  async importEventsFromExternalCalendars(
-    entityType: "doctor" | "patient",
-    entityId: string,
-    startDate: Date,
-    endDate: Date
-  ): Promise<number> {
-    // Only practitioners (doctors) should sync two-way
-    // Patients only sync outwards (from our system to external calendars)
-    if (entityType === "patient") {
-      return 0;
-    }
-
-    // For doctors, get their synced calendars
-    const syncedCalendars =
-      await this.syncedCalendarsService.getPractitionerSyncedCalendars(
-        entityId
-      );
-
-    // Filter active calendars
-    const activeCalendars = syncedCalendars.filter((cal) => cal.isActive);
-
-    if (activeCalendars.length === 0) {
-      return 0;
-    }
-
-    let importedEventsCount = 0;
-    const currentTime = Timestamp.now();
-
-    // Import from each calendar
-    for (const calendar of activeCalendars) {
-      try {
-        let externalEvents: any[] = [];
-
-        // Fetch events based on provider and entity type
-        if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
-          externalEvents =
-            await this.syncedCalendarsService.fetchEventsFromPractitionerGoogleCalendar(
-              entityId,
-              calendar.id,
-              startDate,
-              endDate
-            );
-        }
-        // Add other providers as needed
-
-        // Process and import each event
-        for (const externalEvent of externalEvents) {
-          try {
-            // Convert the external event to our format
-            const convertedEvent =
-              this.syncedCalendarsService.convertGoogleEventsToPractitionerEvents(
-                entityId,
-                [externalEvent]
-              )[0];
-
-            // Skip events without valid time data
-            if (!convertedEvent.eventTime) {
-              continue;
-            }
-
-            // Create event data from external event
-            const eventData: Omit<
-              CreateCalendarEventData,
-              "id" | "createdAt" | "updatedAt"
-            > = {
-              // Ensure all required fields are set
-              eventName: convertedEvent.eventName || "External Event",
-              eventTime: convertedEvent.eventTime,
-              description: convertedEvent.description || "",
-              status: CalendarEventStatus.CONFIRMED,
-              syncStatus: CalendarSyncStatus.EXTERNAL,
-              eventType: CalendarEventType.BLOCKING,
-              practitionerProfileId: entityId,
-              syncedCalendarEventId: [
-                {
-                  eventId: externalEvent.id,
-                  syncedCalendarProvider: calendar.provider,
-                  syncedAt: currentTime,
-                },
-              ],
-            };
-
-            // Create the event in the doctor's calendar
-            const doctorEvent = await this.createDoctorBlockingEvent(
-              entityId,
-              eventData
-            );
-
-            if (doctorEvent) {
-              importedEventsCount++;
-            }
-          } catch (eventError) {
-            console.error("Error importing event:", eventError);
-            // Continue with other events even if one fails
-          }
-        }
-      } catch (calendarError) {
-        console.error(
-          `Error fetching events from calendar ${calendar.id}:`,
-          calendarError
-        );
-        // Continue with other calendars even if one fails
-      }
-    }
-
-    return importedEventsCount;
-  }
-
-  /**
-   * Creates a blocking event in a doctor's calendar
-   * @param doctorId - ID of the doctor
-   * @param eventData - Calendar event data
-   * @returns Created calendar event
-   */
-  private async createDoctorBlockingEvent(
-    doctorId: string,
-    eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">
-  ): Promise<CalendarEvent | null> {
-    try {
-      // Generate a unique ID for the event
-      const eventId = this.generateId();
-
-      // Create the event document reference
-      const eventRef = doc(
-        this.db,
-        PRACTITIONERS_COLLECTION,
-        doctorId,
-        CALENDAR_COLLECTION,
-        eventId
-      );
-
-      // Prepare the event data
-      const newEvent: CreateCalendarEventData = {
-        id: eventId,
-        ...eventData,
-        createdAt: serverTimestamp(),
-        updatedAt: serverTimestamp(),
-      };
-
-      // Set the document
-      await setDoc(eventRef, newEvent);
-
-      // Return the event
-      return {
-        ...newEvent,
-        createdAt: Timestamp.now(),
-        updatedAt: Timestamp.now(),
-      } as CalendarEvent;
-    } catch (error) {
-      console.error(
-        `Error creating blocking event for doctor ${doctorId}:`,
-        error
-      );
-      return null;
-    }
-  }
-
-  /**
-   * Periodically syncs events from external calendars for doctors
-   * This would be called via a scheduled Cloud Function
-   * @param lookbackDays - Number of days to look back for events
-   * @param lookforwardDays - Number of days to look forward for events
-   */
-  async synchronizeExternalCalendars(
-    lookbackDays: number = 7,
-    lookforwardDays: number = 30
-  ): Promise<void> {
-    try {
-      // Get all doctors who have active synced calendars
-      const practitionersRef = collection(this.db, PRACTITIONERS_COLLECTION);
-      const practitionersSnapshot = await getDocs(practitionersRef);
-
-      // Prepare date range
-      const startDate = new Date();
-      startDate.setDate(startDate.getDate() - lookbackDays);
-
-      const endDate = new Date();
-      endDate.setDate(endDate.getDate() + lookforwardDays);
-
-      // For each doctor, check their synced calendars
-      const syncPromises = [];
-      for (const docSnapshot of practitionersSnapshot.docs) {
-        const practitionerId = docSnapshot.id;
-
-        // Import events from external calendars
-        syncPromises.push(
-          this.importEventsFromExternalCalendars(
-            "doctor",
-            practitionerId,
-            startDate,
-            endDate
-          )
-            .then((count) => {
-              console.log(
-                `Imported ${count} events for doctor ${practitionerId}`
-              );
-            })
-            .catch((error) => {
-              console.error(
-                `Error importing events for doctor ${practitionerId}:`,
-                error
-              );
-            })
-        );
-
-        // Also update existing events that might have changed
-        syncPromises.push(
-          this.updateExistingEventsFromExternalCalendars(
-            practitionerId,
-            startDate,
-            endDate
-          )
-            .then((count) => {
-              console.log(
-                `Updated ${count} events for doctor ${practitionerId}`
-              );
-            })
-            .catch((error) => {
-              console.error(
-                `Error updating events for doctor ${practitionerId}:`,
-                error
-              );
-            })
-        );
-      }
-
-      // Wait for all sync operations to complete
-      await Promise.all(syncPromises);
-      console.log("Completed external calendar synchronization");
-    } catch (error) {
-      console.error("Error synchronizing external calendars:", error);
-    }
-  }
-
-  /**
-   * Updates existing events that were synced from external calendars
-   * @param doctorId - ID of the doctor
-   * @param startDate - Start date for fetching events
-   * @param endDate - End date for fetching events
-   * @returns Number of events updated
-   */
-  private async updateExistingEventsFromExternalCalendars(
-    doctorId: string,
-    startDate: Date,
-    endDate: Date
-  ): Promise<number> {
-    try {
-      // Get all EXTERNAL events for this doctor within the date range
-      const eventsRef = collection(
-        this.db,
-        PRACTITIONERS_COLLECTION,
-        doctorId,
-        CALENDAR_COLLECTION
-      );
-      const q = query(
-        eventsRef,
-        where("syncStatus", "==", CalendarSyncStatus.EXTERNAL),
-        where("eventTime.start", ">=", Timestamp.fromDate(startDate)),
-        where("eventTime.start", "<=", Timestamp.fromDate(endDate))
-      );
-
-      const eventsSnapshot = await getDocs(q);
-      const events = eventsSnapshot.docs.map((doc) => ({
-        id: doc.id,
-        ...doc.data(),
-      })) as CalendarEvent[];
-
-      // Get the doctor's synced calendars
-      const calendars =
-        await this.syncedCalendarsService.getPractitionerSyncedCalendars(
-          doctorId
-        );
-      const activeCalendars = calendars.filter((cal) => cal.isActive);
-
-      if (activeCalendars.length === 0 || events.length === 0) {
-        return 0;
-      }
-
-      let updatedCount = 0;
-
-      // For each external event, check if it needs updating
-      for (const event of events) {
-        // Skip events without sync IDs
-        if (!event.syncedCalendarEventId?.length) continue;
-
-        for (const syncId of event.syncedCalendarEventId) {
-          // Find the calendar for this sync ID
-          const calendar = activeCalendars.find(
-            (cal) => cal.provider === syncId.syncedCalendarProvider
-          );
-          if (!calendar) continue;
-
-          // Check if the event exists and needs updating
-          if (syncId.syncedCalendarProvider === SyncedCalendarProvider.GOOGLE) {
-            try {
-              // Fetch the external event
-              const externalEvent = await this.fetchExternalEvent(
-                doctorId,
-                calendar,
-                syncId.eventId
-              );
-
-              // If the event was found, check if it's different from our local copy
-              if (externalEvent) {
-                // Compare basic properties (time, title, description)
-                const externalStartTime = new Date(
-                  externalEvent.start.dateTime || externalEvent.start.date
-                ).getTime();
-                const externalEndTime = new Date(
-                  externalEvent.end.dateTime || externalEvent.end.date
-                ).getTime();
-                const localStartTime = event.eventTime.start.toDate().getTime();
-                const localEndTime = event.eventTime.end.toDate().getTime();
-
-                // If times or title/description have changed, update our local copy
-                if (
-                  externalStartTime !== localStartTime ||
-                  externalEndTime !== localEndTime ||
-                  externalEvent.summary !== event.eventName ||
-                  externalEvent.description !== event.description
-                ) {
-                  // Update our local copy
-                  await this.updateLocalEventFromExternal(
-                    doctorId,
-                    event.id,
-                    externalEvent
-                  );
-                  updatedCount++;
-                }
-              } else {
-                // The event was deleted in the external calendar, mark it as canceled
-                await this.updateEventStatus(
-                  doctorId,
-                  event.id,
-                  CalendarEventStatus.CANCELED
-                );
-                updatedCount++;
-              }
-            } catch (error) {
-              console.error(
-                `Error updating external event ${event.id}:`,
-                error
-              );
-            }
-          }
-        }
-      }
-
-      return updatedCount;
-    } catch (error) {
-      console.error(
-        "Error updating existing events from external calendars:",
-        error
-      );
-      return 0;
-    }
-  }
-
-  /**
-   * Fetches a single external event from Google Calendar
-   * @param doctorId - ID of the doctor
-   * @param calendar - Calendar information
-   * @param externalEventId - ID of the external event
-   * @returns External event data or null if not found
-   */
-  private async fetchExternalEvent(
-    doctorId: string,
-    calendar: any,
-    externalEventId: string
-  ): Promise<any | null> {
-    try {
-      if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
-        // Refresh token if needed
-        // We're using the syncPractitionerEventsToGoogleCalendar to get the calendar with a refreshed token
-        const result =
-          await this.syncedCalendarsService.fetchEventFromPractitionerGoogleCalendar(
-            doctorId,
-            calendar.id,
-            externalEventId
-          );
-
-        return result;
-      }
-      return null;
-    } catch (error) {
-      console.error(`Error fetching external event ${externalEventId}:`, error);
-      return null;
-    }
-  }
-
-  /**
-   * Updates a local event with data from an external event
-   * @param doctorId - ID of the doctor
-   * @param eventId - ID of the local event
-   * @param externalEvent - External event data
-   */
-  private async updateLocalEventFromExternal(
-    doctorId: string,
-    eventId: string,
-    externalEvent: any
-  ): Promise<void> {
-    try {
-      // Create event time from external event
-      const startTime = new Date(
-        externalEvent.start.dateTime || externalEvent.start.date
-      );
-      const endTime = new Date(
-        externalEvent.end.dateTime || externalEvent.end.date
-      );
-
-      // Update the local event
-      const eventRef = doc(
-        this.db,
-        PRACTITIONERS_COLLECTION,
-        doctorId,
-        CALENDAR_COLLECTION,
-        eventId
-      );
-
-      await updateDoc(eventRef, {
-        eventName: externalEvent.summary || "External Event",
-        eventTime: {
-          start: Timestamp.fromDate(startTime),
-          end: Timestamp.fromDate(endTime),
-        },
-        description: externalEvent.description || "",
-        updatedAt: serverTimestamp(),
-      });
-
-      console.log(`Updated local event ${eventId} from external event`);
-    } catch (error) {
-      console.error(
-        `Error updating local event ${eventId} from external:`,
-        error
-      );
-    }
-  }
-
-  /**
-   * Updates an event's status
-   * @param doctorId - ID of the doctor
-   * @param eventId - ID of the event
-   * @param status - New status
-   */
-  private async updateEventStatus(
-    doctorId: string,
-    eventId: string,
-    status: CalendarEventStatus
-  ): Promise<void> {
-    try {
-      const eventRef = doc(
-        this.db,
-        PRACTITIONERS_COLLECTION,
-        doctorId,
-        CALENDAR_COLLECTION,
-        eventId
-      );
-
-      await updateDoc(eventRef, {
-        status,
-        updatedAt: serverTimestamp(),
-      });
-
-      console.log(`Updated event ${eventId} status to ${status}`);
-    } catch (error) {
-      console.error(`Error updating event ${eventId} status:`, error);
-    }
-  }
-
-  /**
-   * Creates a scheduled job to periodically sync external calendars
-   * Note: This would be implemented using Cloud Functions in a real application
-   * This is a sample implementation to show how it could be set up
-   * @param interval - Interval in hours
-   */
-  createScheduledSyncJob(interval: number = 3): void {
-    // This is a simplified implementation
-    // In a real application, you would use Cloud Functions with Pub/Sub
-    console.log(
-      `Setting up scheduled calendar sync job every ${interval} hours`
-    );
-
-    // Example cloud function implementation:
-    /*
-    // Using Firebase Cloud Functions (in index.ts)
-    export const syncExternalCalendars = functions.pubsub
-      .schedule('every 3 hours')
-      .onRun(async (context) => {
-        try {
-          const db = admin.firestore();
-          const auth = admin.auth();
-          const app = admin.app();
-          
-          const calendarService = new CalendarServiceV2(db, auth, app);
-          await calendarService.synchronizeExternalCalendars();
-          
-          console.log('External calendar sync completed successfully');
-          return null;
-        } catch (error) {
-          console.error('Error in calendar sync job:', error);
-          return null;
-        }
-      });
-    */
-  }
-
-  /**
-   * Searches for calendar events based on specified criteria.
-   *
-   * @param {SearchCalendarEventsParams} params - The search parameters.
-   * @param {SearchLocationEnum} params.searchLocation - The primary location to search (practitioner, patient, or clinic).
-   * @param {string} params.entityId - The ID of the entity (practitioner, patient, or clinic) to search within/for.
-   * @param {string} [params.clinicId] - Optional clinic ID to filter by.
-   * @param {string} [params.practitionerId] - Optional practitioner ID to filter by.
-   * @param {string} [params.patientId] - Optional patient ID to filter by.
-   * @param {string} [params.procedureId] - Optional procedure ID to filter by.
-   * @param {DateRange} [params.dateRange] - Optional date range to filter by (event start time).
-   * @param {CalendarEventStatus} [params.eventStatus] - Optional event status to filter by.
-   * @param {CalendarEventType} [params.eventType] - Optional event type to filter by.
-   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of matching calendar events.
-   * @throws {Error} If the search location requires an entity ID that is not provided.
-   */
-  async searchCalendarEvents(
-    params: SearchCalendarEventsParams
-  ): Promise<CalendarEvent[]> {
-    // Use the utility function to perform the search
-    return searchCalendarEventsUtil(this.db, params);
-  }
-
-  /**
-   * Gets a doctor's upcoming appointments for a specific date range
-   *
-   * @param {string} doctorId - ID of the practitioner
-   * @param {Date} startDate - Start date of the range
-   * @param {Date} endDate - End date of the range
-   * @param {CalendarEventStatus} [status] - Optional status filter (defaults to CONFIRMED)
-   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
-   */
-  async getPractitionerUpcomingAppointments(
-    doctorId: string,
-    startDate: Date,
-    endDate: Date,
-    status: CalendarEventStatus = CalendarEventStatus.CONFIRMED
-  ): Promise<CalendarEvent[]> {
-    // Create a date range for the query
-    const dateRange: DateRange = {
-      start: Timestamp.fromDate(startDate),
-      end: Timestamp.fromDate(endDate),
-    };
-
-    // Create the search parameters
-    const searchParams: SearchCalendarEventsParams = {
-      searchLocation: SearchLocationEnum.PRACTITIONER,
-      entityId: doctorId,
-      dateRange,
-      eventStatus: status,
-      eventType: CalendarEventType.APPOINTMENT,
-    };
-
-    // Search for the appointments
-    return this.searchCalendarEvents(searchParams);
-  }
-
-  /**
-   * Gets a patient's appointments for a specific date range
-   *
-   * @param {string} patientId - ID of the patient
-   * @param {Date} startDate - Start date of the range
-   * @param {Date} endDate - End date of the range
-   * @param {CalendarEventStatus} [status] - Optional status filter (defaults to all non-canceled appointments)
-   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
-   */
-  async getPatientAppointments(
-    patientId: string,
-    startDate: Date,
-    endDate: Date,
-    status?: CalendarEventStatus
-  ): Promise<CalendarEvent[]> {
-    // Create a date range for the query
-    const dateRange: DateRange = {
-      start: Timestamp.fromDate(startDate),
-      end: Timestamp.fromDate(endDate),
-    };
-
-    // Create the search parameters
-    const searchParams: SearchCalendarEventsParams = {
-      searchLocation: SearchLocationEnum.PATIENT,
-      entityId: patientId,
-      dateRange,
-      eventType: CalendarEventType.APPOINTMENT,
-    };
-
-    // Add status filter if provided
-    if (status) {
-      searchParams.eventStatus = status;
-    }
-
-    // Search for the appointments
-    return this.searchCalendarEvents(searchParams);
-  }
-
-  /**
-   * Gets all appointments for a clinic within a specific date range
-   *
-   * @param {string} clinicId - ID of the clinic
-   * @param {Date} startDate - Start date of the range
-   * @param {Date} endDate - End date of the range
-   * @param {string} [doctorId] - Optional doctor ID to filter by
-   * @param {CalendarEventStatus} [status] - Optional status filter
-   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
-   */
-  async getClinicAppointments(
-    clinicId: string,
-    startDate: Date,
-    endDate: Date,
-    doctorId?: string,
-    status?: CalendarEventStatus
-  ): Promise<CalendarEvent[]> {
-    // Create a date range for the query
-    const dateRange: DateRange = {
-      start: Timestamp.fromDate(startDate),
-      end: Timestamp.fromDate(endDate),
-    };
-
-    // Create the search parameters
-    const searchParams: SearchCalendarEventsParams = {
-      searchLocation: SearchLocationEnum.CLINIC,
-      entityId: clinicId,
-      dateRange,
-      eventType: CalendarEventType.APPOINTMENT,
-    };
-
-    // Add doctor filter if provided
-    if (doctorId) {
-      searchParams.practitionerId = doctorId;
-    }
-
-    // Add status filter if provided
-    if (status) {
-      searchParams.eventStatus = status;
-    }
-
-    // Search for the appointments
-    return this.searchCalendarEvents(searchParams);
-  }
-
-  // #endregion
-
-  // #region Private Helper Methods
-
-  /**
-   * Validates appointment creation parameters
-   * @param params - Appointment parameters to validate
-   * @throws Error if validation fails
-   */
-  private async validateAppointmentParams(
-    params: CreateAppointmentParams
-  ): Promise<void> {
-    // TODO: Add custom validation logic after Zod schema validation
-    // - Check if doctor works at the clinic
-    // - Check if procedure is available at the clinic
-    // - Check if patient is eligible for the procedure
-    // - Validate time slot (15-minute increments)
-    // - Check clinic's subscription status
-    // - Check if auto-confirm is enabled
-
-    // Validate basic parameters using Zod schema
-    await createAppointmentSchema.parseAsync(params);
-  }
-
-  /**
-   * Validates if the event time falls within clinic working hours
-   * @param clinicId - ID of the clinic
-   * @param eventTime - Event time to validate
-   * @throws Error if validation fails
-   */
-  private async validateClinicWorkingHours(
-    clinicId: string,
-    eventTime: CalendarEventTime
-  ): Promise<void> {
-    // Get clinic working hours for the day
-    const startDate = eventTime.start.toDate();
-    const workingHours = await this.getClinicWorkingHours(clinicId, startDate);
-
-    if (workingHours.length === 0) {
-      throw new Error("Clinic is not open on this day");
-    }
-
-    // Find if the appointment time falls within any working hours slot
-    const startTime = startDate;
-    const endTime = eventTime.end.toDate();
-    const isWithinWorkingHours = workingHours.some((slot) => {
-      return slot.start <= startTime && slot.end >= endTime && slot.isAvailable;
-    });
-
-    if (!isWithinWorkingHours) {
-      throw new Error("Appointment time is outside clinic working hours");
-    }
-  }
-
-  /**
-   * Validates if the doctor is available during the event time
-   * @param doctorId - ID of the doctor
-   * @param eventTime - Event time to validate
-   * @param clinicId - ID of the clinic where the appointment is being booked
-   * @throws Error if validation fails
-   */
-  private async validateDoctorAvailability(
-    doctorId: string,
-    eventTime: CalendarEventTime,
-    clinicId: string
-  ): Promise<void> {
-    const startDate = eventTime.start.toDate();
-    const startTime = startDate;
-    const endTime = eventTime.end.toDate();
-
-    // Get doctor's document to check clinic-specific working hours
-    const practitionerRef = doc(this.db, PRACTITIONERS_COLLECTION, doctorId);
-    const practitionerDoc = await getDoc(practitionerRef);
-
-    if (!practitionerDoc.exists()) {
-      throw new Error(`Doctor with ID ${doctorId} not found`);
-    }
-
-    const practitioner = practitionerDoc.data();
-
-    // Check if doctor works at the specified clinic
-    if (!practitioner.clinics.includes(clinicId)) {
-      throw new Error("Doctor does not work at this clinic");
-    }
-
-    // Get doctor's clinic-specific working hours
-    const clinicWorkingHours = practitioner.clinicWorkingHours?.find(
-      (hours: PractitionerClinicWorkingHours) =>
-        hours.clinicId === clinicId && hours.isActive
-    );
-
-    if (!clinicWorkingHours) {
-      throw new Error("Doctor does not have working hours set for this clinic");
-    }
-
-    // Get the day of the week (0 = Sunday, 1 = Monday, etc.)
-    const dayOfWeek = startDate.getDay();
-    const dayKey = [
-      "sunday",
-      "monday",
-      "tuesday",
-      "wednesday",
-      "thursday",
-      "friday",
-      "saturday",
-    ][dayOfWeek];
-    const daySchedule = clinicWorkingHours.workingHours[dayKey];
-
-    if (!daySchedule) {
-      throw new Error("Doctor is not working on this day at this clinic");
-    }
-
-    // Convert working hours to Date objects for comparison
-    const [startHour, startMinute] = daySchedule.start.split(":").map(Number);
-    const [endHour, endMinute] = daySchedule.end.split(":").map(Number);
-
-    const scheduleStart = new Date(startDate);
-    scheduleStart.setHours(startHour, startMinute, 0, 0);
-
-    const scheduleEnd = new Date(startDate);
-    scheduleEnd.setHours(endHour, endMinute, 0, 0);
-
-    // Check if the appointment time is within doctor's working hours
-    if (startTime < scheduleStart || endTime > scheduleEnd) {
-      throw new Error(
-        "Appointment time is outside doctor's working hours at this clinic"
-      );
-    }
-
-    // Get existing appointments
-    const appointments = await this.getDoctorAppointments(doctorId, startDate);
-
-    // Check for overlapping appointments
-    const hasOverlap = appointments.some((appointment) => {
-      const appointmentStart = appointment.eventTime.start.toDate();
-      const appointmentEnd = appointment.eventTime.end.toDate();
-      return (
-        (startTime >= appointmentStart && startTime < appointmentEnd) ||
-        (endTime > appointmentStart && endTime <= appointmentEnd) ||
-        (startTime <= appointmentStart && endTime >= appointmentEnd)
-      );
-    });
-
-    if (hasOverlap) {
-      throw new Error("Doctor has another appointment during this time");
-    }
-  }
-
-  /**
-   * Updates appointment status
-   * @param appointmentId - ID of the appointment
-   * @param clinicId - ID of the clinic
-   * @param status - New status
-   * @returns Updated calendar event
-   */
-  private async updateAppointmentStatus(
-    appointmentId: string,
-    clinicId: string,
-    status: CalendarEventStatus
-  ): Promise<CalendarEvent> {
-    // Get the appointment
-    const baseCollectionPath = `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}`;
-    const appointmentRef = doc(this.db, baseCollectionPath, appointmentId);
-    const appointmentDoc = await getDoc(appointmentRef);
-
-    if (!appointmentDoc.exists()) {
-      throw new Error(`Appointment with ID ${appointmentId} not found`);
-    }
-
-    const appointment = appointmentDoc.data() as CalendarEvent;
-
-    // Validate that the appointment belongs to the specified clinic
-    if (appointment.clinicBranchId !== clinicId) {
-      throw new Error("Appointment does not belong to the specified clinic");
-    }
-
-    // Validate the status transition
-    this.validateStatusTransition(appointment.status, status);
-
-    // Update the appointment
-    const updateParams: UpdateAppointmentParams = {
-      appointmentId,
-      clinicId,
-      eventTime: appointment.eventTime,
-      description: appointment.description || "",
-      doctorId: appointment.practitionerProfileId || "",
-      patientId: appointment.patientProfileId || "",
-      status,
-    };
-
-    // Validate update parameters
-    await this.validateUpdatePermissions(updateParams);
-
-    // Update the appointment
-    return this.updateAppointment(updateParams);
-  }
-
-  /**
-   * Validates status transition
-   * @param currentStatus - Current status
-   * @param newStatus - New status
-   * @throws Error if transition is invalid
-   */
-  private validateStatusTransition(
-    currentStatus: CalendarEventStatus,
-    newStatus: CalendarEventStatus
-  ): void {
-    // Define valid status transitions
-    const validTransitions: Record<CalendarEventStatus, CalendarEventStatus[]> =
-      {
-        [CalendarEventStatus.PENDING]: [
-          CalendarEventStatus.CONFIRMED,
-          CalendarEventStatus.REJECTED,
-          CalendarEventStatus.CANCELED,
-        ],
-        [CalendarEventStatus.CONFIRMED]: [
-          CalendarEventStatus.CANCELED,
-          CalendarEventStatus.CHECKED_IN,
-          CalendarEventStatus.COMPLETED,
-          CalendarEventStatus.RESCHEDULED,
-          CalendarEventStatus.NO_SHOW,
-        ],
-        [CalendarEventStatus.CHECKED_IN]: [
-          CalendarEventStatus.IN_PROGRESS,
-          CalendarEventStatus.COMPLETED,
-          CalendarEventStatus.CANCELED,
-        ],
-        [CalendarEventStatus.IN_PROGRESS]: [
-          CalendarEventStatus.COMPLETED,
-          CalendarEventStatus.CANCELED,
-        ],
-        [CalendarEventStatus.REJECTED]: [],
-        [CalendarEventStatus.CANCELED]: [],
-        [CalendarEventStatus.RESCHEDULED]: [
-          CalendarEventStatus.CONFIRMED,
-          CalendarEventStatus.CANCELED,
-        ],
-        [CalendarEventStatus.COMPLETED]: [],
-        [CalendarEventStatus.NO_SHOW]: [],
-      };
-
-    // Check if transition is valid
-    if (!validTransitions[currentStatus].includes(newStatus)) {
-      throw new Error(
-        `Invalid status transition from ${currentStatus} to ${newStatus}`
-      );
-    }
-  }
-
-  /**
-   * Syncs appointment with external calendars based on entity type and status
-   * @param appointment - Calendar event to sync
-   */
-  private async syncAppointmentWithExternalCalendars(
-    appointment: CalendarEvent
-  ): Promise<void> {
-    if (!appointment.practitionerProfileId || !appointment.patientProfileId) {
-      return;
-    }
-
-    try {
-      // Get synced calendars for doctor and patient (no longer sync with clinic)
-      const [doctorCalendars, patientCalendars] = await Promise.all([
-        this.syncedCalendarsService.getPractitionerSyncedCalendars(
-          appointment.practitionerProfileId
-        ),
-        this.syncedCalendarsService.getPatientSyncedCalendars(
-          appointment.patientProfileId
-        ),
-      ]);
-
-      // Filter active calendars
-      const activeDoctorCalendars = doctorCalendars.filter(
-        (cal) => cal.isActive
-      );
-      const activePatientCalendars = patientCalendars.filter(
-        (cal) => cal.isActive
-      );
-
-      // Skip if there are no active calendars
-      if (
-        activeDoctorCalendars.length === 0 &&
-        activePatientCalendars.length === 0
-      ) {
-        return;
-      }
-
-      // Only sync INTERNAL events (those created within our system)
-      if (appointment.syncStatus !== CalendarSyncStatus.INTERNAL) {
-        return;
-      }
-
-      // For doctors: Only sync CONFIRMED status events
-      if (
-        appointment.status === CalendarEventStatus.CONFIRMED &&
-        activeDoctorCalendars.length > 0
-      ) {
-        await Promise.all(
-          activeDoctorCalendars.map((calendar) =>
-            this.syncEventToExternalCalendar(appointment, calendar, "doctor")
-          )
-        );
-      }
-
-      // For patients: Sync all events EXCEPT CANCELED and REJECTED
-      if (
-        appointment.status !== CalendarEventStatus.CANCELED &&
-        appointment.status !== CalendarEventStatus.REJECTED &&
-        activePatientCalendars.length > 0
-      ) {
-        await Promise.all(
-          activePatientCalendars.map((calendar) =>
-            this.syncEventToExternalCalendar(appointment, calendar, "patient")
-          )
-        );
-      }
-    } catch (error) {
-      console.error("Error syncing with external calendars:", error);
-      // Don't throw error as this is not critical for appointment creation
-    }
-  }
-
-  /**
-   * Syncs a single event to an external calendar
-   * @param appointment - Calendar event to sync
-   * @param calendar - External calendar to sync with
-   * @param entityType - Type of entity owning the calendar
-   */
-  private async syncEventToExternalCalendar(
-    appointment: CalendarEvent,
-    calendar: any,
-    entityType: "doctor" | "patient"
-  ): Promise<void> {
-    try {
-      // Create a copy of the appointment to modify for external syncing
-      const eventToSync = { ...appointment };
-
-      // Prepare event title based on status and entity type
-      let eventTitle = appointment.eventName;
-      const clinicName = appointment.clinicBranchInfo?.name || "Clinic";
-
-      // Format title appropriately
-      if (entityType === "patient") {
-        eventTitle = `[${appointment.status}] ${eventTitle} @ ${clinicName}`;
-      } else {
-        eventTitle = `${eventTitle} - Patient: ${
-          appointment.patientProfileInfo?.fullName || "Unknown"
-        } @ ${clinicName}`;
-      }
-
-      // Update the event name for external sync
-      eventToSync.eventName = eventTitle;
-
-      // Check if this event was previously synced with this calendar
-      const existingSyncId = appointment.syncedCalendarEventId?.find(
-        (sync) => sync.syncedCalendarProvider === calendar.provider
-      )?.eventId;
-
-      // If we have a synced event ID, we should update the existing event
-      // If not, create a new event
-
-      if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
-        const result =
-          await this.syncedCalendarsService.syncPractitionerEventsToGoogleCalendar(
-            entityType === "doctor"
-              ? appointment.practitionerProfileId!
-              : appointment.patientProfileId!,
-            calendar.id,
-            [eventToSync],
-            existingSyncId // Pass existing sync ID if we have one
-          );
-
-        // If sync was successful and we've created a new event (no existing sync),
-        // we should update our local event with the new sync ID
-        if (result.success && result.eventIds?.length && !existingSyncId) {
-          // Update the appointment with the new sync ID
-          const newSyncEvent: SyncedCalendarEvent = {
-            eventId: result.eventIds[0],
-            syncedCalendarProvider: calendar.provider,
-            syncedAt: Timestamp.now(),
-          };
-
-          // Update the event in the database with the new sync ID
-          await this.updateEventWithSyncId(
-            entityType === "doctor"
-              ? appointment.practitionerProfileId!
-              : appointment.patientProfileId!,
-            entityType,
-            appointment.id,
-            newSyncEvent
-          );
-        }
-      }
-    } catch (error) {
-      console.error(`Error syncing with ${entityType}'s calendar:`, error);
-      // Don't throw error as this is not critical
-    }
-  }
-
-  /**
-   * Updates an event with a new sync ID
-   * @param entityId - ID of the entity (doctor or patient)
-   * @param entityType - Type of entity
-   * @param eventId - ID of the event
-   * @param syncEvent - Sync event information
-   */
-  private async updateEventWithSyncId(
-    entityId: string,
-    entityType: "doctor" | "patient",
-    eventId: string,
-    syncEvent: SyncedCalendarEvent
-  ): Promise<void> {
-    try {
-      // Determine the collection path based on entity type
-      const collectionPath =
-        entityType === "doctor"
-          ? `${PRACTITIONERS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`
-          : `${PATIENTS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
-
-      // Get the event reference
-      const eventRef = doc(this.db, collectionPath, eventId);
-      const eventDoc = await getDoc(eventRef);
-
-      if (eventDoc.exists()) {
-        const event = eventDoc.data() as CalendarEvent;
-        const syncIds = [...(event.syncedCalendarEventId || [])];
-
-        // Check if we already have this sync ID
-        const existingSyncIndex = syncIds.findIndex(
-          (sync) =>
-            sync.syncedCalendarProvider === syncEvent.syncedCalendarProvider
-        );
-
-        if (existingSyncIndex >= 0) {
-          // Update the existing sync ID
-          syncIds[existingSyncIndex] = syncEvent;
-        } else {
-          // Add the new sync ID
-          syncIds.push(syncEvent);
-        }
-
-        // Update the event
-        await updateDoc(eventRef, {
-          syncedCalendarEventId: syncIds,
-          updatedAt: serverTimestamp(),
-        });
-
-        console.log(
-          `Updated event ${eventId} with sync ID ${syncEvent.eventId}`
-        );
-      }
-    } catch (error) {
-      console.error("Error updating event with sync ID:", error);
-    }
-  }
-
-  /**
-   * Validates update permissions and parameters
-   * @param params - Update parameters to validate
-   */
-  private async validateUpdatePermissions(
-    params: UpdateAppointmentParams
-  ): Promise<void> {
-    // TODO: Add custom validation logic after Zod schema validation
-    // - Check if user has permission to update the appointment
-    // - Check if the appointment exists
-    // - Check if the new status transition is valid
-    // - Check if the new time slot is valid
-    // - Validate against clinic's business rules
-
-    // Validate basic parameters using Zod schema
-    await updateAppointmentSchema.parseAsync(params);
-  }
-
-  /**
-   * Gets clinic working hours for a specific date
-   * @param clinicId - ID of the clinic
-   * @param date - Date to get working hours for
-   * @returns Working hours for the clinic
-   */
-  private async getClinicWorkingHours(
-    clinicId: string,
-    date: Date
-  ): Promise<TimeSlot[]> {
-    // Get clinic document
-    const clinicRef = doc(this.db, CLINICS_COLLECTION, clinicId);
-    const clinicDoc = await getDoc(clinicRef);
-
-    if (!clinicDoc.exists()) {
-      throw new Error(`Clinic with ID ${clinicId} not found`);
-    }
-
-    // TODO: Implement proper working hours retrieval from clinic data model
-    // For now, return default working hours (9 AM - 5 PM)
-    const workingHours: TimeSlot[] = [];
-    const dayOfWeek = date.getDay();
-
-    // Skip weekends (0 = Sunday, 6 = Saturday)
-    if (dayOfWeek === 0 || dayOfWeek === 6) {
-      return workingHours;
-    }
-
-    // Create working hours slot (9 AM - 5 PM)
-    const workingDate = new Date(date);
-    workingDate.setHours(9, 0, 0, 0);
-    const startTime = new Date(workingDate);
-
-    workingDate.setHours(17, 0, 0, 0);
-    const endTime = new Date(workingDate);
-
-    workingHours.push({
-      start: startTime,
-      end: endTime,
-      isAvailable: true,
-    });
-
-    return workingHours;
-  }
-
-  /**
-   * Gets doctor's schedule for a specific date
-   * @param doctorId - ID of the doctor
-   * @param date - Date to get schedule for
-   * @returns Doctor's schedule
-   */
-  private async getDoctorSchedule(
-    doctorId: string,
-    date: Date
-  ): Promise<TimeSlot[]> {
-    // Get doctor document
-    const practitionerRef = doc(this.db, PRACTITIONERS_COLLECTION, doctorId);
-    const practitionerDoc = await getDoc(practitionerRef);
-
-    if (!practitionerDoc.exists()) {
-      throw new Error(`Doctor with ID ${doctorId} not found`);
-    }
-
-    // TODO: Implement proper schedule retrieval from practitioner data model
-    // For now, return default schedule (9 AM - 5 PM)
-    const schedule: TimeSlot[] = [];
-    const dayOfWeek = date.getDay();
-
-    // Skip weekends (0 = Sunday, 6 = Saturday)
-    if (dayOfWeek === 0 || dayOfWeek === 6) {
-      return schedule;
-    }
-
-    // Create schedule slot (9 AM - 5 PM)
-    const scheduleDate = new Date(date);
-    scheduleDate.setHours(9, 0, 0, 0);
-    const startTime = new Date(scheduleDate);
-
-    scheduleDate.setHours(17, 0, 0, 0);
-    const endTime = new Date(scheduleDate);
-
-    schedule.push({
-      start: startTime,
-      end: endTime,
-      isAvailable: true,
-    });
-
-    return schedule;
-  }
-
-  /**
-   * Gets doctor's appointments for a specific date
-   * @param doctorId - ID of the doctor
-   * @param date - Date to get appointments for
-   * @returns Array of calendar events
-   */
-  private async getDoctorAppointments(
-    doctorId: string,
-    date: Date
-  ): Promise<CalendarEvent[]> {
-    // Create start and end timestamps for the day
-    const startOfDay = new Date(date);
-    startOfDay.setHours(0, 0, 0, 0);
-    const endOfDay = new Date(date);
-    endOfDay.setHours(23, 59, 59, 999);
-
-    // Query appointments for the doctor on the specified date
-    const appointmentsRef = collection(this.db, CALENDAR_COLLECTION);
-    const q = query(
-      appointmentsRef,
-      where("practitionerProfileId", "==", doctorId),
-      where("eventTime.start", ">=", Timestamp.fromDate(startOfDay)),
-      where("eventTime.start", "<=", Timestamp.fromDate(endOfDay)),
-      where("status", "in", [
-        CalendarEventStatus.CONFIRMED,
-        CalendarEventStatus.PENDING,
-      ])
-    );
-
-    const querySnapshot = await getDocs(q);
-    return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
-  }
-
-  /**
-   * Calculates available time slots based on working hours, schedule and existing appointments
-   * @param workingHours - Clinic working hours
-   * @param doctorSchedule - Doctor's schedule
-   * @param existingAppointments - Existing appointments
-   * @returns Array of available time slots
-   */
-  private calculateAvailableSlots(
-    workingHours: TimeSlot[],
-    doctorSchedule: TimeSlot[],
-    existingAppointments: CalendarEvent[]
-  ): TimeSlot[] {
-    const availableSlots: TimeSlot[] = [];
-
-    // First, find overlapping time slots between clinic hours and doctor schedule
-    for (const workingHour of workingHours) {
-      for (const scheduleSlot of doctorSchedule) {
-        // Find overlap between working hours and doctor schedule
-        const overlapStart = new Date(
-          Math.max(workingHour.start.getTime(), scheduleSlot.start.getTime())
-        );
-        const overlapEnd = new Date(
-          Math.min(workingHour.end.getTime(), scheduleSlot.end.getTime())
-        );
-
-        // If there is an overlap and both slots are available
-        if (
-          overlapStart < overlapEnd &&
-          workingHour.isAvailable &&
-          scheduleSlot.isAvailable
-        ) {
-          // Create 15-minute slots within the overlap period
-          let slotStart = new Date(overlapStart);
-          while (slotStart < overlapEnd) {
-            const slotEnd = new Date(
-              slotStart.getTime() + MIN_APPOINTMENT_DURATION * 60 * 1000
-            );
-
-            // Check if this slot overlaps with any existing appointments
-            const hasOverlap = existingAppointments.some((appointment) => {
-              const appointmentStart = appointment.eventTime.start.toDate();
-              const appointmentEnd = appointment.eventTime.end.toDate();
-              return (
-                (slotStart >= appointmentStart && slotStart < appointmentEnd) ||
-                (slotEnd > appointmentStart && slotEnd <= appointmentEnd)
-              );
-            });
-
-            if (!hasOverlap && slotEnd <= overlapEnd) {
-              availableSlots.push({
-                start: new Date(slotStart),
-                end: new Date(slotEnd),
-                isAvailable: true,
-              });
-            }
-
-            // Move to next slot
-            slotStart = new Date(
-              slotStart.getTime() + MIN_APPOINTMENT_DURATION * 60 * 1000
-            );
-          }
-        }
-      }
-    }
-
-    return availableSlots;
-  }
-
-  /**
-   * Fetches and creates info cards for clinic, doctor, and patient profiles
-   * @param clinicId - ID of the clinic
-   * @param doctorId - ID of the doctor
-   * @param patientId - ID of the patient
-   * @returns Object containing info cards for all profiles
-   */
-  private async fetchProfileInfoCards(
-    clinicId: string,
-    doctorId: string,
-    patientId: string
-  ): Promise<{
-    clinicInfo: ClinicInfo | null;
-    practitionerInfo: PractitionerProfileInfo | null;
-    patientInfo: PatientProfileInfo | null;
-  }> {
-    try {
-      // Fetch all profiles concurrently
-      const [clinicDoc, practitionerDoc, patientDoc, patientSensitiveInfoDoc] =
-        await Promise.all([
-          getDoc(doc(this.db, CLINICS_COLLECTION, clinicId)),
-          getDoc(doc(this.db, PRACTITIONERS_COLLECTION, doctorId)),
-          getDoc(doc(this.db, PATIENTS_COLLECTION, patientId)),
-          getDoc(
-            doc(
-              this.db,
-              PATIENTS_COLLECTION,
-              patientId,
-              PATIENT_SENSITIVE_INFO_COLLECTION,
-              patientId
-            )
-          ),
-        ]);
-
-      // Create info cards
-      const clinicInfo: ClinicInfo | null = clinicDoc.exists()
-        ? {
-            id: clinicDoc.id,
-            featuredPhoto: clinicDoc.data().featuredPhoto || "",
-            name: clinicDoc.data().name,
-            description: clinicDoc.data().description || "",
-            location: clinicDoc.data().location,
-            contactInfo: clinicDoc.data().contactInfo,
-          }
-        : null;
-
-      const practitionerInfo: PractitionerProfileInfo | null =
-        practitionerDoc.exists()
-          ? {
-              id: practitionerDoc.id,
-              practitionerPhoto:
-                practitionerDoc.data().basicInfo.profileImageUrl || null,
-              name: `${practitionerDoc.data().basicInfo.firstName} ${
-                practitionerDoc.data().basicInfo.lastName
-              }`,
-              email: practitionerDoc.data().basicInfo.email,
-              phone: practitionerDoc.data().basicInfo.phoneNumber || null,
-              certification: practitionerDoc.data().certification,
-            }
-          : null;
-
-      // First try to get data from sensitive-info subcollection
-      let patientInfo: PatientProfileInfo | null = null;
-
-      if (patientSensitiveInfoDoc.exists()) {
-        const sensitiveData = patientSensitiveInfoDoc.data();
-        patientInfo = {
-          id: patientId,
-          fullName: `${sensitiveData.firstName} ${sensitiveData.lastName}`,
-          email: sensitiveData.email || "",
-          phone: sensitiveData.phoneNumber || null,
-          dateOfBirth: sensitiveData.dateOfBirth || Timestamp.now(),
-          gender: sensitiveData.gender || Gender.OTHER,
-        };
-      } else if (patientDoc.exists()) {
-        // Fall back to patient document if sensitive info not available
-        patientInfo = {
-          id: patientDoc.id,
-          fullName: patientDoc.data().displayName,
-          email: patientDoc.data().contactInfo?.email || "",
-          phone: patientDoc.data().phoneNumber || null,
-          dateOfBirth: patientDoc.data().dateOfBirth || Timestamp.now(),
-          gender: patientDoc.data().gender || Gender.OTHER,
-        };
-      }
-
-      return {
-        clinicInfo,
-        practitionerInfo,
-        patientInfo,
-      };
-    } catch (error) {
-      console.error("Error fetching profile info cards:", error);
-      return {
-        clinicInfo: null,
-        practitionerInfo: null,
-        patientInfo: null,
-      };
-    }
-  }
-
-  // #endregion
-}
+import { Auth } from "firebase/auth";
+import { Firestore, Timestamp, serverTimestamp } from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+import { BaseService } from "../base.service";
+import {
+  CalendarEvent,
+  CalendarEventStatus,
+  CalendarEventTime,
+  CalendarEventType,
+  CalendarSyncStatus,
+  CreateCalendarEventData,
+  UpdateCalendarEventData,
+  CALENDAR_COLLECTION,
+  SyncedCalendarEvent,
+  ProcedureInfo,
+  TimeSlot,
+  CreateAppointmentParams,
+  UpdateAppointmentParams,
+  SearchCalendarEventsParams,
+  SearchLocationEnum,
+  DateRange,
+} from "../../types/calendar";
+import {
+  PRACTITIONERS_COLLECTION,
+  PractitionerClinicWorkingHours,
+} from "../../types/practitioner";
+import {
+  PATIENTS_COLLECTION,
+  Gender,
+  PATIENT_SENSITIVE_INFO_COLLECTION,
+} from "../../types/patient";
+import { CLINICS_COLLECTION } from "../../types/clinic";
+import { SyncedCalendarProvider } from "../../types/calendar/synced-calendar.types";
+import {
+  ClinicInfo,
+  PatientProfileInfo,
+  PractitionerProfileInfo,
+} from "../../types/profile";
+import {
+  doc,
+  getDoc,
+  collection,
+  query,
+  where,
+  getDocs,
+  setDoc,
+  updateDoc,
+  QueryConstraint,
+  CollectionReference,
+  DocumentData,
+} from "firebase/firestore";
+import {
+  createAppointmentSchema,
+  updateAppointmentSchema,
+} from "../../validations/appointment.schema";
+
+// Import utility functions
+import {
+  createAppointmentUtil,
+  updateAppointmentUtil,
+  deleteAppointmentUtil,
+} from "./utils/appointment.utils";
+import { searchCalendarEventsUtil } from "./utils/calendar-event.utils";
+import { SyncedCalendarsService } from "./synced-calendars.service";
+import { Timestamp as FirestoreTimestamp } from "firebase-admin/firestore";
+
+/**
+ * Minimum appointment duration in minutes
+ */
+const MIN_APPOINTMENT_DURATION = 15;
+
+/**
+ * Refactored Calendar Service
+ * Provides streamlined calendar management with proper access control and scheduling rules
+ */
+export class CalendarServiceV2 extends BaseService {
+  private syncedCalendarsService: SyncedCalendarsService;
+
+  /**
+   * Creates a new CalendarService instance
+   * @param db - Firestore instance
+   * @param auth - Firebase Auth instance
+   * @param app - Firebase App instance
+   */
+  constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
+    super(db, auth, app);
+    this.syncedCalendarsService = new SyncedCalendarsService(db, auth, app);
+  }
+
+  // #region Public API Methods
+
+  /**
+   * Creates a new appointment with proper validation and scheduling rules
+   * @param params - Appointment creation parameters
+   * @returns Created calendar event
+   */
+  async createAppointment(
+    params: CreateAppointmentParams
+  ): Promise<CalendarEvent> {
+    // Validate input parameters
+    await this.validateAppointmentParams(params);
+
+    // Check clinic working hours
+    await this.validateClinicWorkingHours(params.clinicId, params.eventTime);
+
+    // Check doctor availability
+    await this.validateDoctorAvailability(
+      params.doctorId,
+      params.eventTime,
+      params.clinicId
+    );
+
+    // Fetch profile info cards
+    const { clinicInfo, practitionerInfo, patientInfo } =
+      await this.fetchProfileInfoCards(
+        params.clinicId,
+        params.doctorId,
+        params.patientId
+      );
+
+    // Create the appointment
+    const appointmentData: Omit<
+      CreateCalendarEventData,
+      "id" | "createdAt" | "updatedAt"
+    > = {
+      clinicBranchId: params.clinicId,
+      clinicBranchInfo: clinicInfo,
+      practitionerProfileId: params.doctorId,
+      practitionerProfileInfo: practitionerInfo,
+      patientProfileId: params.patientId,
+      patientProfileInfo: patientInfo,
+      procedureId: params.procedureId,
+      eventLocation: params.eventLocation,
+      eventName: "Appointment", // TODO: Add procedure name when procedure model is available
+      eventTime: params.eventTime,
+      description: params.description || "",
+      status: CalendarEventStatus.PENDING,
+      syncStatus: CalendarSyncStatus.INTERNAL,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    const appointment = await createAppointmentUtil(
+      this.db,
+      params.clinicId,
+      params.doctorId,
+      params.patientId,
+      appointmentData,
+      this.generateId.bind(this)
+    );
+
+    // Sync with external calendars if needed
+    await this.syncAppointmentWithExternalCalendars(appointment);
+
+    return appointment;
+  }
+
+  /**
+   * Updates an existing appointment
+   * @param params - Appointment update parameters
+   * @returns Updated calendar event
+   */
+  async updateAppointment(
+    params: UpdateAppointmentParams
+  ): Promise<CalendarEvent> {
+    // Validate permissions
+    await this.validateUpdatePermissions(params);
+
+    const updateData: Omit<UpdateCalendarEventData, "updatedAt"> = {
+      eventTime: params.eventTime,
+      description: params.description,
+      status: params.status,
+    };
+
+    const appointment = await updateAppointmentUtil(
+      this.db,
+      params.clinicId,
+      params.doctorId,
+      params.patientId,
+      params.appointmentId,
+      updateData
+    );
+
+    // Sync with external calendars if needed
+    await this.syncAppointmentWithExternalCalendars(appointment);
+
+    return appointment;
+  }
+
+  /**
+   * Gets available appointment slots for a doctor at a clinic
+   * @param clinicId - ID of the clinic
+   * @param doctorId - ID of the doctor
+   * @param date - Date to check availability for
+   * @returns Array of available time slots
+   */
+  async getAvailableSlots(
+    clinicId: string,
+    doctorId: string,
+    date: Date
+  ): Promise<TimeSlot[]> {
+    // Get clinic working hours
+    const workingHours = await this.getClinicWorkingHours(clinicId, date);
+
+    // Get doctor's schedule
+    const doctorSchedule = await this.getDoctorSchedule(doctorId, date);
+
+    // Get existing appointments
+    const existingAppointments = await this.getDoctorAppointments(
+      doctorId,
+      date
+    );
+
+    // Calculate available slots
+    return this.calculateAvailableSlots(
+      workingHours,
+      doctorSchedule,
+      existingAppointments
+    );
+  }
+
+  /**
+   * Confirms an appointment
+   * @param appointmentId - ID of the appointment
+   * @param clinicId - ID of the clinic
+   * @returns Confirmed calendar event
+   */
+  async confirmAppointment(
+    appointmentId: string,
+    clinicId: string
+  ): Promise<CalendarEvent> {
+    return this.updateAppointmentStatus(
+      appointmentId,
+      clinicId,
+      CalendarEventStatus.CONFIRMED
+    );
+  }
+
+  /**
+   * Rejects an appointment
+   * @param appointmentId - ID of the appointment
+   * @param clinicId - ID of the clinic
+   * @returns Rejected calendar event
+   */
+  async rejectAppointment(
+    appointmentId: string,
+    clinicId: string
+  ): Promise<CalendarEvent> {
+    return this.updateAppointmentStatus(
+      appointmentId,
+      clinicId,
+      CalendarEventStatus.REJECTED
+    );
+  }
+
+  /**
+   * Cancels an appointment
+   * @param appointmentId - ID of the appointment
+   * @param clinicId - ID of the clinic
+   * @returns Canceled calendar event
+   */
+  async cancelAppointment(
+    appointmentId: string,
+    clinicId: string
+  ): Promise<CalendarEvent> {
+    return this.updateAppointmentStatus(
+      appointmentId,
+      clinicId,
+      CalendarEventStatus.CANCELED
+    );
+  }
+
+  /**
+   * Imports events from external calendars
+   * @param entityType - Type of entity (practitioner or patient)
+   * @param entityId - ID of the entity
+   * @param startDate - Start date for fetching events
+   * @param endDate - End date for fetching events
+   * @returns Number of events imported
+   */
+  async importEventsFromExternalCalendars(
+    entityType: "doctor" | "patient",
+    entityId: string,
+    startDate: Date,
+    endDate: Date
+  ): Promise<number> {
+    // Only practitioners (doctors) should sync two-way
+    // Patients only sync outwards (from our system to external calendars)
+    if (entityType === "patient") {
+      return 0;
+    }
+
+    // For doctors, get their synced calendars
+    const syncedCalendars =
+      await this.syncedCalendarsService.getPractitionerSyncedCalendars(
+        entityId
+      );
+
+    // Filter active calendars
+    const activeCalendars = syncedCalendars.filter((cal) => cal.isActive);
+
+    if (activeCalendars.length === 0) {
+      return 0;
+    }
+
+    let importedEventsCount = 0;
+    const currentTime = Timestamp.now();
+
+    // Import from each calendar
+    for (const calendar of activeCalendars) {
+      try {
+        let externalEvents: any[] = [];
+
+        // Fetch events based on provider and entity type
+        if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
+          externalEvents =
+            await this.syncedCalendarsService.fetchEventsFromPractitionerGoogleCalendar(
+              entityId,
+              calendar.id,
+              startDate,
+              endDate
+            );
+        }
+        // Add other providers as needed
+
+        // Process and import each event
+        for (const externalEvent of externalEvents) {
+          try {
+            // Convert the external event to our format
+            const convertedEvent =
+              this.syncedCalendarsService.convertGoogleEventsToPractitionerEvents(
+                entityId,
+                [externalEvent]
+              )[0];
+
+            // Skip events without valid time data
+            if (!convertedEvent.eventTime) {
+              continue;
+            }
+
+            // Create event data from external event
+            const eventData: Omit<
+              CreateCalendarEventData,
+              "id" | "createdAt" | "updatedAt"
+            > = {
+              // Ensure all required fields are set
+              eventName: convertedEvent.eventName || "External Event",
+              eventTime: convertedEvent.eventTime,
+              description: convertedEvent.description || "",
+              status: CalendarEventStatus.CONFIRMED,
+              syncStatus: CalendarSyncStatus.EXTERNAL,
+              eventType: CalendarEventType.BLOCKING,
+              practitionerProfileId: entityId,
+              syncedCalendarEventId: [
+                {
+                  eventId: externalEvent.id,
+                  syncedCalendarProvider: calendar.provider,
+                  syncedAt: currentTime,
+                },
+              ],
+            };
+
+            // Create the event in the doctor's calendar
+            const doctorEvent = await this.createDoctorBlockingEvent(
+              entityId,
+              eventData
+            );
+
+            if (doctorEvent) {
+              importedEventsCount++;
+            }
+          } catch (eventError) {
+            console.error("Error importing event:", eventError);
+            // Continue with other events even if one fails
+          }
+        }
+      } catch (calendarError) {
+        console.error(
+          `Error fetching events from calendar ${calendar.id}:`,
+          calendarError
+        );
+        // Continue with other calendars even if one fails
+      }
+    }
+
+    return importedEventsCount;
+  }
+
+  /**
+   * Creates a blocking event in a doctor's calendar
+   * @param doctorId - ID of the doctor
+   * @param eventData - Calendar event data
+   * @returns Created calendar event
+   */
+  private async createDoctorBlockingEvent(
+    doctorId: string,
+    eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">
+  ): Promise<CalendarEvent | null> {
+    try {
+      // Generate a unique ID for the event
+      const eventId = this.generateId();
+
+      // Create the event document reference
+      const eventRef = doc(
+        this.db,
+        PRACTITIONERS_COLLECTION,
+        doctorId,
+        CALENDAR_COLLECTION,
+        eventId
+      );
+
+      // Prepare the event data
+      const newEvent: CreateCalendarEventData = {
+        id: eventId,
+        ...eventData,
+        createdAt: serverTimestamp(),
+        updatedAt: serverTimestamp(),
+      };
+
+      // Set the document
+      await setDoc(eventRef, newEvent);
+
+      // Return the event
+      return {
+        ...newEvent,
+        createdAt: Timestamp.now(),
+        updatedAt: Timestamp.now(),
+      } as CalendarEvent;
+    } catch (error) {
+      console.error(
+        `Error creating blocking event for doctor ${doctorId}:`,
+        error
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Periodically syncs events from external calendars for doctors
+   * This would be called via a scheduled Cloud Function
+   * @param lookbackDays - Number of days to look back for events
+   * @param lookforwardDays - Number of days to look forward for events
+   */
+  async synchronizeExternalCalendars(
+    lookbackDays: number = 7,
+    lookforwardDays: number = 30
+  ): Promise<void> {
+    try {
+      // Get all doctors who have active synced calendars
+      const practitionersRef = collection(this.db, PRACTITIONERS_COLLECTION);
+      const practitionersSnapshot = await getDocs(practitionersRef);
+
+      // Prepare date range
+      const startDate = new Date();
+      startDate.setDate(startDate.getDate() - lookbackDays);
+
+      const endDate = new Date();
+      endDate.setDate(endDate.getDate() + lookforwardDays);
+
+      // For each doctor, check their synced calendars
+      const syncPromises = [];
+      for (const docSnapshot of practitionersSnapshot.docs) {
+        const practitionerId = docSnapshot.id;
+
+        // Import events from external calendars
+        syncPromises.push(
+          this.importEventsFromExternalCalendars(
+            "doctor",
+            practitionerId,
+            startDate,
+            endDate
+          )
+            .then((count) => {
+              console.log(
+                `Imported ${count} events for doctor ${practitionerId}`
+              );
+            })
+            .catch((error) => {
+              console.error(
+                `Error importing events for doctor ${practitionerId}:`,
+                error
+              );
+            })
+        );
+
+        // Also update existing events that might have changed
+        syncPromises.push(
+          this.updateExistingEventsFromExternalCalendars(
+            practitionerId,
+            startDate,
+            endDate
+          )
+            .then((count) => {
+              console.log(
+                `Updated ${count} events for doctor ${practitionerId}`
+              );
+            })
+            .catch((error) => {
+              console.error(
+                `Error updating events for doctor ${practitionerId}:`,
+                error
+              );
+            })
+        );
+      }
+
+      // Wait for all sync operations to complete
+      await Promise.all(syncPromises);
+      console.log("Completed external calendar synchronization");
+    } catch (error) {
+      console.error("Error synchronizing external calendars:", error);
+    }
+  }
+
+  /**
+   * Updates existing events that were synced from external calendars
+   * @param doctorId - ID of the doctor
+   * @param startDate - Start date for fetching events
+   * @param endDate - End date for fetching events
+   * @returns Number of events updated
+   */
+  private async updateExistingEventsFromExternalCalendars(
+    doctorId: string,
+    startDate: Date,
+    endDate: Date
+  ): Promise<number> {
+    try {
+      // Get all EXTERNAL events for this doctor within the date range
+      const eventsRef = collection(
+        this.db,
+        PRACTITIONERS_COLLECTION,
+        doctorId,
+        CALENDAR_COLLECTION
+      );
+      const q = query(
+        eventsRef,
+        where("syncStatus", "==", CalendarSyncStatus.EXTERNAL),
+        where("eventTime.start", ">=", Timestamp.fromDate(startDate)),
+        where("eventTime.start", "<=", Timestamp.fromDate(endDate))
+      );
+
+      const eventsSnapshot = await getDocs(q);
+      const events = eventsSnapshot.docs.map((doc) => ({
+        id: doc.id,
+        ...doc.data(),
+      })) as CalendarEvent[];
+
+      // Get the doctor's synced calendars
+      const calendars =
+        await this.syncedCalendarsService.getPractitionerSyncedCalendars(
+          doctorId
+        );
+      const activeCalendars = calendars.filter((cal) => cal.isActive);
+
+      if (activeCalendars.length === 0 || events.length === 0) {
+        return 0;
+      }
+
+      let updatedCount = 0;
+
+      // For each external event, check if it needs updating
+      for (const event of events) {
+        // Skip events without sync IDs
+        if (!event.syncedCalendarEventId?.length) continue;
+
+        for (const syncId of event.syncedCalendarEventId) {
+          // Find the calendar for this sync ID
+          const calendar = activeCalendars.find(
+            (cal) => cal.provider === syncId.syncedCalendarProvider
+          );
+          if (!calendar) continue;
+
+          // Check if the event exists and needs updating
+          if (syncId.syncedCalendarProvider === SyncedCalendarProvider.GOOGLE) {
+            try {
+              // Fetch the external event
+              const externalEvent = await this.fetchExternalEvent(
+                doctorId,
+                calendar,
+                syncId.eventId
+              );
+
+              // If the event was found, check if it's different from our local copy
+              if (externalEvent) {
+                // Compare basic properties (time, title, description)
+                const externalStartTime = new Date(
+                  externalEvent.start.dateTime || externalEvent.start.date
+                ).getTime();
+                const externalEndTime = new Date(
+                  externalEvent.end.dateTime || externalEvent.end.date
+                ).getTime();
+                const localStartTime = event.eventTime.start.toDate().getTime();
+                const localEndTime = event.eventTime.end.toDate().getTime();
+
+                // If times or title/description have changed, update our local copy
+                if (
+                  externalStartTime !== localStartTime ||
+                  externalEndTime !== localEndTime ||
+                  externalEvent.summary !== event.eventName ||
+                  externalEvent.description !== event.description
+                ) {
+                  // Update our local copy
+                  await this.updateLocalEventFromExternal(
+                    doctorId,
+                    event.id,
+                    externalEvent
+                  );
+                  updatedCount++;
+                }
+              } else {
+                // The event was deleted in the external calendar, mark it as canceled
+                await this.updateEventStatus(
+                  doctorId,
+                  event.id,
+                  CalendarEventStatus.CANCELED
+                );
+                updatedCount++;
+              }
+            } catch (error) {
+              console.error(
+                `Error updating external event ${event.id}:`,
+                error
+              );
+            }
+          }
+        }
+      }
+
+      return updatedCount;
+    } catch (error) {
+      console.error(
+        "Error updating existing events from external calendars:",
+        error
+      );
+      return 0;
+    }
+  }
+
+  /**
+   * Fetches a single external event from Google Calendar
+   * @param doctorId - ID of the doctor
+   * @param calendar - Calendar information
+   * @param externalEventId - ID of the external event
+   * @returns External event data or null if not found
+   */
+  private async fetchExternalEvent(
+    doctorId: string,
+    calendar: any,
+    externalEventId: string
+  ): Promise<any | null> {
+    try {
+      if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
+        // Refresh token if needed
+        // We're using the syncPractitionerEventsToGoogleCalendar to get the calendar with a refreshed token
+        const result =
+          await this.syncedCalendarsService.fetchEventFromPractitionerGoogleCalendar(
+            doctorId,
+            calendar.id,
+            externalEventId
+          );
+
+        return result;
+      }
+      return null;
+    } catch (error) {
+      console.error(`Error fetching external event ${externalEventId}:`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Updates a local event with data from an external event
+   * @param doctorId - ID of the doctor
+   * @param eventId - ID of the local event
+   * @param externalEvent - External event data
+   */
+  private async updateLocalEventFromExternal(
+    doctorId: string,
+    eventId: string,
+    externalEvent: any
+  ): Promise<void> {
+    try {
+      // Create event time from external event
+      const startTime = new Date(
+        externalEvent.start.dateTime || externalEvent.start.date
+      );
+      const endTime = new Date(
+        externalEvent.end.dateTime || externalEvent.end.date
+      );
+
+      // Update the local event
+      const eventRef = doc(
+        this.db,
+        PRACTITIONERS_COLLECTION,
+        doctorId,
+        CALENDAR_COLLECTION,
+        eventId
+      );
+
+      await updateDoc(eventRef, {
+        eventName: externalEvent.summary || "External Event",
+        eventTime: {
+          start: Timestamp.fromDate(startTime),
+          end: Timestamp.fromDate(endTime),
+        },
+        description: externalEvent.description || "",
+        updatedAt: serverTimestamp(),
+      });
+
+      console.log(`Updated local event ${eventId} from external event`);
+    } catch (error) {
+      console.error(
+        `Error updating local event ${eventId} from external:`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Updates an event's status
+   * @param doctorId - ID of the doctor
+   * @param eventId - ID of the event
+   * @param status - New status
+   */
+  private async updateEventStatus(
+    doctorId: string,
+    eventId: string,
+    status: CalendarEventStatus
+  ): Promise<void> {
+    try {
+      const eventRef = doc(
+        this.db,
+        PRACTITIONERS_COLLECTION,
+        doctorId,
+        CALENDAR_COLLECTION,
+        eventId
+      );
+
+      await updateDoc(eventRef, {
+        status,
+        updatedAt: serverTimestamp(),
+      });
+
+      console.log(`Updated event ${eventId} status to ${status}`);
+    } catch (error) {
+      console.error(`Error updating event ${eventId} status:`, error);
+    }
+  }
+
+  /**
+   * Creates a scheduled job to periodically sync external calendars
+   * Note: This would be implemented using Cloud Functions in a real application
+   * This is a sample implementation to show how it could be set up
+   * @param interval - Interval in hours
+   */
+  createScheduledSyncJob(interval: number = 3): void {
+    // This is a simplified implementation
+    // In a real application, you would use Cloud Functions with Pub/Sub
+    console.log(
+      `Setting up scheduled calendar sync job every ${interval} hours`
+    );
+
+    // Example cloud function implementation:
+    /*
+    // Using Firebase Cloud Functions (in index.ts)
+    export const syncExternalCalendars = functions.pubsub
+      .schedule('every 3 hours')
+      .onRun(async (context) => {
+        try {
+          const db = admin.firestore();
+          const auth = admin.auth();
+          const app = admin.app();
+          
+          const calendarService = new CalendarServiceV2(db, auth, app);
+          await calendarService.synchronizeExternalCalendars();
+          
+          console.log('External calendar sync completed successfully');
+          return null;
+        } catch (error) {
+          console.error('Error in calendar sync job:', error);
+          return null;
+        }
+      });
+    */
+  }
+
+  /**
+   * Searches for calendar events based on specified criteria.
+   *
+   * @param {SearchCalendarEventsParams} params - The search parameters.
+   * @param {SearchLocationEnum} params.searchLocation - The primary location to search (practitioner, patient, or clinic).
+   * @param {string} params.entityId - The ID of the entity (practitioner, patient, or clinic) to search within/for.
+   * @param {string} [params.clinicId] - Optional clinic ID to filter by.
+   * @param {string} [params.practitionerId] - Optional practitioner ID to filter by.
+   * @param {string} [params.patientId] - Optional patient ID to filter by.
+   * @param {string} [params.procedureId] - Optional procedure ID to filter by.
+   * @param {DateRange} [params.dateRange] - Optional date range to filter by (event start time).
+   * @param {CalendarEventStatus} [params.eventStatus] - Optional event status to filter by.
+   * @param {CalendarEventType} [params.eventType] - Optional event type to filter by.
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of matching calendar events.
+   * @throws {Error} If the search location requires an entity ID that is not provided.
+   */
+  async searchCalendarEvents(
+    params: SearchCalendarEventsParams
+  ): Promise<CalendarEvent[]> {
+    // Use the utility function to perform the search
+    return searchCalendarEventsUtil(this.db, params);
+  }
+
+  /**
+   * Gets a doctor's upcoming appointments for a specific date range
+   *
+   * @param {string} doctorId - ID of the practitioner
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {CalendarEventStatus} [status] - Optional status filter (defaults to CONFIRMED)
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getPractitionerUpcomingAppointments(
+    doctorId: string,
+    startDate: Date,
+    endDate: Date,
+    status: CalendarEventStatus = CalendarEventStatus.CONFIRMED
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.PRACTITIONER,
+      entityId: doctorId,
+      dateRange,
+      eventStatus: status,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
+  /**
+   * Gets a patient's appointments for a specific date range
+   *
+   * @param {string} patientId - ID of the patient
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {CalendarEventStatus} [status] - Optional status filter (defaults to all non-canceled appointments)
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getPatientAppointments(
+    patientId: string,
+    startDate: Date,
+    endDate: Date,
+    status?: CalendarEventStatus
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.PATIENT,
+      entityId: patientId,
+      dateRange,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Add status filter if provided
+    if (status) {
+      searchParams.eventStatus = status;
+    }
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
+  /**
+   * Gets all appointments for a clinic within a specific date range
+   *
+   * @param {string} clinicId - ID of the clinic
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {string} [doctorId] - Optional doctor ID to filter by
+   * @param {CalendarEventStatus} [status] - Optional status filter
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getClinicAppointments(
+    clinicId: string,
+    startDate: Date,
+    endDate: Date,
+    doctorId?: string,
+    status?: CalendarEventStatus
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.CLINIC,
+      entityId: clinicId,
+      dateRange,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Add doctor filter if provided
+    if (doctorId) {
+      searchParams.practitionerId = doctorId;
+    }
+
+    // Add status filter if provided
+    if (status) {
+      searchParams.eventStatus = status;
+    }
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
+  // #endregion
+
+  // #region Private Helper Methods
+
+  /**
+   * Validates appointment creation parameters
+   * @param params - Appointment parameters to validate
+   * @throws Error if validation fails
+   */
+  private async validateAppointmentParams(
+    params: CreateAppointmentParams
+  ): Promise<void> {
+    // TODO: Add custom validation logic after Zod schema validation
+    // - Check if doctor works at the clinic
+    // - Check if procedure is available at the clinic
+    // - Check if patient is eligible for the procedure
+    // - Validate time slot (15-minute increments)
+    // - Check clinic's subscription status
+    // - Check if auto-confirm is enabled
+
+    // Validate basic parameters using Zod schema
+    await createAppointmentSchema.parseAsync(params);
+  }
+
+  /**
+   * Validates if the event time falls within clinic working hours
+   * @param clinicId - ID of the clinic
+   * @param eventTime - Event time to validate
+   * @throws Error if validation fails
+   */
+  private async validateClinicWorkingHours(
+    clinicId: string,
+    eventTime: CalendarEventTime
+  ): Promise<void> {
+    // Get clinic working hours for the day
+    const startDate = eventTime.start.toDate();
+    const workingHours = await this.getClinicWorkingHours(clinicId, startDate);
+
+    if (workingHours.length === 0) {
+      throw new Error("Clinic is not open on this day");
+    }
+
+    // Find if the appointment time falls within any working hours slot
+    const startTime = startDate;
+    const endTime = eventTime.end.toDate();
+    const isWithinWorkingHours = workingHours.some((slot) => {
+      return slot.start <= startTime && slot.end >= endTime && slot.isAvailable;
+    });
+
+    if (!isWithinWorkingHours) {
+      throw new Error("Appointment time is outside clinic working hours");
+    }
+  }
+
+  /**
+   * Validates if the doctor is available during the event time
+   * @param doctorId - ID of the doctor
+   * @param eventTime - Event time to validate
+   * @param clinicId - ID of the clinic where the appointment is being booked
+   * @throws Error if validation fails
+   */
+  private async validateDoctorAvailability(
+    doctorId: string,
+    eventTime: CalendarEventTime,
+    clinicId: string
+  ): Promise<void> {
+    const startDate = eventTime.start.toDate();
+    const startTime = startDate;
+    const endTime = eventTime.end.toDate();
+
+    // Get doctor's document to check clinic-specific working hours
+    const practitionerRef = doc(this.db, PRACTITIONERS_COLLECTION, doctorId);
+    const practitionerDoc = await getDoc(practitionerRef);
+
+    if (!practitionerDoc.exists()) {
+      throw new Error(`Doctor with ID ${doctorId} not found`);
+    }
+
+    const practitioner = practitionerDoc.data();
+
+    // Check if doctor works at the specified clinic
+    if (!practitioner.clinics.includes(clinicId)) {
+      throw new Error("Doctor does not work at this clinic");
+    }
+
+    // Get doctor's clinic-specific working hours
+    const clinicWorkingHours = practitioner.clinicWorkingHours?.find(
+      (hours: PractitionerClinicWorkingHours) =>
+        hours.clinicId === clinicId && hours.isActive
+    );
+
+    if (!clinicWorkingHours) {
+      throw new Error("Doctor does not have working hours set for this clinic");
+    }
+
+    // Get the day of the week (0 = Sunday, 1 = Monday, etc.)
+    const dayOfWeek = startDate.getDay();
+    const dayKey = [
+      "sunday",
+      "monday",
+      "tuesday",
+      "wednesday",
+      "thursday",
+      "friday",
+      "saturday",
+    ][dayOfWeek];
+    const daySchedule = clinicWorkingHours.workingHours[dayKey];
+
+    if (!daySchedule) {
+      throw new Error("Doctor is not working on this day at this clinic");
+    }
+
+    // Convert working hours to Date objects for comparison
+    const [startHour, startMinute] = daySchedule.start.split(":").map(Number);
+    const [endHour, endMinute] = daySchedule.end.split(":").map(Number);
+
+    const scheduleStart = new Date(startDate);
+    scheduleStart.setHours(startHour, startMinute, 0, 0);
+
+    const scheduleEnd = new Date(startDate);
+    scheduleEnd.setHours(endHour, endMinute, 0, 0);
+
+    // Check if the appointment time is within doctor's working hours
+    if (startTime < scheduleStart || endTime > scheduleEnd) {
+      throw new Error(
+        "Appointment time is outside doctor's working hours at this clinic"
+      );
+    }
+
+    // Get existing appointments
+    const appointments = await this.getDoctorAppointments(doctorId, startDate);
+
+    // Check for overlapping appointments
+    const hasOverlap = appointments.some((appointment) => {
+      const appointmentStart = appointment.eventTime.start.toDate();
+      const appointmentEnd = appointment.eventTime.end.toDate();
+      return (
+        (startTime >= appointmentStart && startTime < appointmentEnd) ||
+        (endTime > appointmentStart && endTime <= appointmentEnd) ||
+        (startTime <= appointmentStart && endTime >= appointmentEnd)
+      );
+    });
+
+    if (hasOverlap) {
+      throw new Error("Doctor has another appointment during this time");
+    }
+  }
+
+  /**
+   * Updates appointment status
+   * @param appointmentId - ID of the appointment
+   * @param clinicId - ID of the clinic
+   * @param status - New status
+   * @returns Updated calendar event
+   */
+  private async updateAppointmentStatus(
+    appointmentId: string,
+    clinicId: string,
+    status: CalendarEventStatus
+  ): Promise<CalendarEvent> {
+    // Get the appointment
+    const baseCollectionPath = `${CLINICS_COLLECTION}/${clinicId}/${CALENDAR_COLLECTION}`;
+    const appointmentRef = doc(this.db, baseCollectionPath, appointmentId);
+    const appointmentDoc = await getDoc(appointmentRef);
+
+    if (!appointmentDoc.exists()) {
+      throw new Error(`Appointment with ID ${appointmentId} not found`);
+    }
+
+    const appointment = appointmentDoc.data() as CalendarEvent;
+
+    // Validate that the appointment belongs to the specified clinic
+    if (appointment.clinicBranchId !== clinicId) {
+      throw new Error("Appointment does not belong to the specified clinic");
+    }
+
+    // Validate the status transition
+    this.validateStatusTransition(appointment.status, status);
+
+    // Update the appointment
+    const updateParams: UpdateAppointmentParams = {
+      appointmentId,
+      clinicId,
+      eventTime: appointment.eventTime,
+      description: appointment.description || "",
+      doctorId: appointment.practitionerProfileId || "",
+      patientId: appointment.patientProfileId || "",
+      status,
+    };
+
+    // Validate update parameters
+    await this.validateUpdatePermissions(updateParams);
+
+    // Update the appointment
+    return this.updateAppointment(updateParams);
+  }
+
+  /**
+   * Validates status transition
+   * @param currentStatus - Current status
+   * @param newStatus - New status
+   * @throws Error if transition is invalid
+   */
+  private validateStatusTransition(
+    currentStatus: CalendarEventStatus,
+    newStatus: CalendarEventStatus
+  ): void {
+    // Define valid status transitions
+    const validTransitions: Record<CalendarEventStatus, CalendarEventStatus[]> =
+      {
+        [CalendarEventStatus.PENDING]: [
+          CalendarEventStatus.CONFIRMED,
+          CalendarEventStatus.REJECTED,
+          CalendarEventStatus.CANCELED,
+        ],
+        [CalendarEventStatus.CONFIRMED]: [
+          CalendarEventStatus.CANCELED,
+          CalendarEventStatus.CHECKED_IN,
+          CalendarEventStatus.COMPLETED,
+          CalendarEventStatus.RESCHEDULED,
+          CalendarEventStatus.NO_SHOW,
+        ],
+        [CalendarEventStatus.CHECKED_IN]: [
+          CalendarEventStatus.IN_PROGRESS,
+          CalendarEventStatus.COMPLETED,
+          CalendarEventStatus.CANCELED,
+        ],
+        [CalendarEventStatus.IN_PROGRESS]: [
+          CalendarEventStatus.COMPLETED,
+          CalendarEventStatus.CANCELED,
+        ],
+        [CalendarEventStatus.REJECTED]: [],
+        [CalendarEventStatus.CANCELED]: [],
+        [CalendarEventStatus.RESCHEDULED]: [
+          CalendarEventStatus.CONFIRMED,
+          CalendarEventStatus.CANCELED,
+        ],
+        [CalendarEventStatus.COMPLETED]: [],
+        [CalendarEventStatus.NO_SHOW]: [],
+      };
+
+    // Check if transition is valid
+    if (!validTransitions[currentStatus].includes(newStatus)) {
+      throw new Error(
+        `Invalid status transition from ${currentStatus} to ${newStatus}`
+      );
+    }
+  }
+
+  /**
+   * Syncs appointment with external calendars based on entity type and status
+   * @param appointment - Calendar event to sync
+   */
+  private async syncAppointmentWithExternalCalendars(
+    appointment: CalendarEvent
+  ): Promise<void> {
+    if (!appointment.practitionerProfileId || !appointment.patientProfileId) {
+      return;
+    }
+
+    try {
+      // Get synced calendars for doctor and patient (no longer sync with clinic)
+      const [doctorCalendars, patientCalendars] = await Promise.all([
+        this.syncedCalendarsService.getPractitionerSyncedCalendars(
+          appointment.practitionerProfileId
+        ),
+        this.syncedCalendarsService.getPatientSyncedCalendars(
+          appointment.patientProfileId
+        ),
+      ]);
+
+      // Filter active calendars
+      const activeDoctorCalendars = doctorCalendars.filter(
+        (cal) => cal.isActive
+      );
+      const activePatientCalendars = patientCalendars.filter(
+        (cal) => cal.isActive
+      );
+
+      // Skip if there are no active calendars
+      if (
+        activeDoctorCalendars.length === 0 &&
+        activePatientCalendars.length === 0
+      ) {
+        return;
+      }
+
+      // Only sync INTERNAL events (those created within our system)
+      if (appointment.syncStatus !== CalendarSyncStatus.INTERNAL) {
+        return;
+      }
+
+      // For doctors: Only sync CONFIRMED status events
+      if (
+        appointment.status === CalendarEventStatus.CONFIRMED &&
+        activeDoctorCalendars.length > 0
+      ) {
+        await Promise.all(
+          activeDoctorCalendars.map((calendar) =>
+            this.syncEventToExternalCalendar(appointment, calendar, "doctor")
+          )
+        );
+      }
+
+      // For patients: Sync all events EXCEPT CANCELED and REJECTED
+      if (
+        appointment.status !== CalendarEventStatus.CANCELED &&
+        appointment.status !== CalendarEventStatus.REJECTED &&
+        activePatientCalendars.length > 0
+      ) {
+        await Promise.all(
+          activePatientCalendars.map((calendar) =>
+            this.syncEventToExternalCalendar(appointment, calendar, "patient")
+          )
+        );
+      }
+    } catch (error) {
+      console.error("Error syncing with external calendars:", error);
+      // Don't throw error as this is not critical for appointment creation
+    }
+  }
+
+  /**
+   * Syncs a single event to an external calendar
+   * @param appointment - Calendar event to sync
+   * @param calendar - External calendar to sync with
+   * @param entityType - Type of entity owning the calendar
+   */
+  private async syncEventToExternalCalendar(
+    appointment: CalendarEvent,
+    calendar: any,
+    entityType: "doctor" | "patient"
+  ): Promise<void> {
+    try {
+      // Create a copy of the appointment to modify for external syncing
+      const eventToSync = { ...appointment };
+
+      // Prepare event title based on status and entity type
+      let eventTitle = appointment.eventName;
+      const clinicName = appointment.clinicBranchInfo?.name || "Clinic";
+
+      // Format title appropriately
+      if (entityType === "patient") {
+        eventTitle = `[${appointment.status}] ${eventTitle} @ ${clinicName}`;
+      } else {
+        eventTitle = `${eventTitle} - Patient: ${
+          appointment.patientProfileInfo?.fullName || "Unknown"
+        } @ ${clinicName}`;
+      }
+
+      // Update the event name for external sync
+      eventToSync.eventName = eventTitle;
+
+      // Check if this event was previously synced with this calendar
+      const existingSyncId = appointment.syncedCalendarEventId?.find(
+        (sync) => sync.syncedCalendarProvider === calendar.provider
+      )?.eventId;
+
+      // If we have a synced event ID, we should update the existing event
+      // If not, create a new event
+
+      if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
+        const result =
+          await this.syncedCalendarsService.syncPractitionerEventsToGoogleCalendar(
+            entityType === "doctor"
+              ? appointment.practitionerProfileId!
+              : appointment.patientProfileId!,
+            calendar.id,
+            [eventToSync],
+            existingSyncId // Pass existing sync ID if we have one
+          );
+
+        // If sync was successful and we've created a new event (no existing sync),
+        // we should update our local event with the new sync ID
+        if (result.success && result.eventIds?.length && !existingSyncId) {
+          // Update the appointment with the new sync ID
+          const newSyncEvent: SyncedCalendarEvent = {
+            eventId: result.eventIds[0],
+            syncedCalendarProvider: calendar.provider,
+            syncedAt: Timestamp.now(),
+          };
+
+          // Update the event in the database with the new sync ID
+          await this.updateEventWithSyncId(
+            entityType === "doctor"
+              ? appointment.practitionerProfileId!
+              : appointment.patientProfileId!,
+            entityType,
+            appointment.id,
+            newSyncEvent
+          );
+        }
+      }
+    } catch (error) {
+      console.error(`Error syncing with ${entityType}'s calendar:`, error);
+      // Don't throw error as this is not critical
+    }
+  }
+
+  /**
+   * Updates an event with a new sync ID
+   * @param entityId - ID of the entity (doctor or patient)
+   * @param entityType - Type of entity
+   * @param eventId - ID of the event
+   * @param syncEvent - Sync event information
+   */
+  private async updateEventWithSyncId(
+    entityId: string,
+    entityType: "doctor" | "patient",
+    eventId: string,
+    syncEvent: SyncedCalendarEvent
+  ): Promise<void> {
+    try {
+      // Determine the collection path based on entity type
+      const collectionPath =
+        entityType === "doctor"
+          ? `${PRACTITIONERS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`
+          : `${PATIENTS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
+
+      // Get the event reference
+      const eventRef = doc(this.db, collectionPath, eventId);
+      const eventDoc = await getDoc(eventRef);
+
+      if (eventDoc.exists()) {
+        const event = eventDoc.data() as CalendarEvent;
+        const syncIds = [...(event.syncedCalendarEventId || [])];
+
+        // Check if we already have this sync ID
+        const existingSyncIndex = syncIds.findIndex(
+          (sync) =>
+            sync.syncedCalendarProvider === syncEvent.syncedCalendarProvider
+        );
+
+        if (existingSyncIndex >= 0) {
+          // Update the existing sync ID
+          syncIds[existingSyncIndex] = syncEvent;
+        } else {
+          // Add the new sync ID
+          syncIds.push(syncEvent);
+        }
+
+        // Update the event
+        await updateDoc(eventRef, {
+          syncedCalendarEventId: syncIds,
+          updatedAt: serverTimestamp(),
+        });
+
+        console.log(
+          `Updated event ${eventId} with sync ID ${syncEvent.eventId}`
+        );
+      }
+    } catch (error) {
+      console.error("Error updating event with sync ID:", error);
+    }
+  }
+
+  /**
+   * Validates update permissions and parameters
+   * @param params - Update parameters to validate
+   */
+  private async validateUpdatePermissions(
+    params: UpdateAppointmentParams
+  ): Promise<void> {
+    // TODO: Add custom validation logic after Zod schema validation
+    // - Check if user has permission to update the appointment
+    // - Check if the appointment exists
+    // - Check if the new status transition is valid
+    // - Check if the new time slot is valid
+    // - Validate against clinic's business rules
+
+    // Validate basic parameters using Zod schema
+    await updateAppointmentSchema.parseAsync(params);
+  }
+
+  /**
+   * Gets clinic working hours for a specific date
+   * @param clinicId - ID of the clinic
+   * @param date - Date to get working hours for
+   * @returns Working hours for the clinic
+   */
+  private async getClinicWorkingHours(
+    clinicId: string,
+    date: Date
+  ): Promise<TimeSlot[]> {
+    // Get clinic document
+    const clinicRef = doc(this.db, CLINICS_COLLECTION, clinicId);
+    const clinicDoc = await getDoc(clinicRef);
+
+    if (!clinicDoc.exists()) {
+      throw new Error(`Clinic with ID ${clinicId} not found`);
+    }
+
+    // TODO: Implement proper working hours retrieval from clinic data model
+    // For now, return default working hours (9 AM - 5 PM)
+    const workingHours: TimeSlot[] = [];
+    const dayOfWeek = date.getDay();
+
+    // Skip weekends (0 = Sunday, 6 = Saturday)
+    if (dayOfWeek === 0 || dayOfWeek === 6) {
+      return workingHours;
+    }
+
+    // Create working hours slot (9 AM - 5 PM)
+    const workingDate = new Date(date);
+    workingDate.setHours(9, 0, 0, 0);
+    const startTime = new Date(workingDate);
+
+    workingDate.setHours(17, 0, 0, 0);
+    const endTime = new Date(workingDate);
+
+    workingHours.push({
+      start: startTime,
+      end: endTime,
+      isAvailable: true,
+    });
+
+    return workingHours;
+  }
+
+  /**
+   * Gets doctor's schedule for a specific date
+   * @param doctorId - ID of the doctor
+   * @param date - Date to get schedule for
+   * @returns Doctor's schedule
+   */
+  private async getDoctorSchedule(
+    doctorId: string,
+    date: Date
+  ): Promise<TimeSlot[]> {
+    // Get doctor document
+    const practitionerRef = doc(this.db, PRACTITIONERS_COLLECTION, doctorId);
+    const practitionerDoc = await getDoc(practitionerRef);
+
+    if (!practitionerDoc.exists()) {
+      throw new Error(`Doctor with ID ${doctorId} not found`);
+    }
+
+    // TODO: Implement proper schedule retrieval from practitioner data model
+    // For now, return default schedule (9 AM - 5 PM)
+    const schedule: TimeSlot[] = [];
+    const dayOfWeek = date.getDay();
+
+    // Skip weekends (0 = Sunday, 6 = Saturday)
+    if (dayOfWeek === 0 || dayOfWeek === 6) {
+      return schedule;
+    }
+
+    // Create schedule slot (9 AM - 5 PM)
+    const scheduleDate = new Date(date);
+    scheduleDate.setHours(9, 0, 0, 0);
+    const startTime = new Date(scheduleDate);
+
+    scheduleDate.setHours(17, 0, 0, 0);
+    const endTime = new Date(scheduleDate);
+
+    schedule.push({
+      start: startTime,
+      end: endTime,
+      isAvailable: true,
+    });
+
+    return schedule;
+  }
+
+  /**
+   * Gets doctor's appointments for a specific date
+   * @param doctorId - ID of the doctor
+   * @param date - Date to get appointments for
+   * @returns Array of calendar events
+   */
+  private async getDoctorAppointments(
+    doctorId: string,
+    date: Date
+  ): Promise<CalendarEvent[]> {
+    // Create start and end timestamps for the day
+    const startOfDay = new Date(date);
+    startOfDay.setHours(0, 0, 0, 0);
+    const endOfDay = new Date(date);
+    endOfDay.setHours(23, 59, 59, 999);
+
+    // Query appointments for the doctor on the specified date
+    const appointmentsRef = collection(this.db, CALENDAR_COLLECTION);
+    const q = query(
+      appointmentsRef,
+      where("practitionerProfileId", "==", doctorId),
+      where("eventTime.start", ">=", Timestamp.fromDate(startOfDay)),
+      where("eventTime.start", "<=", Timestamp.fromDate(endOfDay)),
+      where("status", "in", [
+        CalendarEventStatus.CONFIRMED,
+        CalendarEventStatus.PENDING,
+      ])
+    );
+
+    const querySnapshot = await getDocs(q);
+    return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
+  }
+
+  /**
+   * Calculates available time slots based on working hours, schedule and existing appointments
+   * @param workingHours - Clinic working hours
+   * @param doctorSchedule - Doctor's schedule
+   * @param existingAppointments - Existing appointments
+   * @returns Array of available time slots
+   */
+  private calculateAvailableSlots(
+    workingHours: TimeSlot[],
+    doctorSchedule: TimeSlot[],
+    existingAppointments: CalendarEvent[]
+  ): TimeSlot[] {
+    const availableSlots: TimeSlot[] = [];
+
+    // First, find overlapping time slots between clinic hours and doctor schedule
+    for (const workingHour of workingHours) {
+      for (const scheduleSlot of doctorSchedule) {
+        // Find overlap between working hours and doctor schedule
+        const overlapStart = new Date(
+          Math.max(workingHour.start.getTime(), scheduleSlot.start.getTime())
+        );
+        const overlapEnd = new Date(
+          Math.min(workingHour.end.getTime(), scheduleSlot.end.getTime())
+        );
+
+        // If there is an overlap and both slots are available
+        if (
+          overlapStart < overlapEnd &&
+          workingHour.isAvailable &&
+          scheduleSlot.isAvailable
+        ) {
+          // Create 15-minute slots within the overlap period
+          let slotStart = new Date(overlapStart);
+          while (slotStart < overlapEnd) {
+            const slotEnd = new Date(
+              slotStart.getTime() + MIN_APPOINTMENT_DURATION * 60 * 1000
+            );
+
+            // Check if this slot overlaps with any existing appointments
+            const hasOverlap = existingAppointments.some((appointment) => {
+              const appointmentStart = appointment.eventTime.start.toDate();
+              const appointmentEnd = appointment.eventTime.end.toDate();
+              return (
+                (slotStart >= appointmentStart && slotStart < appointmentEnd) ||
+                (slotEnd > appointmentStart && slotEnd <= appointmentEnd)
+              );
+            });
+
+            if (!hasOverlap && slotEnd <= overlapEnd) {
+              availableSlots.push({
+                start: new Date(slotStart),
+                end: new Date(slotEnd),
+                isAvailable: true,
+              });
+            }
+
+            // Move to next slot
+            slotStart = new Date(
+              slotStart.getTime() + MIN_APPOINTMENT_DURATION * 60 * 1000
+            );
+          }
+        }
+      }
+    }
+
+    return availableSlots;
+  }
+
+  /**
+   * Fetches and creates info cards for clinic, doctor, and patient profiles
+   * @param clinicId - ID of the clinic
+   * @param doctorId - ID of the doctor
+   * @param patientId - ID of the patient
+   * @returns Object containing info cards for all profiles
+   */
+  private async fetchProfileInfoCards(
+    clinicId: string,
+    doctorId: string,
+    patientId: string
+  ): Promise<{
+    clinicInfo: ClinicInfo | null;
+    practitionerInfo: PractitionerProfileInfo | null;
+    patientInfo: PatientProfileInfo | null;
+  }> {
+    try {
+      // Fetch all profiles concurrently
+      const [clinicDoc, practitionerDoc, patientDoc, patientSensitiveInfoDoc] =
+        await Promise.all([
+          getDoc(doc(this.db, CLINICS_COLLECTION, clinicId)),
+          getDoc(doc(this.db, PRACTITIONERS_COLLECTION, doctorId)),
+          getDoc(doc(this.db, PATIENTS_COLLECTION, patientId)),
+          getDoc(
+            doc(
+              this.db,
+              PATIENTS_COLLECTION,
+              patientId,
+              PATIENT_SENSITIVE_INFO_COLLECTION,
+              patientId
+            )
+          ),
+        ]);
+
+      // Create info cards
+      const clinicInfo: ClinicInfo | null = clinicDoc.exists()
+        ? {
+            id: clinicDoc.id,
+            featuredPhoto: clinicDoc.data().featuredPhoto || "",
+            name: clinicDoc.data().name,
+            description: clinicDoc.data().description || "",
+            location: clinicDoc.data().location,
+            contactInfo: clinicDoc.data().contactInfo,
+          }
+        : null;
+
+      const practitionerInfo: PractitionerProfileInfo | null =
+        practitionerDoc.exists()
+          ? {
+              id: practitionerDoc.id,
+              practitionerPhoto:
+                practitionerDoc.data().basicInfo.profileImageUrl || null,
+              name: `${practitionerDoc.data().basicInfo.firstName} ${
+                practitionerDoc.data().basicInfo.lastName
+              }`,
+              email: practitionerDoc.data().basicInfo.email,
+              phone: practitionerDoc.data().basicInfo.phoneNumber || null,
+              certification: practitionerDoc.data().certification,
+            }
+          : null;
+
+      // First try to get data from sensitive-info subcollection
+      let patientInfo: PatientProfileInfo | null = null;
+
+      if (patientSensitiveInfoDoc.exists()) {
+        const sensitiveData = patientSensitiveInfoDoc.data();
+        patientInfo = {
+          id: patientId,
+          fullName: `${sensitiveData.firstName} ${sensitiveData.lastName}`,
+          email: sensitiveData.email || "",
+          phone: sensitiveData.phoneNumber || null,
+          dateOfBirth: sensitiveData.dateOfBirth || Timestamp.now(),
+          gender: sensitiveData.gender || Gender.OTHER,
+        };
+      } else if (patientDoc.exists()) {
+        // Fall back to patient document if sensitive info not available
+        patientInfo = {
+          id: patientDoc.id,
+          fullName: patientDoc.data().displayName,
+          email: patientDoc.data().contactInfo?.email || "",
+          phone: patientDoc.data().phoneNumber || null,
+          dateOfBirth: patientDoc.data().dateOfBirth || Timestamp.now(),
+          gender: patientDoc.data().gender || Gender.OTHER,
+        };
+      }
+
+      return {
+        clinicInfo,
+        practitionerInfo,
+        patientInfo,
+      };
+    } catch (error) {
+      console.error("Error fetching profile info cards:", error);
+      return {
+        clinicInfo: null,
+        practitionerInfo: null,
+        patientInfo: null,
+      };
+    }
+  }
+
+  // #endregion
+}