@blackcode_sa/metaestetics-api 1.12.68 → 1.13.0

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

@@ -0,0 +1,1632 @@
+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,
+  ProductUsageMetrics,
+  ProductRevenueMetrics,
+  ProductUsageByProcedure,
+  PatientAnalytics,
+  PatientLifetimeValueMetrics,
+  PatientRetentionMetrics,
+  CostPerPatientMetrics,
+  PaymentStatusBreakdown,
+  ClinicAnalytics,
+  ClinicComparisonMetrics,
+  ProcedurePopularity,
+  ProcedureProfitability,
+  CancellationReasonStats,
+  DashboardAnalytics,
+  AnalyticsDateRange,
+  AnalyticsFilters,
+  GroupingPeriod,
+  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 { ReadStoredAnalyticsOptions, AnalyticsPeriod } from '../../types/analytics';
+import {
+  GroupedRevenueMetrics,
+  GroupedProductUsageMetrics,
+  GroupedTimeEfficiencyMetrics,
+  GroupedPatientBehaviorMetrics,
+} from '../../types/analytics/grouped-analytics.types';
+
+/**
+ * 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;
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Fetches appointments with optional filters
+   *
+   * @param filters - Optional filters
+   * @param dateRange - Optional date range
+   * @returns Array of appointments
+   */
+  private async fetchAppointments(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<Appointment[]> {
+    try {
+      // Build query constraints
+      const constraints: any[] = [];
+
+      if (filters?.clinicBranchId) {
+        constraints.push(where('clinicBranchId', '==', filters.clinicBranchId));
+      }
+      if (filters?.practitionerId) {
+        constraints.push(where('practitionerId', '==', filters.practitionerId));
+      }
+      if (filters?.procedureId) {
+        constraints.push(where('procedureId', '==', filters.procedureId));
+      }
+      if (filters?.patientId) {
+        constraints.push(where('patientId', '==', filters.patientId));
+      }
+      if (dateRange) {
+        constraints.push(where('appointmentStartTime', '>=', Timestamp.fromDate(dateRange.start)));
+        constraints.push(where('appointmentStartTime', '<=', Timestamp.fromDate(dateRange.end)));
+      }
+
+      // Use AppointmentService to search appointments
+      const searchParams: any = {};
+      if (filters?.clinicBranchId) searchParams.clinicBranchId = filters.clinicBranchId;
+      if (filters?.practitionerId) searchParams.practitionerId = filters.practitionerId;
+      if (filters?.procedureId) searchParams.procedureId = filters.procedureId;
+      if (filters?.patientId) searchParams.patientId = filters.patientId;
+      if (dateRange) {
+        searchParams.startDate = dateRange.start;
+        searchParams.endDate = dateRange.end;
+      }
+
+      const result = await this.appointmentService.searchAppointments(searchParams);
+
+      return result.appointments;
+    } catch (error) {
+      console.error('[AnalyticsService] Error fetching appointments:', error);
+      throw error;
+    }
+  }
+
+  // ==========================================
+  // Practitioner Analytics
+  // ==========================================
+
+  /**
+   * Get practitioner performance metrics
+   * First checks for stored analytics, then calculates if not available or stale
+   *
+   * @param practitionerId - ID of the practitioner
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics
+   * @returns Practitioner analytics object
+   */
+  async getPractitionerAnalytics(
+    practitionerId: string,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<PractitionerAnalytics> {
+    // Try to read from stored analytics first
+    if (dateRange && options?.useCache !== false) {
+      // Determine period from date range
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const clinicBranchId = options?.clinicBranchId; // Would need to be passed or determined
+
+      if (clinicBranchId) {
+        const stored = await readStoredPractitionerAnalytics(
+          this.db,
+          clinicBranchId,
+          practitionerId,
+          { ...options, period },
+        );
+
+        if (stored) {
+          // Return stored data (without metadata)
+          const { metadata, ...analytics } = stored;
+          return analytics;
+        }
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments({ practitionerId }, dateRange);
+
+    const completed = getCompletedAppointments(appointments);
+    const canceled = getCanceledAppointments(appointments);
+    const noShow = getNoShowAppointments(appointments);
+    const pending = filterAppointments(appointments, { practitionerId }).filter(
+      a => a.status === AppointmentStatus.PENDING,
+    );
+    const confirmed = filterAppointments(appointments, { practitionerId }).filter(
+      a => a.status === AppointmentStatus.CONFIRMED,
+    );
+
+    const { totalRevenue, currency } = calculateTotalRevenue(completed);
+    const timeMetrics = calculateAverageTimeMetrics(completed);
+
+    // Get unique patients
+    const uniquePatients = new Set(appointments.map(a => a.patientId));
+    const returningPatients = new Set(
+      appointments
+        .filter(a => {
+          const patientAppointments = appointments.filter(ap => ap.patientId === a.patientId);
+          return patientAppointments.length > 1;
+        })
+        .map(a => a.patientId),
+    );
+
+    // Get top procedures
+    const procedureMap = new Map<string, { name: string; count: number; revenue: number }>();
+    completed.forEach(appointment => {
+      const procId = appointment.procedureId;
+      const procName = appointment.procedureInfo?.name || 'Unknown';
+      const cost = calculateAppointmentCost(appointment).cost;
+
+      if (procedureMap.has(procId)) {
+        const existing = procedureMap.get(procId)!;
+        existing.count++;
+        existing.revenue += cost;
+      } else {
+        procedureMap.set(procId, { name: procName, count: 1, revenue: cost });
+      }
+    });
+
+    const topProcedures = Array.from(procedureMap.entries())
+      .map(([procedureId, data]) => ({
+        procedureId,
+        procedureName: data.name,
+        count: data.count,
+        revenue: data.revenue,
+      }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 10);
+
+    const practitionerName =
+      appointments.length > 0
+        ? appointments[0].practitionerInfo?.name || 'Unknown'
+        : 'Unknown';
+
+    return {
+      total: appointments.length,
+      dateRange,
+      practitionerId,
+      practitionerName,
+      totalAppointments: appointments.length,
+      completedAppointments: completed.length,
+      canceledAppointments: canceled.length,
+      noShowAppointments: noShow.length,
+      pendingAppointments: pending.length,
+      confirmedAppointments: confirmed.length,
+      cancellationRate: calculatePercentage(canceled.length, appointments.length),
+      noShowRate: calculatePercentage(noShow.length, appointments.length),
+      averageBookedTime: timeMetrics.averageBookedDuration,
+      averageActualTime: timeMetrics.averageActualDuration,
+      timeEfficiency: timeMetrics.averageEfficiency,
+      totalRevenue,
+      averageRevenuePerAppointment: completed.length > 0 ? totalRevenue / completed.length : 0,
+      currency,
+      topProcedures,
+      patientRetentionRate: calculatePercentage(returningPatients.size, uniquePatients.size),
+      uniquePatients: uniquePatients.size,
+    };
+  }
+
+  // ==========================================
+  // Procedure Analytics
+  // ==========================================
+
+  /**
+   * Get procedure performance metrics
+   * First checks for stored analytics, then calculates if not available or stale
+   *
+   * @param procedureId - ID of the procedure (optional, if not provided returns all)
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics
+   * @returns Procedure analytics object or array
+   */
+  async getProcedureAnalytics(
+    procedureId?: string,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<ProcedureAnalytics | ProcedureAnalytics[]> {
+    // Try to read from stored analytics first (only for single procedure)
+    if (procedureId && dateRange && options?.useCache !== false) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const clinicBranchId = options?.clinicBranchId;
+      
+      if (clinicBranchId) {
+        const stored = await readStoredProcedureAnalytics(
+          this.db,
+          clinicBranchId,
+          procedureId,
+          { ...options, period },
+        );
+
+        if (stored) {
+          // Return stored data (without metadata)
+          const { metadata, ...analytics } = stored;
+          return analytics;
+        }
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(procedureId ? { procedureId } : undefined, dateRange);
+
+    if (procedureId) {
+      return this.calculateProcedureAnalytics(appointments, procedureId);
+    }
+
+    // Group by procedure
+    const procedureMap = new Map<string, Appointment[]>();
+    appointments.forEach(appointment => {
+      const procId = appointment.procedureId;
+      if (!procedureMap.has(procId)) {
+        procedureMap.set(procId, []);
+      }
+      procedureMap.get(procId)!.push(appointment);
+    });
+
+    return Array.from(procedureMap.entries()).map(([procId, procAppointments]) =>
+      this.calculateProcedureAnalytics(procAppointments, procId),
+    );
+  }
+
+  /**
+   * Calculate analytics for a specific procedure
+   *
+   * @param appointments - Appointments for the procedure
+   * @param procedureId - Procedure ID
+   * @returns Procedure analytics
+   */
+  private calculateProcedureAnalytics(
+    appointments: Appointment[],
+    procedureId: string,
+  ): ProcedureAnalytics {
+    const completed = getCompletedAppointments(appointments);
+    const canceled = getCanceledAppointments(appointments);
+    const noShow = getNoShowAppointments(appointments);
+
+    const { totalRevenue, currency } = calculateTotalRevenue(completed);
+    const timeMetrics = calculateAverageTimeMetrics(completed);
+
+    const firstAppointment = appointments[0];
+    const procedureInfo = firstAppointment?.procedureExtendedInfo || firstAppointment?.procedureInfo;
+
+    // Extract product usage
+    const productMap = new Map<
+      string,
+      { name: string; brandName: string; quantity: number; revenue: number; usageCount: number }
+    >();
+
+    completed.forEach(appointment => {
+      const products = extractProductUsage(appointment);
+      products.forEach(product => {
+        if (productMap.has(product.productId)) {
+          const existing = productMap.get(product.productId)!;
+          existing.quantity += product.quantity;
+          existing.revenue += product.subtotal;
+          existing.usageCount++;
+        } else {
+          productMap.set(product.productId, {
+            name: product.productName,
+            brandName: product.brandName,
+            quantity: product.quantity,
+            revenue: product.subtotal,
+            usageCount: 1,
+          });
+        }
+      });
+    });
+
+    const productUsage = Array.from(productMap.entries()).map(([productId, data]) => ({
+      productId,
+      productName: data.name,
+      brandName: data.brandName,
+      totalQuantity: data.quantity,
+      totalRevenue: data.revenue,
+      usageCount: data.usageCount,
+    }));
+
+    return {
+      total: appointments.length,
+      procedureId,
+      procedureName: procedureInfo?.name || 'Unknown',
+      procedureFamily: procedureInfo?.procedureFamily || '',
+      categoryName: procedureInfo?.procedureCategoryName || '',
+      subcategoryName: procedureInfo?.procedureSubCategoryName || '',
+      technologyName: procedureInfo?.procedureTechnologyName || '',
+      totalAppointments: appointments.length,
+      completedAppointments: completed.length,
+      canceledAppointments: canceled.length,
+      noShowAppointments: noShow.length,
+      cancellationRate: calculatePercentage(canceled.length, appointments.length),
+      noShowRate: calculatePercentage(noShow.length, appointments.length),
+      averageCost: completed.length > 0 ? totalRevenue / completed.length : 0,
+      totalRevenue,
+      averageRevenuePerAppointment: completed.length > 0 ? totalRevenue / completed.length : 0,
+      currency,
+      averageBookedDuration: timeMetrics.averageBookedDuration,
+      averageActualDuration: timeMetrics.averageActualDuration,
+      productUsage,
+    };
+  }
+
+  /**
+   * Get procedure popularity metrics
+   *
+   * @param dateRange - Optional date range filter
+   * @param limit - Number of top procedures to return
+   * @returns Array of procedure popularity metrics
+   */
+  async getProcedurePopularity(
+    dateRange?: AnalyticsDateRange,
+    limit: number = 10,
+  ): Promise<ProcedurePopularity[]> {
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const procedureMap = new Map<string, { name: string; category: string; subcategory: string; technology: string; count: number }>();
+
+    completed.forEach(appointment => {
+      const procId = appointment.procedureId;
+      const procInfo = appointment.procedureExtendedInfo || appointment.procedureInfo;
+
+      if (procedureMap.has(procId)) {
+        procedureMap.get(procId)!.count++;
+      } else {
+        procedureMap.set(procId, {
+          name: procInfo?.name || 'Unknown',
+          category: procInfo?.procedureCategoryName || '',
+          subcategory: procInfo?.procedureSubCategoryName || '',
+          technology: procInfo?.procedureTechnologyName || '',
+          count: 1,
+        });
+      }
+    });
+
+    return Array.from(procedureMap.entries())
+      .map(([procedureId, data]) => ({
+        procedureId,
+        procedureName: data.name,
+        categoryName: data.category,
+        subcategoryName: data.subcategory,
+        technologyName: data.technology,
+        appointmentCount: data.count,
+        completedCount: data.count,
+        rank: 0, // Will be set after sorting
+      }))
+      .sort((a, b) => b.appointmentCount - a.appointmentCount)
+      .slice(0, limit)
+      .map((item, index) => ({ ...item, rank: index + 1 }));
+  }
+
+  /**
+   * Get procedure profitability metrics
+   *
+   * @param dateRange - Optional date range filter
+   * @param limit - Number of top procedures to return
+   * @returns Array of procedure profitability metrics
+   */
+  async getProcedureProfitability(
+    dateRange?: AnalyticsDateRange,
+    limit: number = 10,
+  ): Promise<ProcedureProfitability[]> {
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const procedureMap = new Map<
+      string,
+      {
+        name: string;
+        category: string;
+        subcategory: string;
+        technology: string;
+        revenue: number;
+        count: number;
+      }
+    >();
+
+    completed.forEach(appointment => {
+      const procId = appointment.procedureId;
+      const procInfo = appointment.procedureExtendedInfo || appointment.procedureInfo;
+      const cost = calculateAppointmentCost(appointment).cost;
+
+      if (procedureMap.has(procId)) {
+        const existing = procedureMap.get(procId)!;
+        existing.revenue += cost;
+        existing.count++;
+      } else {
+        procedureMap.set(procId, {
+          name: procInfo?.name || 'Unknown',
+          category: procInfo?.procedureCategoryName || '',
+          subcategory: procInfo?.procedureSubCategoryName || '',
+          technology: procInfo?.procedureTechnologyName || '',
+          revenue: cost,
+          count: 1,
+        });
+      }
+    });
+
+    return Array.from(procedureMap.entries())
+      .map(([procedureId, data]) => ({
+        procedureId,
+        procedureName: data.name,
+        categoryName: data.category,
+        subcategoryName: data.subcategory,
+        technologyName: data.technology,
+        totalRevenue: data.revenue,
+        averageRevenue: data.count > 0 ? data.revenue / data.count : 0,
+        appointmentCount: data.count,
+        rank: 0, // Will be set after sorting
+      }))
+      .sort((a, b) => b.totalRevenue - a.totalRevenue)
+      .slice(0, limit)
+      .map((item, index) => ({ ...item, rank: index + 1 }));
+  }
+
+  // ==========================================
+  // Time Efficiency Analytics
+  // ==========================================
+
+  /**
+   * Get time efficiency metrics grouped by clinic, practitioner, procedure, patient, or technology
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'procedure' | 'patient' | 'technology'
+   * @param dateRange - Optional date range filter
+   * @param filters - Optional additional filters
+   * @returns Grouped time efficiency metrics
+   */
+  async getTimeEfficiencyMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedTimeEfficiencyMetrics[]> {
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    return calculateGroupedTimeEfficiencyMetrics(appointments, groupBy);
+  }
+
+  /**
+   * Get time efficiency metrics for appointments
+   * First checks for stored analytics, then calculates if not available or stale
+   *
+   * @param filters - Optional filters
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics
+   * @returns Time efficiency metrics
+   */
+  async getTimeEfficiencyMetrics(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<TimeEfficiencyMetrics> {
+    // Try to read from stored analytics first
+    if (filters?.clinicBranchId && dateRange && options?.useCache !== false) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const stored = await readStoredTimeEfficiencyMetrics(
+        this.db,
+        filters.clinicBranchId,
+        { ...options, period },
+      );
+
+      if (stored) {
+        // Return stored data (without metadata)
+        const { metadata, ...metrics } = stored;
+        return metrics;
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(filters, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const timeMetrics = calculateAverageTimeMetrics(completed);
+    const efficiencyDistribution = calculateEfficiencyDistribution(completed);
+
+    return {
+      totalAppointments: completed.length,
+      appointmentsWithActualTime: timeMetrics.appointmentsWithActualTime,
+      averageBookedDuration: timeMetrics.averageBookedDuration,
+      averageActualDuration: timeMetrics.averageActualDuration,
+      averageEfficiency: timeMetrics.averageEfficiency,
+      totalOverrun: timeMetrics.totalOverrun,
+      totalUnderutilization: timeMetrics.totalUnderutilization,
+      averageOverrun: timeMetrics.averageOverrun,
+      averageUnderutilization: timeMetrics.averageUnderutilization,
+      efficiencyDistribution,
+    };
+  }
+
+  // ==========================================
+  // Cancellation & No-Show Analytics
+  // ==========================================
+
+  /**
+   * Get cancellation metrics
+   * First checks for stored analytics when grouping by clinic, then calculates if not available or stale
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'patient' | 'procedure' | 'technology'
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics (requires clinicBranchId for cache)
+   * @returns Cancellation metrics grouped by specified entity
+   */
+  async getCancellationMetrics(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<CancellationMetrics | CancellationMetrics[]> {
+    // Try to read from stored analytics first (only for clinic-level grouping)
+    if (groupBy === 'clinic' && dateRange && options?.useCache !== false && options?.clinicBranchId) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const stored = await readStoredCancellationMetrics(
+        this.db,
+        options.clinicBranchId,
+        'clinic',
+        { ...options, period },
+      );
+
+      if (stored) {
+        // Return stored data (without metadata)
+        const { metadata, ...metrics } = stored;
+        return metrics;
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const canceled = getCanceledAppointments(appointments);
+
+    if (groupBy === 'clinic') {
+      return this.groupCancellationsByClinic(canceled, appointments);
+    } else if (groupBy === 'practitioner') {
+      return this.groupCancellationsByPractitioner(canceled, appointments);
+    } else if (groupBy === 'patient') {
+      return this.groupCancellationsByPatient(canceled, appointments);
+    } else if (groupBy === 'technology') {
+      return this.groupCancellationsByTechnology(canceled, appointments);
+    } else {
+      return this.groupCancellationsByProcedure(canceled, appointments);
+    }
+  }
+
+  /**
+   * Group cancellations by clinic
+   */
+  private groupCancellationsByClinic(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const clinicMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const clinicId = appointment.clinicBranchId;
+      const clinicName = appointment.clinicInfo?.name || 'Unknown';
+
+      if (!clinicMap.has(clinicId)) {
+        clinicMap.set(clinicId, { name: clinicName, canceled: [], all: [] });
+      }
+      clinicMap.get(clinicId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const clinicId = appointment.clinicBranchId;
+      if (clinicMap.has(clinicId)) {
+        clinicMap.get(clinicId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(clinicMap.entries()).map(([clinicId, data]) =>
+      this.calculateCancellationMetrics(clinicId, data.name, 'clinic', data.canceled, data.all),
+    );
+  }
+
+  /**
+   * Group cancellations by practitioner
+   */
+  private groupCancellationsByPractitioner(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const practitionerMap = new Map<
+      string,
+      { name: string; canceled: Appointment[]; all: Appointment[] }
+    >();
+
+    allAppointments.forEach(appointment => {
+      const practitionerId = appointment.practitionerId;
+      const practitionerName = appointment.practitionerInfo?.name || 'Unknown';
+
+      if (!practitionerMap.has(practitionerId)) {
+        practitionerMap.set(practitionerId, { name: practitionerName, canceled: [], all: [] });
+      }
+      practitionerMap.get(practitionerId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const practitionerId = appointment.practitionerId;
+      if (practitionerMap.has(practitionerId)) {
+        practitionerMap.get(practitionerId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(practitionerMap.entries()).map(([practitionerId, data]) =>
+      this.calculateCancellationMetrics(
+        practitionerId,
+        data.name,
+        'practitioner',
+        data.canceled,
+        data.all,
+      ),
+    );
+  }
+
+  /**
+   * Group cancellations by patient
+   */
+  private groupCancellationsByPatient(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const patientMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const patientId = appointment.patientId;
+      const patientName = appointment.patientInfo?.fullName || 'Unknown';
+
+      if (!patientMap.has(patientId)) {
+        patientMap.set(patientId, { name: patientName, canceled: [], all: [] });
+      }
+      patientMap.get(patientId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const patientId = appointment.patientId;
+      if (patientMap.has(patientId)) {
+        patientMap.get(patientId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(patientMap.entries()).map(([patientId, data]) =>
+      this.calculateCancellationMetrics(patientId, data.name, 'patient', data.canceled, data.all),
+    );
+  }
+
+  /**
+   * Group cancellations by procedure
+   */
+  private groupCancellationsByProcedure(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const procedureMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const procedureId = appointment.procedureId;
+      const procedureName = appointment.procedureInfo?.name || 'Unknown';
+
+      if (!procedureMap.has(procedureId)) {
+        procedureMap.set(procedureId, { name: procedureName, canceled: [], all: [] });
+      }
+      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]) =>
+      this.calculateCancellationMetrics(
+        procedureId,
+        data.name,
+        'procedure',
+        data.canceled,
+        data.all,
+      ),
+    );
+  }
+
+  /**
+   * Group cancellations by technology
+   * Aggregates all procedures using the same technology across all doctors
+   */
+  private groupCancellationsByTechnology(
+    canceled: Appointment[],
+    allAppointments: Appointment[],
+  ): CancellationMetrics[] {
+    const technologyMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const technologyId =
+        appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology';
+      const technologyName =
+        appointment.procedureExtendedInfo?.procedureTechnologyName ||
+        appointment.procedureInfo?.technologyName ||
+        'Unknown';
+
+      if (!technologyMap.has(technologyId)) {
+        technologyMap.set(technologyId, { name: technologyName, canceled: [], all: [] });
+      }
+      technologyMap.get(technologyId)!.all.push(appointment);
+    });
+
+    canceled.forEach(appointment => {
+      const technologyId =
+        appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology';
+      if (technologyMap.has(technologyId)) {
+        technologyMap.get(technologyId)!.canceled.push(appointment);
+      }
+    });
+
+    return Array.from(technologyMap.entries()).map(([technologyId, data]) =>
+      this.calculateCancellationMetrics(
+        technologyId,
+        data.name,
+        'technology',
+        data.canceled,
+        data.all,
+      ),
+    );
+  }
+
+  /**
+   * Calculate cancellation metrics for a specific entity
+   */
+  private calculateCancellationMetrics(
+    entityId: string,
+    entityName: string,
+    entityType: EntityType,
+    canceled: Appointment[],
+    all: Appointment[],
+  ): CancellationMetrics {
+    const canceledByPatient = canceled.filter(
+      a => a.status === AppointmentStatus.CANCELED_PATIENT,
+    ).length;
+    const canceledByClinic = canceled.filter(
+      a => a.status === AppointmentStatus.CANCELED_CLINIC,
+    ).length;
+    const canceledRescheduled = canceled.filter(
+      a => a.status === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
+    ).length;
+
+    // Calculate average cancellation lead time
+    const leadTimes = canceled
+      .map(a => calculateCancellationLeadTime(a))
+      .filter((lt): lt is number => lt !== null);
+    const averageLeadTime =
+      leadTimes.length > 0 ? leadTimes.reduce((a, b) => a + b, 0) / leadTimes.length : 0;
+
+    // Group cancellation reasons
+    const reasonMap = new Map<string, number>();
+    canceled.forEach(appointment => {
+      const reason = appointment.cancellationReason || 'No reason provided';
+      reasonMap.set(reason, (reasonMap.get(reason) || 0) + 1);
+    });
+
+    const cancellationReasons = Array.from(reasonMap.entries()).map(([reason, count]) => ({
+      reason,
+      count,
+      percentage: calculatePercentage(count, canceled.length),
+    }));
+
+    return {
+      entityId,
+      entityName,
+      entityType,
+      totalAppointments: all.length,
+      canceledAppointments: canceled.length,
+      cancellationRate: calculatePercentage(canceled.length, all.length),
+      canceledByPatient,
+      canceledByClinic,
+      canceledByPractitioner: 0, // Not tracked in current status enum
+      canceledRescheduled,
+      averageCancellationLeadTime: Math.round(averageLeadTime * 100) / 100,
+      cancellationReasons,
+    };
+  }
+
+  /**
+   * Get no-show metrics
+   * First checks for stored analytics when grouping by clinic, then calculates if not available or stale
+   *
+   * @param groupBy - Group by 'clinic' | 'practitioner' | 'patient' | 'procedure' | 'technology'
+   * @param dateRange - Optional date range filter
+   * @param options - Options for reading stored analytics (requires clinicBranchId for cache)
+   * @returns No-show metrics grouped by specified entity
+   */
+  async getNoShowMetrics(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    options?: ReadStoredAnalyticsOptions,
+  ): Promise<NoShowMetrics | NoShowMetrics[]> {
+    // Try to read from stored analytics first (only for clinic-level grouping)
+    if (groupBy === 'clinic' && dateRange && options?.useCache !== false && options?.clinicBranchId) {
+      const period: AnalyticsPeriod = this.determinePeriodFromDateRange(dateRange);
+      const stored = await readStoredNoShowMetrics(
+        this.db,
+        options.clinicBranchId,
+        'clinic',
+        { ...options, period },
+      );
+
+      if (stored) {
+        // Return stored data (without metadata)
+        const { metadata, ...metrics } = stored;
+        return metrics;
+      }
+    }
+
+    // Fall back to calculation
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const noShow = getNoShowAppointments(appointments);
+
+    if (groupBy === 'clinic') {
+      return this.groupNoShowsByClinic(noShow, appointments);
+    } else if (groupBy === 'practitioner') {
+      return this.groupNoShowsByPractitioner(noShow, appointments);
+    } else if (groupBy === 'patient') {
+      return this.groupNoShowsByPatient(noShow, appointments);
+    } else if (groupBy === 'technology') {
+      return this.groupNoShowsByTechnology(noShow, appointments);
+    } else {
+      return this.groupNoShowsByProcedure(noShow, appointments);
+    }
+  }
+
+  /**
+   * Group no-shows by clinic
+   */
+  private groupNoShowsByClinic(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const clinicMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const clinicId = appointment.clinicBranchId;
+      const clinicName = appointment.clinicInfo?.name || 'Unknown';
+      if (!clinicMap.has(clinicId)) {
+        clinicMap.set(clinicId, { name: clinicName, noShow: [], all: [] });
+      }
+      clinicMap.get(clinicId)!.all.push(appointment);
+    });
+
+    noShow.forEach(appointment => {
+      const clinicId = appointment.clinicBranchId;
+      if (clinicMap.has(clinicId)) {
+        clinicMap.get(clinicId)!.noShow.push(appointment);
+      }
+    });
+
+    return Array.from(clinicMap.entries()).map(([clinicId, data]) => ({
+      entityId: clinicId,
+      entityName: data.name,
+      entityType: 'clinic' as EntityType,
+      totalAppointments: data.all.length,
+      noShowAppointments: data.noShow.length,
+      noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+    }));
+  }
+
+  /**
+   * Group no-shows by practitioner
+   */
+  private groupNoShowsByPractitioner(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const practitionerMap = new Map<
+      string,
+      { name: string; noShow: Appointment[]; all: Appointment[] }
+    >();
+
+    allAppointments.forEach(appointment => {
+      const practitionerId = appointment.practitionerId;
+      const practitionerName = appointment.practitionerInfo?.name || 'Unknown';
+
+      if (!practitionerMap.has(practitionerId)) {
+        practitionerMap.set(practitionerId, { name: practitionerName, noShow: [], all: [] });
+      }
+      practitionerMap.get(practitionerId)!.all.push(appointment);
+    });
+
+    noShow.forEach(appointment => {
+      const practitionerId = appointment.practitionerId;
+      if (practitionerMap.has(practitionerId)) {
+        practitionerMap.get(practitionerId)!.noShow.push(appointment);
+      }
+    });
+
+    return Array.from(practitionerMap.entries()).map(([practitionerId, data]) => ({
+      entityId: practitionerId,
+      entityName: data.name,
+      entityType: 'practitioner' as EntityType,
+      totalAppointments: data.all.length,
+      noShowAppointments: data.noShow.length,
+      noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+    }));
+  }
+
+  /**
+   * Group no-shows by patient
+   */
+  private groupNoShowsByPatient(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const patientMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const patientId = appointment.patientId;
+      const patientName = appointment.patientInfo?.fullName || 'Unknown';
+
+      if (!patientMap.has(patientId)) {
+        patientMap.set(patientId, { name: patientName, noShow: [], all: [] });
+      }
+      patientMap.get(patientId)!.all.push(appointment);
+    });
+
+    noShow.forEach(appointment => {
+      const patientId = appointment.patientId;
+      if (patientMap.has(patientId)) {
+        patientMap.get(patientId)!.noShow.push(appointment);
+      }
+    });
+
+    return Array.from(patientMap.entries()).map(([patientId, data]) => ({
+      entityId: patientId,
+      entityName: data.name,
+      entityType: 'patient' as EntityType,
+      totalAppointments: data.all.length,
+      noShowAppointments: data.noShow.length,
+      noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+    }));
+  }
+
+  /**
+   * Group no-shows by procedure
+   */
+  private groupNoShowsByProcedure(
+    noShow: Appointment[],
+    allAppointments: Appointment[],
+  ): NoShowMetrics[] {
+    const procedureMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[] }>();
+
+    allAppointments.forEach(appointment => {
+      const procedureId = appointment.procedureId;
+      const procedureName = appointment.procedureInfo?.name || 'Unknown';
+
+      if (!procedureMap.has(procedureId)) {
+        procedureMap.set(procedureId, { name: procedureName, noShow: [], all: [] });
+      }
+      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),
+    }));
+  }
+
+  /**
+   * 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
+   *
+   * @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
+    const revenueByStatus: Partial<Record<AppointmentStatus, number>> = {};
+    Object.values(AppointmentStatus).forEach(status => {
+      const statusAppointments = appointments.filter(a => a.status === status);
+      const { totalRevenue: statusRevenue } = calculateTotalRevenue(statusAppointments);
+      revenueByStatus[status] = statusRevenue;
+    });
+
+    // 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
+   *
+   * @param productId - Optional product ID (if not provided, returns all products)
+   * @param dateRange - Optional date range filter
+   * @returns Product usage metrics
+   */
+  async getProductUsageMetrics(
+    productId?: string,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<ProductUsageMetrics | ProductUsageMetrics[]> {
+    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const completed = getCompletedAppointments(appointments);
+
+    const productMap = new Map<
+      string,
+      {
+        name: string;
+        brandId: string;
+        brandName: string;
+        quantity: number;
+        revenue: number;
+        usageCount: number;
+        procedureMap: Map<string, { name: string; count: number; quantity: number }>;
+      }
+    >();
+
+    completed.forEach(appointment => {
+      const products = extractProductUsage(appointment);
+      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,
+            procedureMap: new Map(),
+          });
+        }
+
+        const productData = productMap.get(product.productId)!;
+        productData.quantity += product.quantity;
+        productData.revenue += product.subtotal;
+        productData.usageCount++;
+
+        // Track usage by procedure
+        const procId = appointment.procedureId;
+        const procName = appointment.procedureInfo?.name || 'Unknown';
+        if (productData.procedureMap.has(procId)) {
+          const procData = productData.procedureMap.get(procId)!;
+          procData.count++;
+          procData.quantity += product.quantity;
+        } else {
+          productData.procedureMap.set(procId, {
+            name: procName,
+            count: 1,
+            quantity: product.quantity,
+          });
+        }
+      });
+    });
+
+    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,
+    };
+  }
+}
+