@blackcode_sa/metaestetics-api 1.12.72 → 1.13.1

package/src/services/analytics/analytics.service.ts

@@ -0,0 +1,2142 @@
+import { Firestore, collection, query, where, getDocs, Timestamp } from 'firebase/firestore';
+import { Auth } from 'firebase/auth';
+import { FirebaseApp } from 'firebase/app';
+import { BaseService } from '../base.service';
+import { Appointment, AppointmentStatus, APPOINTMENTS_COLLECTION, PaymentStatus } from '../../types/appointment';
+import { AppointmentService } from '../appointment/appointment.service';
+import {
+  PractitionerAnalytics,
+  ProcedureAnalytics,
+  TimeEfficiencyMetrics,
+  CancellationMetrics,
+  NoShowMetrics,
+  RevenueMetrics,
+  RevenueTrend,
+  DurationTrend,
+  AppointmentTrend,
+  CancellationRateTrend,
+  ProductUsageMetrics,
+  ProductRevenueMetrics,
+  ProductUsageByProcedure,
+  PatientAnalytics,
+  PatientLifetimeValueMetrics,
+  PatientRetentionMetrics,
+  CostPerPatientMetrics,
+  PaymentStatusBreakdown,
+  ClinicAnalytics,
+  ClinicComparisonMetrics,
+  ProcedurePopularity,
+  ProcedureProfitability,
+  CancellationReasonStats,
+  DashboardAnalytics,
+  AnalyticsDateRange,
+  AnalyticsFilters,
+  GroupingPeriod,
+  TrendPeriod,
+  EntityType,
+} from '../../types/analytics';
+
+// Import utility functions
+import { calculateAppointmentCost, calculateTotalRevenue, extractProductUsage } from './utils/cost-calculation.utils';
+import {
+  calculateTimeEfficiency,
+  calculateAverageTimeMetrics,
+  calculateEfficiencyDistribution,
+  calculateCancellationLeadTime,
+} from './utils/time-calculation.utils';
+import {
+  filterByDateRange,
+  filterAppointments,
+  getCompletedAppointments,
+  getCanceledAppointments,
+  getNoShowAppointments,
+  getActiveAppointments,
+  calculatePercentage,
+} from './utils/appointment-filtering.utils';
+import {
+  readStoredPractitionerAnalytics,
+  readStoredProcedureAnalytics,
+  readStoredClinicAnalytics,
+  readStoredDashboardAnalytics,
+  readStoredTimeEfficiencyMetrics,
+  readStoredRevenueMetrics,
+  readStoredCancellationMetrics,
+  readStoredNoShowMetrics,
+} from './utils/stored-analytics.utils';
+import {
+  calculateGroupedRevenueMetrics,
+  calculateGroupedProductUsageMetrics,
+  calculateGroupedTimeEfficiencyMetrics,
+  calculateGroupedPatientBehaviorMetrics,
+} from './utils/grouping.utils';
+import {
+  groupAppointmentsByPeriod,
+  generatePeriods,
+  getTrendChange,
+  type TrendPeriod as TrendPeriodType,
+} from './utils/trend-calculation.utils';
+import { ReadStoredAnalyticsOptions, AnalyticsPeriod } from '../../types/analytics';
+import {
+  GroupedRevenueMetrics,
+  GroupedProductUsageMetrics,
+  GroupedTimeEfficiencyMetrics,
+  GroupedPatientBehaviorMetrics,
+} from '../../types/analytics/grouped-analytics.types';
+import { ReviewAnalyticsService, ReviewAnalyticsMetrics, OverallReviewAverages, ReviewDetail } from './review-analytics.service';
+import { ReviewTrend } from '../../types/analytics';
+
+/**
+ * AnalyticsService provides comprehensive financial and analytical intelligence
+ * for the Clinic Admin app, including metrics about doctors, procedures,
+ * appointments, patients, products, and clinic operations.
+ */
+export class AnalyticsService extends BaseService {
+  private appointmentService: AppointmentService;
+  private reviewAnalyticsService: ReviewAnalyticsService;
+
+  /**
+   * Creates a new AnalyticsService instance.
+   *
+   * @param db Firestore instance
+   * @param auth Firebase Auth instance
+   * @param app Firebase App instance
+   * @param appointmentService Appointment service instance for querying appointments
+   */
+  constructor(db: Firestore, auth: Auth, app: FirebaseApp, appointmentService: AppointmentService) {
+    super(db, auth, app);
+    this.appointmentService = appointmentService;
+    this.reviewAnalyticsService = new ReviewAnalyticsService(db, auth, app, appointmentService);
+  }
+
+  /**
+   * Fetches appointments with optional filters
+   *
+   * @param filters - Optional filters
+   * @param dateRange - Optional date range
+   * @returns Array of appointments
+   */
+  private async fetchAppointments(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<Appointment[]> {
+    try {
+      // Build query constraints
+      const constraints: any[] = [];
+
+      if (filters?.clinicBranchId) {
+        constraints.push(where('clinicBranchId', '==', filters.clinicBranchId));
+      }
+      if (filters?.practitionerId) {
+        constraints.push(where('practitionerId', '==', filters.practitionerId));
+      }
+      if (filters?.procedureId) {
+        constraints.push(where('procedureId', '==', filters.procedureId));
+      }
+      if (filters?.patientId) {
+        constraints.push(where('patientId', '==', filters.patientId));
+      }
+      if (dateRange) {
+        constraints.push(where('appointmentStartTime', '>=', Timestamp.fromDate(dateRange.start)));
+        constraints.push(where('appointmentStartTime', '<=', Timestamp.fromDate(dateRange.end)));
+      }
+
+      // Use AppointmentService to search appointments
+      const searchParams: any = {};
+      if (filters?.clinicBranchId) searchParams.clinicBranchId = filters.clinicBranchId;
+      if (filters?.practitionerId) searchParams.practitionerId = filters.practitionerId;
+      if (filters?.procedureId) searchParams.procedureId = filters.procedureId;
+      if (filters?.patientId) searchParams.patientId = filters.patientId;
+      if (dateRange) {
+        searchParams.startDate = dateRange.start;
+        searchParams.endDate = dateRange.end;
+      }
+
+      const result = await this.appointmentService.searchAppointments(searchParams);
+
+      return result.appointments;
+    } catch (error) {
+      console.error('[AnalyticsService] Error fetching appointments:', error);
+      throw error;
+    }
+  }
+
+  // ==========================================
+  // Practitioner Analytics
+  // ==========================================
+
+  /**
+   * Get practitioner performance metrics
+   * First checks for stored analytics, then calculates if not available or stale
+   *
+   * @param practitionerId - ID of the practitioner
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics
+   * @returns Practitioner analytics object
+   */
+  async getPractitionerAnalytics(
+    practitionerId: string,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<PractitionerAnalytics> {
+    // Try to read from stored analytics first
+    if (dateRange && options?.useCache !== false) {
+      // Determine period from date range
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const clinicBranchId = options?.clinicBranchId; // Would need to be passed or determined
+
+      if (clinicBranchId) {
+        const stored = await readStoredPractitionerAnalytics(
+          this.db,
+          clinicBranchId,
+          practitionerId,
+          { ...options, period },
+        );
+
+        if (stored) {
+          // Return stored data (without metadata)
+          const { metadata, ...analytics } = stored;
+          return analytics;
+        }
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments({ practitionerId }, dateRange);
+
+    const completed = getCompletedAppointments(appointments);
+    const canceled = getCanceledAppointments(appointments);
+    const noShow = getNoShowAppointments(appointments);
+    const pending = filterAppointments(appointments, { practitionerId }).filter(
+      a => a.status === AppointmentStatus.PENDING,
+    );
+    const confirmed = filterAppointments(appointments, { practitionerId }).filter(
+      a => a.status === AppointmentStatus.CONFIRMED,
+    );
+
+    const { totalRevenue, currency } = calculateTotalRevenue(completed);
+    const timeMetrics = calculateAverageTimeMetrics(completed);
+
+    // Get unique patients
+    const uniquePatients = new Set(appointments.map(a => a.patientId));
+    const returningPatients = new Set(
+      appointments
+        .filter(a => {
+          const patientAppointments = appointments.filter(ap => ap.patientId === a.patientId);
+          return patientAppointments.length > 1;
+        })
+        .map(a => a.patientId),
+    );
+
+    // Get top procedures
+    const procedureMap = new Map<string, { name: string; count: number; revenue: number }>();
+    completed.forEach(appointment => {
+      const procId = appointment.procedureId;
+      const procName = appointment.procedureInfo?.name || 'Unknown';
+      const cost = calculateAppointmentCost(appointment).cost;
+
+      if (procedureMap.has(procId)) {
+        const existing = procedureMap.get(procId)!;
+        existing.count++;
+        existing.revenue += cost;
+      } else {
+        procedureMap.set(procId, { name: procName, count: 1, revenue: cost });
+      }
+    });
+
+    const topProcedures = Array.from(procedureMap.entries())
+      .map(([procedureId, data]) => ({
+        procedureId,
+        procedureName: data.name,
+        count: data.count,
+        revenue: data.revenue,
+      }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 10);
+
+    const practitionerName =
+      appointments.length > 0
+        ? appointments[0].practitionerInfo?.name || 'Unknown'
+        : 'Unknown';
+
+    return {
+      total: appointments.length,
+      dateRange,
+      practitionerId,
+      practitionerName,
+      totalAppointments: appointments.length,
+      completedAppointments: completed.length,
+      canceledAppointments: canceled.length,
+      noShowAppointments: noShow.length,
+      pendingAppointments: pending.length,
+      confirmedAppointments: confirmed.length,
+      cancellationRate: calculatePercentage(canceled.length, appointments.length),
+      noShowRate: calculatePercentage(noShow.length, appointments.length),
+      averageBookedTime: timeMetrics.averageBookedDuration,
+      averageActualTime: timeMetrics.averageActualDuration,
+      timeEfficiency: timeMetrics.averageEfficiency,
+      totalRevenue,
+      averageRevenuePerAppointment: completed.length > 0 ? totalRevenue / completed.length : 0,
+      currency,
+      topProcedures,
+      patientRetentionRate: calculatePercentage(returningPatients.size, uniquePatients.size),
+      uniquePatients: uniquePatients.size,
+    };
+  }
+
+  // ==========================================
+  // Procedure Analytics
+  // ==========================================
+
+  /**
+   * Get procedure performance metrics
+   * First checks for stored analytics, then calculates if not available or stale
+   *
+   * @param procedureId - ID of the procedure (optional, if not provided returns all)
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics
+   * @returns Procedure analytics object or array
+   */
+  async getProcedureAnalytics(
+    procedureId?: string,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<ProcedureAnalytics | ProcedureAnalytics[]> {
+    // Try to read from stored analytics first (only for single procedure)
+    if (procedureId && dateRange && options?.useCache !== false) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const clinicBranchId = options?.clinicBranchId;
+      
+      if (clinicBranchId) {
+        const stored = await readStoredProcedureAnalytics(
+          this.db,
+          clinicBranchId,
+          procedureId,
+          { ...options, period },
+        );
+
+        if (stored) {
+          // Return stored data (without metadata)
+          const { metadata, ...analytics } = stored;
+          return analytics;
+        }
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(procedureId ? { procedureId } : undefined, dateRange);
+
+    if (procedureId) {
+      return this.calculateProcedureAnalytics(appointments, procedureId);
+    }
+
+    // Group by procedure
+    const procedureMap = new Map<string, Appointment[]>();
+    appointments.forEach(appointment => {
+      const procId = appointment.procedureId;
+      if (!procedureMap.has(procId)) {
+        procedureMap.set(procId, []);
+      }
+      procedureMap.get(procId)!.push(appointment);
+    });
+
+    return Array.from(procedureMap.entries()).map(([procId, procAppointments]) =>
+      this.calculateProcedureAnalytics(procAppointments, procId),
+    );
+  }
+
+  /**
+   * Calculate analytics for a specific procedure
+   *
+   * @param appointments - Appointments for the procedure
+   * @param procedureId - Procedure ID
+   * @returns Procedure analytics
+   */
+  private calculateProcedureAnalytics(
+    appointments: Appointment[],
+    procedureId: string,
+  ): ProcedureAnalytics {
+    const completed = getCompletedAppointments(appointments);
+    const canceled = getCanceledAppointments(appointments);
+    const noShow = getNoShowAppointments(appointments);
+
+    const { totalRevenue, currency } = calculateTotalRevenue(completed);
+    const timeMetrics = calculateAverageTimeMetrics(completed);
+
+    const firstAppointment = appointments[0];
+    const procedureInfo = firstAppointment?.procedureExtendedInfo || firstAppointment?.procedureInfo;
+
+    // Extract product usage
+    const productMap = new Map<
+      string,
+      { name: string; brandName: string; quantity: number; revenue: number; usageCount: number }
+    >();
+
+    completed.forEach(appointment => {
+      const products = extractProductUsage(appointment);
+      products.forEach(product => {
+        if (productMap.has(product.productId)) {
+          const existing = productMap.get(product.productId)!;
+          existing.quantity += product.quantity;
+          existing.revenue += product.subtotal;
+          existing.usageCount++;
+        } else {
+          productMap.set(product.productId, {
+            name: product.productName,
+            brandName: product.brandName,
+            quantity: product.quantity,
+            revenue: product.subtotal,
+            usageCount: 1,
+          });
+        }
+      });
+    });
+
+    const productUsage = Array.from(productMap.entries()).map(([productId, data]) => ({
+      productId,
+      productName: data.name,
+      brandName: data.brandName,
+      totalQuantity: data.quantity,
+      totalRevenue: data.revenue,
+      usageCount: data.usageCount,
+    }));
+
+    return {
+      total: appointments.length,
+      procedureId,
+      procedureName: procedureInfo?.name || 'Unknown',
+      procedureFamily: procedureInfo?.procedureFamily || '',
+      categoryName: procedureInfo?.procedureCategoryName || '',
+      subcategoryName: procedureInfo?.procedureSubCategoryName || '',
+      technologyName: procedureInfo?.procedureTechnologyName || '',
+      totalAppointments: appointments.length,
+      completedAppointments: completed.length,
+      canceledAppointments: canceled.length,
+      noShowAppointments: noShow.length,
+      cancellationRate: calculatePercentage(canceled.length, appointments.length),
+      noShowRate: calculatePercentage(noShow.length, appointments.length),
+      averageCost: completed.length > 0 ? totalRevenue / completed.length : 0,
+      totalRevenue,
+      averageRevenuePerAppointment: completed.length > 0 ? totalRevenue / completed.length : 0,
+      currency,
+      averageBookedDuration: timeMetrics.averageBookedDuration,
+      averageActualDuration: timeMetrics.averageActualDuration,
+      productUsage,
+    };
+  }
+
+  /**
+   * Get procedure popularity metrics
+   *
+   * @param dateRange - Optional date range filter
+   * @param limit - Number of top procedures to return
+   * @returns Array of procedure popularity metrics
+   */
+  async getProcedurePopularity(
+    dateRange?: AnalyticsDateRange,
+    limit: number = 10,
+  ): Promise<ProcedurePopularity[]> {
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const procedureMap = new Map<string, { name: string; category: string; subcategory: string; technology: string; count: number }>();
+
+    completed.forEach(appointment => {
+      const procId = appointment.procedureId;
+      const procInfo = appointment.procedureExtendedInfo || appointment.procedureInfo;
+
+      if (procedureMap.has(procId)) {
+        procedureMap.get(procId)!.count++;
+      } else {
+        procedureMap.set(procId, {
+          name: procInfo?.name || 'Unknown',
+          category: procInfo?.procedureCategoryName || '',
+          subcategory: procInfo?.procedureSubCategoryName || '',
+          technology: procInfo?.procedureTechnologyName || '',
+          count: 1,
+        });
+      }
+    });
+
+    return Array.from(procedureMap.entries())
+      .map(([procedureId, data]) => ({
+        procedureId,
+        procedureName: data.name,
+        categoryName: data.category,
+        subcategoryName: data.subcategory,
+        technologyName: data.technology,
+        appointmentCount: data.count,
+        completedCount: data.count,
+        rank: 0, // Will be set after sorting
+      }))
+      .sort((a, b) => b.appointmentCount - a.appointmentCount)
+      .slice(0, limit)
+      .map((item, index) => ({ ...item, rank: index + 1 }));
+  }
+
+  /**
+   * Get procedure profitability metrics
+   *
+   * @param dateRange - Optional date range filter
+   * @param limit - Number of top procedures to return
+   * @returns Array of procedure profitability metrics
+   */
+  async getProcedureProfitability(
+    dateRange?: AnalyticsDateRange,
+    limit: number = 10,
+  ): Promise<ProcedureProfitability[]> {
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const procedureMap = new Map<
+      string,
+      {
+        name: string;
+        category: string;
+        subcategory: string;
+        technology: string;
+        revenue: number;
+        count: number;
+      }
+    >();
+
+    completed.forEach(appointment => {
+      const procId = appointment.procedureId;
+      const procInfo = appointment.procedureExtendedInfo || appointment.procedureInfo;
+      const cost = calculateAppointmentCost(appointment).cost;
+
+      if (procedureMap.has(procId)) {
+        const existing = procedureMap.get(procId)!;
+        existing.revenue += cost;
+        existing.count++;
+      } else {
+        procedureMap.set(procId, {
+          name: procInfo?.name || 'Unknown',
+          category: procInfo?.procedureCategoryName || '',
+          subcategory: procInfo?.procedureSubCategoryName || '',
+          technology: procInfo?.procedureTechnologyName || '',
+          revenue: cost,
+          count: 1,
+        });
+      }
+    });
+
+    return Array.from(procedureMap.entries())
+      .map(([procedureId, data]) => ({
+        procedureId,
+        procedureName: data.name,
+        categoryName: data.category,
+        subcategoryName: data.subcategory,
+        technologyName: data.technology,
+        totalRevenue: data.revenue,
+        averageRevenue: data.count > 0 ? data.revenue / data.count : 0,
+        appointmentCount: data.count,
+        rank: 0, // Will be set after sorting
+      }))
+      .sort((a, b) => b.totalRevenue - a.totalRevenue)
+      .slice(0, limit)
+      .map((item, index) => ({ ...item, rank: index + 1 }));
+  }
+
+  // ==========================================
+  // Time Efficiency Analytics
+  // ==========================================
+
+  /**
+   * Get time efficiency metrics grouped by clinic, practitioner, procedure, patient, or technology
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'procedure' | 'patient' | 'technology'
+   * @param dateRange - Optional date range filter
+   * @param filters - Optional additional filters
+   * @returns Grouped time efficiency metrics
+   */
+  async getTimeEfficiencyMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedTimeEfficiencyMetrics[]> {
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    return calculateGroupedTimeEfficiencyMetrics(appointments, groupBy);
+  }
+
+  /**
+   * Get time efficiency metrics for appointments
+   * First checks for stored analytics, then calculates if not available or stale
+   *
+   * @param filters - Optional filters
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics
+   * @returns Time efficiency metrics
+   */
+  async getTimeEfficiencyMetrics(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<TimeEfficiencyMetrics> {
+    // Try to read from stored analytics first
+    if (filters?.clinicBranchId && dateRange && options?.useCache !== false) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const stored = await readStoredTimeEfficiencyMetrics(
+        this.db,
+        filters.clinicBranchId,
+        { ...options, period },
+      );
+
+      if (stored) {
+        // Return stored data (without metadata)
+        const { metadata, ...metrics } = stored;
+        return metrics;
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const timeMetrics = calculateAverageTimeMetrics(completed);
+    const efficiencyDistribution = calculateEfficiencyDistribution(completed);
+
+    return {
+      totalAppointments: completed.length,
+      appointmentsWithActualTime: timeMetrics.appointmentsWithActualTime,
+      averageBookedDuration: timeMetrics.averageBookedDuration,
+      averageActualDuration: timeMetrics.averageActualDuration,
+      averageEfficiency: timeMetrics.averageEfficiency,
+      totalOverrun: timeMetrics.totalOverrun,
+      totalUnderutilization: timeMetrics.totalUnderutilization,
+      averageOverrun: timeMetrics.averageOverrun,
+      averageUnderutilization: timeMetrics.averageUnderutilization,
+      efficiencyDistribution,
+    };
+  }
+
+  // ==========================================
+  // Cancellation & No-Show Analytics
+  // ==========================================
+
+  /**
+   * Get cancellation metrics
+   * First checks for stored analytics when grouping by clinic, then calculates if not available or stale
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'patient' | 'procedure' | 'technology'
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics (requires clinicBranchId for cache)
+   * @returns Cancellation metrics grouped by specified entity
+   */
+  async getCancellationMetrics(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<CancellationMetrics | CancellationMetrics[]> {
+    // Try to read from stored analytics first (only for clinic-level grouping)
+    if (groupBy === 'clinic' && dateRange && options?.useCache !== false && options?.clinicBranchId) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const stored = await readStoredCancellationMetrics(
+        this.db,
+        options.clinicBranchId,
+        'clinic',
+        { ...options, period },
+      );
+
+      if (stored) {
+        // Return stored data (without metadata)
+        const { metadata, ...metrics } = stored;
+        return metrics;
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const canceled = getCanceledAppointments(appointments);
+
+    if (groupBy === 'clinic') {
+      return this.groupCancellationsByClinic(canceled, appointments);
+    } else if (groupBy === 'practitioner') {
+      return this.groupCancellationsByPractitioner(canceled, appointments);
+    } else if (groupBy === 'patient') {
+      return this.groupCancellationsByPatient(canceled, appointments);
+    } else if (groupBy === 'technology') {
+      return this.groupCancellationsByTechnology(canceled, appointments);
+    } else {
+      return this.groupCancellationsByProcedure(canceled, appointments);
+    }
+  }
+
+  /**
+   * Group cancellations by clinic
+   */
+  private groupCancellationsByClinic(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const clinicMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const clinicId = appointment.clinicBranchId;
+      const clinicName = appointment.clinicInfo?.name || 'Unknown';
+
+      if (!clinicMap.has(clinicId)) {
+        clinicMap.set(clinicId, { name: clinicName, canceled: [], all: [] });
+      }
+      clinicMap.get(clinicId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const clinicId = appointment.clinicBranchId;
+      if (clinicMap.has(clinicId)) {
+        clinicMap.get(clinicId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(clinicMap.entries()).map(([clinicId, data]) =>
+      this.calculateCancellationMetrics(clinicId, data.name, 'clinic', data.canceled, data.all),
+    );
+  }
+
+  /**
+   * Group cancellations by practitioner
+   */
+  private groupCancellationsByPractitioner(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const practitionerMap = new Map<
+      string,
+      { name: string; canceled: Appointment[]; all: Appointment[] }
+    >();
+
+    allAppointments.forEach(appointment => {
+      const practitionerId = appointment.practitionerId;
+      const practitionerName = appointment.practitionerInfo?.name || 'Unknown';
+
+      if (!practitionerMap.has(practitionerId)) {
+        practitionerMap.set(practitionerId, { name: practitionerName, canceled: [], all: [] });
+      }
+      practitionerMap.get(practitionerId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const practitionerId = appointment.practitionerId;
+      if (practitionerMap.has(practitionerId)) {
+        practitionerMap.get(practitionerId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(practitionerMap.entries()).map(([practitionerId, data]) =>
+      this.calculateCancellationMetrics(
+        practitionerId,
+        data.name,
+        'practitioner',
+        data.canceled,
+        data.all,
+      ),
+    );
+  }
+
+  /**
+   * Group cancellations by patient
+   */
+  private groupCancellationsByPatient(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const patientMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const patientId = appointment.patientId;
+      const patientName = appointment.patientInfo?.fullName || 'Unknown';
+
+      if (!patientMap.has(patientId)) {
+        patientMap.set(patientId, { name: patientName, canceled: [], all: [] });
+      }
+      patientMap.get(patientId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const patientId = appointment.patientId;
+      if (patientMap.has(patientId)) {
+        patientMap.get(patientId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(patientMap.entries()).map(([patientId, data]) =>
+      this.calculateCancellationMetrics(patientId, data.name, 'patient', data.canceled, data.all),
+    );
+  }
+
+  /**
+   * Group cancellations by procedure
+   */
+  private groupCancellationsByProcedure(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const procedureMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[]; practitionerId?: string; practitionerName?: string }>();
+
+    allAppointments.forEach(appointment => {
+      const procedureId = appointment.procedureId;
+      const procedureName = appointment.procedureInfo?.name || 'Unknown';
+
+      if (!procedureMap.has(procedureId)) {
+        procedureMap.set(procedureId, { 
+          name: procedureName, 
+          canceled: [], 
+          all: [],
+          practitionerId: appointment.practitionerId,
+          practitionerName: appointment.practitionerInfo?.name,
+        });
+      }
+      procedureMap.get(procedureId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const procedureId = appointment.procedureId;
+      if (procedureMap.has(procedureId)) {
+        procedureMap.get(procedureId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(procedureMap.entries()).map(([procedureId, data]) => {
+      const metrics = this.calculateCancellationMetrics(
+        procedureId,
+        data.name,
+        'procedure',
+        data.canceled,
+        data.all,
+      );
+      return {
+        ...metrics,
+        ...(data.practitionerId && { practitionerId: data.practitionerId }),
+        ...(data.practitionerName && { practitionerName: data.practitionerName }),
+      };
+    });
+  }
+
+  /**
+   * Group cancellations by technology
+   * Aggregates all procedures using the same technology across all doctors
+   */
+  private groupCancellationsByTechnology(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const technologyMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const technologyId =
+        appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology';
+      const technologyName =
+        appointment.procedureExtendedInfo?.procedureTechnologyName ||
+        appointment.procedureInfo?.technologyName ||
+        'Unknown';
+
+      if (!technologyMap.has(technologyId)) {
+        technologyMap.set(technologyId, { name: technologyName, canceled: [], all: [] });
+      }
+      technologyMap.get(technologyId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const technologyId =
+        appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology';
+      if (technologyMap.has(technologyId)) {
+        technologyMap.get(technologyId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(technologyMap.entries()).map(([technologyId, data]) =>
+      this.calculateCancellationMetrics(
+        technologyId,
+        data.name,
+        'technology',
+        data.canceled,
+        data.all,
+      ),
+    );
+  }
+
+  /**
+   * Calculate cancellation metrics for a specific entity
+   */
+  private calculateCancellationMetrics(
+    entityId: string,
+    entityName: string,
+    entityType: EntityType,
+    canceled: Appointment[],
+    all: Appointment[],
+  ): CancellationMetrics {
+    const canceledByPatient = canceled.filter(
+      a => a.status === AppointmentStatus.CANCELED_PATIENT,
+    ).length;
+    const canceledByClinic = canceled.filter(
+      a => a.status === AppointmentStatus.CANCELED_CLINIC,
+    ).length;
+    const canceledRescheduled = canceled.filter(
+      a => a.status === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
+    ).length;
+
+    // Calculate average cancellation lead time
+    const leadTimes = canceled
+      .map(a => calculateCancellationLeadTime(a))
+      .filter((lt): lt is number => lt !== null);
+    const averageLeadTime =
+      leadTimes.length > 0 ? leadTimes.reduce((a, b) => a + b, 0) / leadTimes.length : 0;
+
+    // Group cancellation reasons
+    const reasonMap = new Map<string, number>();
+    canceled.forEach(appointment => {
+      const reason = appointment.cancellationReason || 'No reason provided';
+      reasonMap.set(reason, (reasonMap.get(reason) || 0) + 1);
+    });
+
+    const cancellationReasons = Array.from(reasonMap.entries()).map(([reason, count]) => ({
+      reason,
+      count,
+      percentage: calculatePercentage(count, canceled.length),
+    }));
+
+    return {
+      entityId,
+      entityName,
+      entityType,
+      totalAppointments: all.length,
+      canceledAppointments: canceled.length,
+      cancellationRate: calculatePercentage(canceled.length, all.length),
+      canceledByPatient,
+      canceledByClinic,
+      canceledByPractitioner: 0, // Not tracked in current status enum
+      canceledRescheduled,
+      averageCancellationLeadTime: Math.round(averageLeadTime * 100) / 100,
+      cancellationReasons,
+    };
+  }
+
+  /**
+   * Get no-show metrics
+   * First checks for stored analytics when grouping by clinic, then calculates if not available or stale
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'patient' | 'procedure' | 'technology'
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics (requires clinicBranchId for cache)
+   * @returns No-show metrics grouped by specified entity
+   */
+  async getNoShowMetrics(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<NoShowMetrics | NoShowMetrics[]> {
+    // Try to read from stored analytics first (only for clinic-level grouping)
+    if (groupBy === 'clinic' && dateRange && options?.useCache !== false && options?.clinicBranchId) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const stored = await readStoredNoShowMetrics(
+        this.db,
+        options.clinicBranchId,
+        'clinic',
+        { ...options, period },
+      );
+
+      if (stored) {
+        // Return stored data (without metadata)
+        const { metadata, ...metrics } = stored;
+        return metrics;
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const noShow = getNoShowAppointments(appointments);
+
+    if (groupBy === 'clinic') {
+      return this.groupNoShowsByClinic(noShow, appointments);
+    } else if (groupBy === 'practitioner') {
+      return this.groupNoShowsByPractitioner(noShow, appointments);
+    } else if (groupBy === 'patient') {
+      return this.groupNoShowsByPatient(noShow, appointments);
+    } else if (groupBy === 'technology') {
+      return this.groupNoShowsByTechnology(noShow, appointments);
+    } else {
+      return this.groupNoShowsByProcedure(noShow, appointments);
+    }
+  }
+
+  /**
+   * Group no-shows by clinic
+   */
+  private groupNoShowsByClinic(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const clinicMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const clinicId = appointment.clinicBranchId;
+      const clinicName = appointment.clinicInfo?.name || 'Unknown';
+      if (!clinicMap.has(clinicId)) {
+        clinicMap.set(clinicId, { name: clinicName, noShow: [], all: [] });
+      }
+      clinicMap.get(clinicId)!.all.push(appointment);
+    });
+
+    noShow.forEach(appointment => {
+      const clinicId = appointment.clinicBranchId;
+      if (clinicMap.has(clinicId)) {
+        clinicMap.get(clinicId)!.noShow.push(appointment);
+      }
+    });
+
+    return Array.from(clinicMap.entries()).map(([clinicId, data]) => ({
+      entityId: clinicId,
+      entityName: data.name,
+      entityType: 'clinic' as EntityType,
+      totalAppointments: data.all.length,
+      noShowAppointments: data.noShow.length,
+      noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+    }));
+  }
+
+  /**
+   * Group no-shows by practitioner
+   */
+  private groupNoShowsByPractitioner(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const practitionerMap = new Map<
+      string,
+      { name: string; noShow: Appointment[]; all: Appointment[] }
+    >();
+
+    allAppointments.forEach(appointment => {
+      const practitionerId = appointment.practitionerId;
+      const practitionerName = appointment.practitionerInfo?.name || 'Unknown';
+
+      if (!practitionerMap.has(practitionerId)) {
+        practitionerMap.set(practitionerId, { name: practitionerName, noShow: [], all: [] });
+      }
+      practitionerMap.get(practitionerId)!.all.push(appointment);
+    });
+
+    noShow.forEach(appointment => {
+      const practitionerId = appointment.practitionerId;
+      if (practitionerMap.has(practitionerId)) {
+        practitionerMap.get(practitionerId)!.noShow.push(appointment);
+      }
+    });
+
+    return Array.from(practitionerMap.entries()).map(([practitionerId, data]) => ({
+      entityId: practitionerId,
+      entityName: data.name,
+      entityType: 'practitioner' as EntityType,
+      totalAppointments: data.all.length,
+      noShowAppointments: data.noShow.length,
+      noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+    }));
+  }
+
+  /**
+   * Group no-shows by patient
+   */
+  private groupNoShowsByPatient(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const patientMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const patientId = appointment.patientId;
+      const patientName = appointment.patientInfo?.fullName || 'Unknown';
+
+      if (!patientMap.has(patientId)) {
+        patientMap.set(patientId, { name: patientName, noShow: [], all: [] });
+      }
+      patientMap.get(patientId)!.all.push(appointment);
+    });
+
+    noShow.forEach(appointment => {
+      const patientId = appointment.patientId;
+      if (patientMap.has(patientId)) {
+        patientMap.get(patientId)!.noShow.push(appointment);
+      }
+    });
+
+    return Array.from(patientMap.entries()).map(([patientId, data]) => ({
+      entityId: patientId,
+      entityName: data.name,
+      entityType: 'patient' as EntityType,
+      totalAppointments: data.all.length,
+      noShowAppointments: data.noShow.length,
+      noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+    }));
+  }
+
+  /**
+   * Group no-shows by procedure
+   */
+  private groupNoShowsByProcedure(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const procedureMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[]; practitionerId?: string; practitionerName?: string }>();
+
+    allAppointments.forEach(appointment => {
+      const procedureId = appointment.procedureId;
+      const procedureName = appointment.procedureInfo?.name || 'Unknown';
+
+      if (!procedureMap.has(procedureId)) {
+        procedureMap.set(procedureId, { 
+          name: procedureName, 
+          noShow: [], 
+          all: [],
+          practitionerId: appointment.practitionerId,
+          practitionerName: appointment.practitionerInfo?.name,
+        });
+      }
+      procedureMap.get(procedureId)!.all.push(appointment);
+    });
+
+    noShow.forEach(appointment => {
+      const procedureId = appointment.procedureId;
+      if (procedureMap.has(procedureId)) {
+        procedureMap.get(procedureId)!.noShow.push(appointment);
+      }
+    });
+
+    return Array.from(procedureMap.entries()).map(([procedureId, data]) => ({
+      entityId: procedureId,
+      entityName: data.name,
+      entityType: 'procedure' as EntityType,
+      totalAppointments: data.all.length,
+      noShowAppointments: data.noShow.length,
+      noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+      ...(data.practitionerId && { practitionerId: data.practitionerId }),
+      ...(data.practitionerName && { practitionerName: data.practitionerName }),
+    }));
+  }
+
+  /**
+   * Group no-shows by technology
+   * Aggregates all procedures using the same technology across all doctors
+   */
+  private groupNoShowsByTechnology(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const technologyMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const technologyId =
+        appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology';
+      const technologyName =
+        appointment.procedureExtendedInfo?.procedureTechnologyName ||
+        appointment.procedureInfo?.technologyName ||
+        'Unknown';
+
+      if (!technologyMap.has(technologyId)) {
+        technologyMap.set(technologyId, { name: technologyName, noShow: [], all: [] });
+      }
+      technologyMap.get(technologyId)!.all.push(appointment);
+    });
+
+    noShow.forEach(appointment => {
+      const technologyId =
+        appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology';
+      if (technologyMap.has(technologyId)) {
+        technologyMap.get(technologyId)!.noShow.push(appointment);
+      }
+    });
+
+    return Array.from(technologyMap.entries()).map(([technologyId, data]) => ({
+      entityId: technologyId,
+      entityName: data.name,
+      entityType: 'technology' as EntityType,
+      totalAppointments: data.all.length,
+      noShowAppointments: data.noShow.length,
+      noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+    }));
+  }
+
+  // ==========================================
+  // Financial Analytics
+  // ==========================================
+
+  /**
+   * Get revenue metrics grouped by clinic, practitioner, procedure, patient, or technology
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'procedure' | 'patient' | 'technology'
+   * @param dateRange - Optional date range filter
+   * @param filters - Optional additional filters
+   * @returns Grouped revenue metrics
+   */
+  async getRevenueMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedRevenueMetrics[]> {
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    return calculateGroupedRevenueMetrics(appointments, groupBy);
+  }
+
+  /**
+   * Get revenue metrics
+   * First checks for stored analytics, then calculates if not available or stale
+   *
+   * IMPORTANT: Financial calculations only consider COMPLETED appointments.
+   * Confirmed, pending, canceled, and no-show appointments are NOT included in revenue calculations.
+   * Only procedures that have been completed generate revenue.
+   *
+   * @param filters - Optional filters
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics
+   * @returns Revenue metrics
+   */
+  async getRevenueMetrics(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<RevenueMetrics> {
+    // Try to read from stored analytics first
+    if (filters?.clinicBranchId && dateRange && options?.useCache !== false) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const stored = await readStoredRevenueMetrics(
+        this.db,
+        filters.clinicBranchId,
+        { ...options, period },
+      );
+
+      if (stored) {
+        // Return stored data (without metadata)
+        const { metadata, ...metrics } = stored;
+        return metrics;
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const { totalRevenue, currency } = calculateTotalRevenue(completed);
+
+    // Calculate revenue by status - ONLY for COMPLETED appointments
+    // Financial calculations should only consider completed procedures
+    const revenueByStatus: Partial<Record<AppointmentStatus, number>> = {};
+    // Only calculate revenue for COMPLETED status (other statuses have no revenue)
+    const { totalRevenue: completedRevenue } = calculateTotalRevenue(completed);
+    revenueByStatus[AppointmentStatus.COMPLETED] = completedRevenue;
+    // All other statuses have 0 revenue (confirmed, pending, canceled, etc. don't generate revenue)
+
+    // Calculate revenue by payment status
+    const revenueByPaymentStatus: Partial<Record<PaymentStatus, number>> = {};
+    Object.values(PaymentStatus).forEach(paymentStatus => {
+      const paymentAppointments = completed.filter(a => a.paymentStatus === paymentStatus);
+      const { totalRevenue: paymentRevenue } = calculateTotalRevenue(paymentAppointments);
+      revenueByPaymentStatus[paymentStatus] = paymentRevenue;
+    });
+
+    const unpaid = completed.filter(a => a.paymentStatus === PaymentStatus.UNPAID);
+    const refunded = completed.filter(a => a.paymentStatus === PaymentStatus.REFUNDED);
+
+    const { totalRevenue: unpaidRevenue } = calculateTotalRevenue(unpaid);
+    const { totalRevenue: refundedRevenue } = calculateTotalRevenue(refunded);
+
+    // Calculate tax and subtotal from finalbilling if available
+    let totalTax = 0;
+    let totalSubtotal = 0;
+    completed.forEach(appointment => {
+      const costData = calculateAppointmentCost(appointment);
+      if (costData.source === 'finalbilling') {
+        totalTax += costData.tax || 0;
+        totalSubtotal += costData.subtotal || 0;
+      } else {
+        totalSubtotal += costData.cost;
+      }
+    });
+
+    return {
+      totalRevenue,
+      averageRevenuePerAppointment: completed.length > 0 ? totalRevenue / completed.length : 0,
+      totalAppointments: appointments.length,
+      completedAppointments: completed.length,
+      currency,
+      revenueByStatus,
+      revenueByPaymentStatus,
+      unpaidRevenue,
+      refundedRevenue,
+      totalTax,
+      totalSubtotal,
+    };
+  }
+
+  // ==========================================
+  // Product Usage Analytics
+  // ==========================================
+
+  /**
+   * Get product usage metrics grouped by clinic, practitioner, procedure, or patient
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'procedure' | 'patient'
+   * @param dateRange - Optional date range filter
+   * @param filters - Optional additional filters
+   * @returns Grouped product usage metrics
+   */
+  async getProductUsageMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedProductUsageMetrics[]> {
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    return calculateGroupedProductUsageMetrics(appointments, groupBy);
+  }
+
+  /**
+   * Get product usage metrics
+   *
+   * IMPORTANT: Only COMPLETED appointments are included in product usage calculations.
+   * Products are only considered "used" when the procedure has been completed.
+   * Confirmed, pending, canceled, and no-show appointments are excluded from product metrics.
+   *
+   * @param productId - Optional product ID (if not provided, returns all products)
+   * @param dateRange - Optional date range filter
+   * @param filters - Optional filters (e.g., clinicBranchId)
+   * @returns Product usage metrics
+   */
+  async getProductUsageMetrics(
+    productId?: string,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<ProductUsageMetrics | ProductUsageMetrics[]> {
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const productMap = new Map<
+      string,
+      {
+        name: string;
+        brandId: string;
+        brandName: string;
+        quantity: number;
+        revenue: number;
+        usageCount: number;
+        appointmentIds: Set<string>; // Track which appointments used this product
+        procedureMap: Map<string, { name: string; count: number; quantity: number }>;
+      }
+    >();
+
+    completed.forEach(appointment => {
+      const products = extractProductUsage(appointment);
+      // Track which products were used in this appointment to count appointments, not product entries
+      const productsInThisAppointment = new Set<string>();
+      
+      products.forEach(product => {
+        if (productId && product.productId !== productId) {
+          return;
+        }
+
+        if (!productMap.has(product.productId)) {
+          productMap.set(product.productId, {
+            name: product.productName,
+            brandId: product.brandId,
+            brandName: product.brandName,
+            quantity: 0,
+            revenue: 0,
+            usageCount: 0,
+            appointmentIds: new Set(),
+            procedureMap: new Map(),
+          });
+        }
+
+        const productData = productMap.get(product.productId)!;
+        productData.quantity += product.quantity;
+        productData.revenue += product.subtotal;
+        
+        // Track that this product was used in this appointment
+        productsInThisAppointment.add(product.productId);
+      });
+      
+      // After processing all products from this appointment, increment usageCount once per product
+      productsInThisAppointment.forEach(productId => {
+        const productData = productMap.get(productId)!;
+        if (!productData.appointmentIds.has(appointment.id)) {
+          productData.appointmentIds.add(appointment.id);
+          productData.usageCount++;
+          
+          // Track usage by procedure (only once per appointment)
+          const procId = appointment.procedureId;
+          const procName = appointment.procedureInfo?.name || 'Unknown';
+          if (productData.procedureMap.has(procId)) {
+            const procData = productData.procedureMap.get(procId)!;
+            procData.count++;
+            // Sum all quantities for this product in this appointment
+            const appointmentProducts = products.filter(p => p.productId === productId);
+            procData.quantity += appointmentProducts.reduce((sum, p) => sum + p.quantity, 0);
+          } else {
+            const appointmentProducts = products.filter(p => p.productId === productId);
+            const totalQuantity = appointmentProducts.reduce((sum, p) => sum + p.quantity, 0);
+            productData.procedureMap.set(procId, {
+              name: procName,
+              count: 1,
+              quantity: totalQuantity,
+            });
+          }
+        }
+      });
+    });
+
+    const results = Array.from(productMap.entries()).map(([productId, data]) => ({
+      productId,
+      productName: data.name,
+      brandId: data.brandId,
+      brandName: data.brandName,
+      totalQuantity: data.quantity,
+      totalRevenue: data.revenue,
+      averagePrice: data.usageCount > 0 ? data.revenue / data.quantity : 0,
+      currency: 'CHF', // Could be extracted from products
+      usageCount: data.usageCount,
+      averageQuantityPerAppointment:
+        data.usageCount > 0 ? data.quantity / data.usageCount : 0,
+      usageByProcedure: Array.from(data.procedureMap.entries()).map(([procId, procData]) => ({
+        procedureId: procId,
+        procedureName: procData.name,
+        count: procData.count,
+        totalQuantity: procData.quantity,
+      })),
+    }));
+
+    return productId ? results[0] : results;
+  }
+
+  // ==========================================
+  // Patient Analytics
+  // ==========================================
+
+  /**
+   * Get patient behavior metrics grouped by clinic, practitioner, procedure, or technology
+   * Shows patient no-show and cancellation patterns per entity
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'procedure' | 'technology'
+   * @param dateRange - Optional date range filter
+   * @param filters - Optional additional filters
+   * @returns Grouped patient behavior metrics
+   */
+  async getPatientBehaviorMetricsByEntity(
+    groupBy: 'clinic' | 'practitioner' | 'procedure' | 'technology',
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedPatientBehaviorMetrics[]> {
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    return calculateGroupedPatientBehaviorMetrics(appointments, groupBy);
+  }
+
+  /**
+   * Get patient analytics
+   *
+   * @param patientId - Optional patient ID (if not provided, returns aggregate)
+   * @param dateRange - Optional date range filter
+   * @returns Patient analytics
+   */
+  async getPatientAnalytics(
+    patientId?: string,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<PatientAnalytics | PatientAnalytics[]> {
+    const appointments = await this.fetchAppointments(patientId ? { patientId } : undefined, dateRange);
+
+    if (patientId) {
+      return this.calculatePatientAnalytics(appointments, patientId);
+    }
+
+    // Group by patient
+    const patientMap = new Map<string, Appointment[]>();
+    appointments.forEach(appointment => {
+      const patId = appointment.patientId;
+      if (!patientMap.has(patId)) {
+        patientMap.set(patId, []);
+      }
+      patientMap.get(patId)!.push(appointment);
+    });
+
+    return Array.from(patientMap.entries()).map(([patId, patAppointments]) =>
+      this.calculatePatientAnalytics(patAppointments, patId),
+    );
+  }
+
+  /**
+   * Calculate analytics for a specific patient
+   */
+  private calculatePatientAnalytics(appointments: Appointment[], patientId: string): PatientAnalytics {
+    const completed = getCompletedAppointments(appointments);
+    const canceled = getCanceledAppointments(appointments);
+    const noShow = getNoShowAppointments(appointments);
+
+    const { totalRevenue, currency } = calculateTotalRevenue(completed);
+
+    // Get appointment dates
+    const appointmentDates = appointments
+      .map(a => a.appointmentStartTime.toDate())
+      .sort((a, b) => a.getTime() - b.getTime());
+
+    const firstAppointmentDate = appointmentDates.length > 0 ? appointmentDates[0] : null;
+    const lastAppointmentDate =
+      appointmentDates.length > 0 ? appointmentDates[appointmentDates.length - 1] : null;
+
+    // Calculate average days between appointments
+    let averageDaysBetween = null;
+    if (appointmentDates.length > 1) {
+      const intervals: number[] = [];
+      for (let i = 1; i < appointmentDates.length; i++) {
+        const diffMs = appointmentDates[i].getTime() - appointmentDates[i - 1].getTime();
+        intervals.push(diffMs / (1000 * 60 * 60 * 24));
+      }
+      averageDaysBetween = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+    }
+
+    // Get unique practitioners and clinics
+    const uniquePractitioners = new Set(appointments.map(a => a.practitionerId));
+    const uniqueClinics = new Set(appointments.map(a => a.clinicBranchId));
+
+    // Get favorite procedures
+    const procedureMap = new Map<string, { name: string; count: number }>();
+    completed.forEach(appointment => {
+      const procId = appointment.procedureId;
+      const procName = appointment.procedureInfo?.name || 'Unknown';
+      procedureMap.set(procId, {
+        name: procName,
+        count: (procedureMap.get(procId)?.count || 0) + 1,
+      });
+    });
+
+    const favoriteProcedures = Array.from(procedureMap.entries())
+      .map(([procedureId, data]) => ({
+        procedureId,
+        procedureName: data.name,
+        count: data.count,
+      }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 5);
+
+    const patientName = appointments.length > 0 ? appointments[0].patientInfo?.fullName || 'Unknown' : 'Unknown';
+
+    return {
+      patientId,
+      patientName,
+      totalAppointments: appointments.length,
+      completedAppointments: completed.length,
+      canceledAppointments: canceled.length,
+      noShowAppointments: noShow.length,
+      cancellationRate: calculatePercentage(canceled.length, appointments.length),
+      noShowRate: calculatePercentage(noShow.length, appointments.length),
+      totalRevenue,
+      averageRevenuePerAppointment: completed.length > 0 ? totalRevenue / completed.length : 0,
+      currency,
+      lifetimeValue: totalRevenue,
+      firstAppointmentDate,
+      lastAppointmentDate,
+      averageDaysBetweenAppointments: averageDaysBetween ? Math.round(averageDaysBetween) : null,
+      uniquePractitioners: uniquePractitioners.size,
+      uniqueClinics: uniqueClinics.size,
+      favoriteProcedures,
+    };
+  }
+
+  // ==========================================
+  // Dashboard Analytics
+  // ==========================================
+
+  /**
+   * Determines analytics period from date range
+   */
+  private determinePeriodFromDateRange(dateRange: AnalyticsDateRange): AnalyticsPeriod {
+    const diffMs = dateRange.end.getTime() - dateRange.start.getTime();
+    const diffDays = diffMs / (1000 * 60 * 60 * 24);
+
+    if (diffDays <= 1) return 'daily';
+    if (diffDays <= 7) return 'weekly';
+    if (diffDays <= 31) return 'monthly';
+    if (diffDays <= 365) return 'yearly';
+    return 'all_time';
+  }
+
+  /**
+   * Get comprehensive dashboard data
+   * First checks for stored analytics, then calculates if not available or stale
+   *
+   * @param filters - Optional filters
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics
+   * @returns Complete dashboard analytics
+   */
+  async getDashboardData(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<DashboardAnalytics> {
+    // Try to read from stored analytics first
+    if (filters?.clinicBranchId && dateRange && options?.useCache !== false) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const stored = await readStoredDashboardAnalytics(
+        this.db,
+        filters.clinicBranchId,
+        { ...options, period },
+      );
+
+      if (stored) {
+        const { metadata, ...analytics } = stored;
+        return analytics;
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(filters, dateRange);
+
+    const completed = getCompletedAppointments(appointments);
+    const canceled = getCanceledAppointments(appointments);
+    const noShow = getNoShowAppointments(appointments);
+    const pending = appointments.filter(a => a.status === AppointmentStatus.PENDING);
+    const confirmed = appointments.filter(a => a.status === AppointmentStatus.CONFIRMED);
+
+    const { totalRevenue, currency } = calculateTotalRevenue(completed);
+
+    // Get unique counts
+    const uniquePatients = new Set(appointments.map(a => a.patientId));
+    const uniquePractitioners = new Set(appointments.map(a => a.practitionerId));
+    const uniqueProcedures = new Set(appointments.map(a => a.procedureId));
+
+    // Get top practitioners (limit to 5)
+    const practitionerMetrics = await Promise.all(
+      Array.from(uniquePractitioners)
+        .slice(0, 5)
+        .map(practitionerId => this.getPractitionerAnalytics(practitionerId, dateRange)),
+    );
+
+    // Get top procedures (limit to 5)
+    const procedureMetricsResults = await Promise.all(
+      Array.from(uniqueProcedures)
+        .slice(0, 5)
+        .map(procedureId => this.getProcedureAnalytics(procedureId, dateRange)),
+    );
+    // Filter out arrays and ensure we have ProcedureAnalytics objects
+    const procedureMetrics = procedureMetricsResults.filter(
+      (result): result is ProcedureAnalytics => !Array.isArray(result),
+    );
+
+    // Get cancellation and no-show metrics (aggregated)
+    const cancellationMetrics = await this.getCancellationMetrics('clinic', dateRange);
+    const noShowMetrics = await this.getNoShowMetrics('clinic', dateRange);
+
+    // Get time efficiency
+    const timeEfficiency = await this.getTimeEfficiencyMetrics(filters, dateRange);
+
+    // Get top products
+    const productMetrics = await this.getProductUsageMetrics(undefined, dateRange);
+    const topProducts = Array.isArray(productMetrics)
+      ? productMetrics.sort((a, b) => b.totalRevenue - a.totalRevenue).slice(0, 5)
+      : [];
+
+    // Get recent activity (last 10 appointments)
+    const recentActivity = appointments
+      .sort((a, b) => b.appointmentStartTime.toMillis() - a.appointmentStartTime.toMillis())
+      .slice(0, 10)
+      .map(appointment => {
+        let type: 'appointment' | 'cancellation' | 'completion' | 'no_show' = 'appointment';
+        let description = '';
+
+        if (appointment.status === AppointmentStatus.COMPLETED) {
+          type = 'completion';
+          description = `Appointment completed: ${appointment.procedureInfo?.name || 'Unknown procedure'}`;
+        } else if (
+          appointment.status === AppointmentStatus.CANCELED_PATIENT ||
+          appointment.status === AppointmentStatus.CANCELED_CLINIC ||
+          appointment.status === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED
+        ) {
+          type = 'cancellation';
+          description = `Appointment canceled: ${appointment.procedureInfo?.name || 'Unknown procedure'}`;
+        } else if (appointment.status === AppointmentStatus.NO_SHOW) {
+          type = 'no_show';
+          description = `No-show: ${appointment.procedureInfo?.name || 'Unknown procedure'}`;
+        } else {
+          description = `Appointment ${appointment.status}: ${appointment.procedureInfo?.name || 'Unknown procedure'}`;
+        }
+
+        return {
+          type,
+          date: appointment.appointmentStartTime.toDate(),
+          description,
+          entityId: appointment.practitionerId,
+          entityName: appointment.practitionerInfo?.name || 'Unknown',
+        };
+      });
+
+    return {
+      overview: {
+        totalAppointments: appointments.length,
+        completedAppointments: completed.length,
+        canceledAppointments: canceled.length,
+        noShowAppointments: noShow.length,
+        pendingAppointments: pending.length,
+        confirmedAppointments: confirmed.length,
+        totalRevenue,
+        averageRevenuePerAppointment: completed.length > 0 ? totalRevenue / completed.length : 0,
+        currency,
+        uniquePatients: uniquePatients.size,
+        uniquePractitioners: uniquePractitioners.size,
+        uniqueProcedures: uniqueProcedures.size,
+        cancellationRate: calculatePercentage(canceled.length, appointments.length),
+        noShowRate: calculatePercentage(noShow.length, appointments.length),
+      },
+      practitionerMetrics: Array.isArray(practitionerMetrics) ? practitionerMetrics : [],
+      procedureMetrics: Array.isArray(procedureMetrics) ? procedureMetrics : [],
+      cancellationMetrics: Array.isArray(cancellationMetrics) ? cancellationMetrics[0] : cancellationMetrics,
+      noShowMetrics: Array.isArray(noShowMetrics) ? noShowMetrics[0] : noShowMetrics,
+      revenueTrends: [], // TODO: Implement revenue trends
+      timeEfficiency,
+      topProducts,
+      recentActivity,
+    };
+  }
+
+  /**
+   * Calculate revenue trends over time
+   * Groups appointments by week/month/quarter/year and calculates revenue metrics
+   *
+   * @param dateRange - Date range for trend analysis (must align with period boundaries)
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters for clinic, practitioner, procedure, patient
+   * @param groupBy - Optional entity type to group trends by (clinic, practitioner, procedure, technology, patient)
+   * @returns Array of revenue trends with percentage changes
+   */
+  async getRevenueTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    groupBy?: EntityType,
+  ): Promise<RevenueTrend[]> {
+    const appointments = await this.fetchAppointments(filters);
+    const filtered = filterByDateRange(appointments, dateRange);
+
+    if (filtered.length === 0) {
+      return [];
+    }
+
+    // If grouping by entity, calculate trends per entity
+    if (groupBy) {
+      return this.getGroupedRevenueTrends(filtered, dateRange, period, groupBy);
+    }
+
+    // Calculate overall trends
+    const periodMap = groupAppointmentsByPeriod(filtered, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: RevenueTrend[] = [];
+
+    let previousRevenue = 0;
+    let previousAppointmentCount = 0;
+
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      const completed = getCompletedAppointments(periodAppointments);
+      const { totalRevenue, currency } = calculateTotalRevenue(completed);
+
+      const appointmentCount = completed.length;
+      const averageRevenue = appointmentCount > 0 ? totalRevenue / appointmentCount : 0;
+
+      const trend: RevenueTrend = {
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        revenue: totalRevenue,
+        appointmentCount,
+        averageRevenue,
+        currency,
+      };
+
+      // Calculate percentage change from previous period
+      if (previousRevenue > 0 || previousAppointmentCount > 0) {
+        const revenueChange = getTrendChange(totalRevenue, previousRevenue);
+        trend.previousPeriod = {
+          revenue: previousRevenue,
+          appointmentCount: previousAppointmentCount,
+          percentageChange: revenueChange.percentageChange,
+          direction: revenueChange.direction,
+        };
+      }
+
+      trends.push(trend);
+      previousRevenue = totalRevenue;
+      previousAppointmentCount = appointmentCount;
+    });
+
+    return trends;
+  }
+
+  /**
+   * Calculate revenue trends grouped by entity
+   */
+  private async getGroupedRevenueTrends(
+    appointments: Appointment[],
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    groupBy: EntityType,
+  ): Promise<RevenueTrend[]> {
+    const periodMap = groupAppointmentsByPeriod(appointments, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: RevenueTrend[] = [];
+
+    // Group appointments by entity for each period
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      if (periodAppointments.length === 0) return;
+
+      const groupedMetrics = calculateGroupedRevenueMetrics(periodAppointments, groupBy);
+      
+      // Sum up all entities for this period
+      const totalRevenue = groupedMetrics.reduce((sum, m) => sum + m.totalRevenue, 0);
+      const totalAppointments = groupedMetrics.reduce((sum, m) => sum + m.totalAppointments, 0);
+      const currency = groupedMetrics[0]?.currency || 'CHF';
+      const averageRevenue = totalAppointments > 0 ? totalRevenue / totalAppointments : 0;
+
+      trends.push({
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        revenue: totalRevenue,
+        appointmentCount: totalAppointments,
+        averageRevenue,
+        currency,
+      });
+    });
+
+    // Calculate percentage changes
+    for (let i = 1; i < trends.length; i++) {
+      const current = trends[i];
+      const previous = trends[i - 1];
+      const revenueChange = getTrendChange(current.revenue, previous.revenue);
+      
+      current.previousPeriod = {
+        revenue: previous.revenue,
+        appointmentCount: previous.appointmentCount,
+        percentageChange: revenueChange.percentageChange,
+        direction: revenueChange.direction,
+      };
+    }
+
+    return trends;
+  }
+
+  /**
+   * Calculate duration/efficiency trends over time
+   *
+   * @param dateRange - Date range for trend analysis
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters
+   * @param groupBy - Optional entity type to group trends by
+   * @returns Array of duration trends with percentage changes
+   */
+  async getDurationTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    groupBy?: EntityType,
+  ): Promise<DurationTrend[]> {
+    const appointments = await this.fetchAppointments(filters);
+    const filtered = filterByDateRange(appointments, dateRange);
+
+    if (filtered.length === 0) {
+      return [];
+    }
+
+    const periodMap = groupAppointmentsByPeriod(filtered, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: DurationTrend[] = [];
+
+    let previousEfficiency = 0;
+    let previousBookedDuration = 0;
+    let previousActualDuration = 0;
+
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      const completed = getCompletedAppointments(periodAppointments);
+
+      if (groupBy) {
+        // Group by entity and calculate average
+        const groupedMetrics = calculateGroupedTimeEfficiencyMetrics(completed, groupBy);
+        if (groupedMetrics.length === 0) return;
+
+        const totalAppointments = groupedMetrics.reduce((sum, m) => sum + m.totalAppointments, 0);
+        const weightedBooked = groupedMetrics.reduce(
+          (sum, m) => sum + m.averageBookedDuration * m.totalAppointments,
+          0,
+        );
+        const weightedActual = groupedMetrics.reduce(
+          (sum, m) => sum + m.averageActualDuration * m.totalAppointments,
+          0,
+        );
+        const weightedEfficiency = groupedMetrics.reduce(
+          (sum, m) => sum + m.averageEfficiency * m.totalAppointments,
+          0,
+        );
+
+        const averageBookedDuration = totalAppointments > 0 ? weightedBooked / totalAppointments : 0;
+        const averageActualDuration = totalAppointments > 0 ? weightedActual / totalAppointments : 0;
+        const averageEfficiency = totalAppointments > 0 ? weightedEfficiency / totalAppointments : 0;
+
+        const trend: DurationTrend = {
+          period: periodInfo.period,
+          startDate: periodInfo.startDate,
+          endDate: periodInfo.endDate,
+          averageBookedDuration,
+          averageActualDuration,
+          averageEfficiency,
+          appointmentCount: totalAppointments,
+        };
+
+        if (previousEfficiency > 0) {
+          const efficiencyChange = getTrendChange(averageEfficiency, previousEfficiency);
+          trend.previousPeriod = {
+            averageBookedDuration: previousBookedDuration,
+            averageActualDuration: previousActualDuration,
+            averageEfficiency: previousEfficiency,
+            efficiencyPercentageChange: efficiencyChange.percentageChange,
+            direction: efficiencyChange.direction,
+          };
+        }
+
+        trends.push(trend);
+        previousEfficiency = averageEfficiency;
+        previousBookedDuration = averageBookedDuration;
+        previousActualDuration = averageActualDuration;
+      } else {
+        // Overall trends
+        const timeMetrics = calculateAverageTimeMetrics(completed);
+
+        const trend: DurationTrend = {
+          period: periodInfo.period,
+          startDate: periodInfo.startDate,
+          endDate: periodInfo.endDate,
+          averageBookedDuration: timeMetrics.averageBookedDuration,
+          averageActualDuration: timeMetrics.averageActualDuration,
+          averageEfficiency: timeMetrics.averageEfficiency,
+          appointmentCount: timeMetrics.appointmentsWithActualTime,
+        };
+
+        if (previousEfficiency > 0) {
+          const efficiencyChange = getTrendChange(timeMetrics.averageEfficiency, previousEfficiency);
+          trend.previousPeriod = {
+            averageBookedDuration: previousBookedDuration,
+            averageActualDuration: previousActualDuration,
+            averageEfficiency: previousEfficiency,
+            efficiencyPercentageChange: efficiencyChange.percentageChange,
+            direction: efficiencyChange.direction,
+          };
+        }
+
+        trends.push(trend);
+        previousEfficiency = timeMetrics.averageEfficiency;
+        previousBookedDuration = timeMetrics.averageBookedDuration;
+        previousActualDuration = timeMetrics.averageActualDuration;
+      }
+    });
+
+    return trends;
+  }
+
+  /**
+   * Calculate appointment count trends over time
+   *
+   * @param dateRange - Date range for trend analysis
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters
+   * @param groupBy - Optional entity type to group trends by
+   * @returns Array of appointment trends with percentage changes
+   */
+  async getAppointmentTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    groupBy?: EntityType,
+  ): Promise<AppointmentTrend[]> {
+    const appointments = await this.fetchAppointments(filters);
+    const filtered = filterByDateRange(appointments, dateRange);
+
+    if (filtered.length === 0) {
+      return [];
+    }
+
+    const periodMap = groupAppointmentsByPeriod(filtered, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: AppointmentTrend[] = [];
+
+    let previousTotal = 0;
+    let previousCompleted = 0;
+
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      const completed = getCompletedAppointments(periodAppointments);
+      const canceled = getCanceledAppointments(periodAppointments);
+      const noShow = getNoShowAppointments(periodAppointments);
+      const pending = periodAppointments.filter(a => a.status === AppointmentStatus.PENDING);
+      const confirmed = periodAppointments.filter(a => a.status === AppointmentStatus.CONFIRMED);
+
+      const trend: AppointmentTrend = {
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        totalAppointments: periodAppointments.length,
+        completedAppointments: completed.length,
+        canceledAppointments: canceled.length,
+        noShowAppointments: noShow.length,
+        pendingAppointments: pending.length,
+        confirmedAppointments: confirmed.length,
+      };
+
+      if (previousTotal > 0) {
+        const totalChange = getTrendChange(periodAppointments.length, previousTotal);
+        trend.previousPeriod = {
+          totalAppointments: previousTotal,
+          completedAppointments: previousCompleted,
+          percentageChange: totalChange.percentageChange,
+          direction: totalChange.direction,
+        };
+      }
+
+      trends.push(trend);
+      previousTotal = periodAppointments.length;
+      previousCompleted = completed.length;
+    });
+
+    return trends;
+  }
+
+  /**
+   * Calculate cancellation and no-show rate trends over time
+   *
+   * @param dateRange - Date range for trend analysis
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters
+   * @param groupBy - Optional entity type to group trends by
+   * @returns Array of cancellation rate trends with percentage changes
+   */
+  async getCancellationRateTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    groupBy?: EntityType,
+  ): Promise<CancellationRateTrend[]> {
+    const appointments = await this.fetchAppointments(filters);
+    const filtered = filterByDateRange(appointments, dateRange);
+
+    if (filtered.length === 0) {
+      return [];
+    }
+
+    const periodMap = groupAppointmentsByPeriod(filtered, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: CancellationRateTrend[] = [];
+
+    let previousCancellationRate = 0;
+    let previousNoShowRate = 0;
+
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      const canceled = getCanceledAppointments(periodAppointments);
+      const noShow = getNoShowAppointments(periodAppointments);
+
+      const cancellationRate = calculatePercentage(canceled.length, periodAppointments.length);
+      const noShowRate = calculatePercentage(noShow.length, periodAppointments.length);
+
+      const trend: CancellationRateTrend = {
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        cancellationRate,
+        noShowRate,
+        totalAppointments: periodAppointments.length,
+        canceledAppointments: canceled.length,
+        noShowAppointments: noShow.length,
+      };
+
+      if (previousCancellationRate > 0 || previousNoShowRate > 0) {
+        const cancellationChange = getTrendChange(cancellationRate, previousCancellationRate);
+        const noShowChange = getTrendChange(noShowRate, previousNoShowRate);
+        
+        trend.previousPeriod = {
+          cancellationRate: previousCancellationRate,
+          noShowRate: previousNoShowRate,
+          cancellationRateChange: cancellationChange.percentageChange,
+          noShowRateChange: noShowChange.percentageChange,
+          direction: cancellationChange.direction, // Use cancellation direction as primary
+        };
+      }
+
+      trends.push(trend);
+      previousCancellationRate = cancellationRate;
+      previousNoShowRate = noShowRate;
+    });
+
+    return trends;
+  }
+
+  // ==========================================
+  // Review Analytics Methods
+  // ==========================================
+
+  /**
+   * Get review metrics for a specific entity (practitioner, procedure, etc.)
+   */
+  async getReviewMetricsByEntity(
+    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
+    entityId: string,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewAnalyticsMetrics | null> {
+    return this.reviewAnalyticsService.getReviewMetricsByEntity(entityType, entityId, dateRange, filters);
+  }
+
+  /**
+   * Get review metrics for multiple entities (grouped)
+   */
+  async getReviewMetricsByEntities(
+    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewAnalyticsMetrics[]> {
+    return this.reviewAnalyticsService.getReviewMetricsByEntities(entityType, dateRange, filters);
+  }
+
+  /**
+   * Get overall review averages for comparison
+   */
+  async getOverallReviewAverages(
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<OverallReviewAverages> {
+    return this.reviewAnalyticsService.getOverallReviewAverages(dateRange, filters);
+  }
+
+  /**
+   * Get review details for a specific entity
+   */
+  async getReviewDetails(
+    entityType: 'practitioner' | 'procedure',
+    entityId: string,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewDetail[]> {
+    return this.reviewAnalyticsService.getReviewDetails(entityType, entityId, dateRange, filters);
+  }
+
+  /**
+   * Calculate review trends over time
+   * Groups reviews by period and calculates rating and recommendation metrics
+   *
+   * @param dateRange - Date range for trend analysis
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters for clinic, practitioner, procedure
+   * @param entityType - Optional entity type to group trends by
+   * @returns Array of review trends with percentage changes
+   */
+  async getReviewTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    entityType?: 'practitioner' | 'procedure' | 'technology'
+  ): Promise<ReviewTrend[]> {
+    return this.reviewAnalyticsService.getReviewTrends(dateRange, period, filters, entityType);
+  }
+}
+