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

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

@@ -1,2148 +1,2148 @@
-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 - filter by clinic if specified
-    const filters: AnalyticsFilters | undefined = options?.clinicBranchId
-      ? { clinicBranchId: options.clinicBranchId }
-      : undefined;
-    const appointments = await this.fetchAppointments(filters, 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 - filter by clinic if specified
-    const filters: AnalyticsFilters | undefined = options?.clinicBranchId
-      ? { clinicBranchId: options.clinicBranchId }
-      : undefined;
-    const appointments = await this.fetchAppointments(filters, 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);
-  }
-}
-
+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 - filter by clinic if specified
+    const filters: AnalyticsFilters | undefined = options?.clinicBranchId
+      ? { clinicBranchId: options.clinicBranchId }
+      : undefined;
+    const appointments = await this.fetchAppointments(filters, 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 - filter by clinic if specified
+    const filters: AnalyticsFilters | undefined = options?.clinicBranchId
+      ? { clinicBranchId: options.clinicBranchId }
+      : undefined;
+    const appointments = await this.fetchAppointments(filters, 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);
+  }
+}
+