Commission Tracking System

Last Updated: March 2024
Status: Production Ready with Real-time Updates

A comprehensive commission management system for healthcare platforms, providing automated calculation, tracking, and reporting of commission earnings for healthcare professionals with real-time updates powered by WebSocket integration.

OverviewCopy Anchor Link

The Commission Tracking System enables healthcare organizations to:

• Define flexible commission rules for different user types and services
• Automate commission calculations with validation and preview
• Track commission earnings and payment status
• Provide self-service access for consultants to view their earnings
• Generate detailed reports and analytics

ArchitectureCopy Anchor Link

Key ComponentsCopy Anchor Link

1. Commission Rules Management

   • Rule creation and configuration
   • Support for percentage, tiered, and performance-based rules
   • User and service-specific rule assignment
   • Priority-based rule resolution

2. Calculation Engine

   • Batch calculation processing
   • Real-time preview and validation
   • Job queue management
   • Progress tracking and monitoring

3. Payment Workflow

   • Commission approval process
   • Payment tracking and history
   • Dispute management
   • Automated notifications

4. Reporting & Analytics

   • Real-time dashboards
   • User-specific earnings views
   • Export functionality (CSV, PDF, Excel)
   • Trend analysis and metrics

5. Analytics & Comparisons

   • Period-over-period analysis
   • Interactive data visualizations
   • Performance benchmarking
   • Location-based insights

Data FlowCopy Anchor Link

Commission Rules → Calculation Jobs → Validation → Calculations → Approval → Payment
                        ↓                ↓
                   Job Queue        Preview/Dry Run
                        ↓
                   Monitoring & Notifications

Feature ImplementationCopy Anchor Link

Commission Rules (/reports/commission-rules)Copy Anchor Link

Commission rules define how commissions are calculated for different scenarios.

Rule TypesCopy Anchor Link

1. Percentage-Based

   Copy Text

   {
     ruleType: 'percentage',
     basePercentage: 15,
     minimumRevenue: 500,
     maximumCommission: 2000
   }

2. Tiered Commission

   Copy Text

   {
     ruleType: 'tiered',
     tiers: [
       { minimumAmount: 0, maximumAmount: 5000, percentage: 12 },
       { minimumAmount: 5000, maximumAmount: 15000, percentage: 18, fixedBonus: 200 },
       { minimumAmount: 15000, percentage: 25, fixedBonus: 500 }
     ]
   }

3. Performance-Based

   Copy Text

   {
     ruleType: 'performance',
     basePercentage: 20,
     performanceMetrics: [
       { metric: 'patient_satisfaction', operator: 'greater_than', targetValue: 4.5, bonusPercentage: 5 },
       { metric: 'new_patients', operator: 'greater_than', targetValue: 20, bonusAmount: 300 }
     ]
   }

Rule Management UICopy Anchor Link

• Table view with filtering and search
• Create/Edit modal with validation
• Active/Inactive toggle
• Rule priority management
• Bulk operations support

Commission Dashboard (/reports/commission-dashboard)Copy Anchor Link

Provides comprehensive overview of commission metrics and trends.

Key MetricsCopy Anchor Link

• Total Commission (current period)
• Pending Commissions
• Approved Commissions
• Paid Commissions
• Period-over-period comparison

FeaturesCopy Anchor Link

• Interactive charts with trend visualization
• Drill-down capabilities
• Filter by date range, user, location
• Export functionality
• Role-based data access (consultants see only their data)

Commission Calculations (/reports/commission-calculations)Copy Anchor Link

Tracks individual commission calculations with detailed breakdowns.

Calculation StatesCopy Anchor Link

• pending - Awaiting approval
• approved - Approved for payment
• paid - Payment completed
• disputed - Under review
• cancelled - Cancelled/voided

FeaturesCopy Anchor Link

• Detailed calculation breakdown
• Approval workflow
• Batch operations
• Export functionality
• Dispute management

Commission Workflows (/reports/commission-workflows)Copy Anchor Link

Manages calculation jobs and automated processing.

Job TypesCopy Anchor Link

• bulk_calculation - Process multiple users/periods
• preview_calculation - Dry run for validation
• scheduled_calculation - Automated recurring calculations

Workflow FeaturesCopy Anchor Link

1. Job Creation

   • Date range selection
   • Rule and user filtering
   • Validation level configuration
   • Preview mode support

2. Validation & Preview

   • Data integrity checks
   • Rule consistency validation
   • User eligibility verification
   • Impact analysis
   • Side-by-side comparison

3. Job Monitoring

   • Real-time progress tracking
   • Status updates
   • Error handling
   • Retry capabilities
   • Batch operations

4. Notifications

   • Job completion alerts
   • Error notifications
   • Status change updates
   • Action-based navigation

Commission Analytics (/reports/commission-analytics)Copy Anchor Link

Provides comprehensive analytics and comparison views for commission performance.

Analytics FeaturesCopy Anchor Link

1. Comparison Controls

   • Period-over-period comparison
   • Year-over-year analysis
   • Location-based comparisons
   • Custom date range selection

2. Key Performance Metrics

   • Total commission with trend indicators
   • Revenue growth tracking
   • Active user counts
   • Average commission per user
   • Period-to-period percentage changes

3. Interactive Visualizations

   Bar Charts - Side-by-side comparison

   Copy Text

   <CommissionComparisonChart
     title="Month-over-Month Commission Comparison"
     data={[
       { label: "Jan 2024", previous: 102000, current: 108000 },
       { label: "Feb 2024", previous: 108000, current: 112340 }
     ]}
   />

   Pie Charts - Distribution analysis

   Copy Text

   <CommissionPieChart
     title="Commission Distribution by Location"
     data={[
       { label: "Main Hospital", value: 65000 },
       { label: "North Clinic", value: 35750 }
     ]}
   />

   Line Charts - Trend visualization

   Copy Text

   <CommissionLineChart
     title="Commission Growth Trend"
     data={trendData}
     animate={true}
   />

   Performance Gauges - Visual KPI indicators

   • Arc-based gauges showing relative performance
   • Color-coded growth indicators (green/blue/red)
   • Percentage of top performer metric

4. Analytics Tabs

   User Performance

   • Top performers ranking with growth metrics
   • Performance gauge visualization
   • Average growth calculation
   • Positive/negative growth tracking
   • Interactive hover effects

   Trends Analysis

   • 6-month commission progression
   • Animated line charts
   • Year-over-year growth comparison
   • Visual trend indicators

   Location Analysis

   • Commission distribution pie chart
   • Location-wise performance metrics
   • Growth comparison by location
   • User count per location

5. Analytics Summary Cards

   • Best performing location
   • Highest growth location
   • Average commission per user
   • Real-time metric updates

Edge Case HandlingCopy Anchor Link

The commission tracking system includes comprehensive edge case handling to ensure robust operation:

Empty State ManagementCopy Anchor Link

• Approval Modal: Displays helpful message when no pending calculations are available
• Payout Modal: Shows clear messaging when no approved calculations exist for payout
• Payout History: Provides contextual empty states based on filter status
• Calculations Page: Differentiates between "no data" and "no matching filters"

Validation & PreventionCopy Anchor Link

1. Status Validation

   • Prevents approving already approved or paid calculations
   • Blocks payment attempts on non-approved calculations
   • Shows specific error messages for mixed status selections

2. Payment Validation

   • Validates payment dates (no past dates allowed)
   • Checks payment method availability before processing
   • Auto-generates transaction references if not provided
   • Warns about zero-amount calculations

3. Batch Operations

   • Large batch warning for 50+ selections
   • "Select All" only affects visible/filtered items
   • Prevents accidental bulk operations

State ManagementCopy Anchor Link

• Form data persists through errors (no data loss on failure)
• Modal state resets only on successful operations
• Error messages clear when retrying operations
• Selected items maintain state during operations

Network Error RecoveryCopy Anchor Link

• Retry buttons on all error states
• Preserves user selections during retry
• Shows specific error messages from API
• Implements exponential backoff for retries

Code ExamplesCopy Anchor Link

Empty State HandlingCopy Anchor Link

{calculations.length === 0 ? (
  <div className="text-center py-12">
    <Calculator className="mx-auto h-12 w-12 text-muted-foreground mb-4" />
    <h3 className="text-lg font-semibold mb-2">No Calculations Available</h3>
    <p className="text-muted-foreground">
      There are no pending calculations to approve at this time.
    </p>
  </div>
) : (
  // Normal content
)}

Validation ExampleCopy Anchor Link

const handlePayoutClick = () => {
  const approvedCalculations = commissionCalculations.filter(
    calc => selectedCalculations.includes(calc.id) && calc.status === 'approved'
  )
  
  if (approvedCalculations.length === 0) {
    const selectedCalcs = commissionCalculations.filter(calc => selectedCalculations.includes(calc.id))
    if (selectedCalcs.some(calc => calc.status === 'paid')) {
      toast.error("Some selected calculations are already paid")
    } else if (selectedCalcs.some(calc => calc.status === 'pending_approval')) {
      toast.error("Some selected calculations are still pending approval")
    }
    return
  }
  
  setShowPayoutModal(true)
}

Error RecoveryCopy Anchor Link

{error && (
  <Alert variant="destructive">
    <AlertTriangle className="h-4 w-4" />
    <AlertDescription>
      <div className="flex items-center justify-between">
        <span>{error}</span>
        <Button variant="outline" size="sm" onClick={retry}>
          <RefreshCw className="mr-2 h-4 w-4" />
          Retry
        </Button>
      </div>
    </AlertDescription>
  </Alert>
)}

## Error Handling & Recovery

### Error Boundary Protection

All commission pages are wrapped with error boundaries to prevent crashes:

```typescript
<CommissionErrorBoundary>
  <CommissionWorkflowsPageContent />
</CommissionErrorBoundary>

Features:

• Graceful error display
• Error details in development
• Recovery options (retry/reload)
• Automatic error logging
• Notification integration

Retry LogicCopy Anchor Link

Critical operations implement exponential backoff retry:

retryOperation(operation, {
  maxAttempts: 5,
  delay: 2000,
  backoff: 'exponential',
  maxDelay: 60000
})

Retry configurations:

• critical - Commission calculations (5 attempts)
• standard - Regular API calls (3 attempts)
• fast - Quick operations (2 attempts)
• polling - Status checks (10 attempts)

Real-time NotificationsCopy Anchor Link

Comprehensive notification system for commission events:

const { notifyCommissionJobComplete, notifyCommissionError } = useNotificationStore()

Notification types:

• Job completion (success/failure)
• Validation warnings
• Approval status changes
• Payment confirmations
• System errors

Features:

• Toast notifications
• Persistent notification center
• Action buttons for navigation
• Category-based filtering
• Read/unread status

Access ControlCopy Anchor Link

Role-Based AccessCopy Anchor Link

1. Admin/Manager

   • Full access to all features
   • Create/edit commission rules
   • Approve calculations
   • Process payments
   • View all user data

2. Consultant Doctors

   • View own commission data only
   • Access dashboard with personal metrics
   • View calculation details
   • Export own reports
   • No rule management access

Permission ChecksCopy Anchor Link

// Allow consultant doctors to view their data
if (user?.role === "doctor") {
  filters.userIds = [user.id]
}

// UI restrictions
{canManageUsers && (
  <Button>Create Rule</Button>
)}

Reusable Chart ComponentsCopy Anchor Link

The commission analytics system includes reusable chart components for data visualization:

CommissionComparisonChartCopy Anchor Link

Bar chart for period-over-period comparisons with:

• Side-by-side bars for current vs previous periods
• Percentage change indicators
• Interactive hover effects
• Customizable value formatting

CommissionPieChartCopy Anchor Link

Pie chart for distribution analysis with:

• Automatic percentage calculation
• Interactive slices with hover effects
• Legend with values and percentages
• Customizable colors
• Labels for slices >5%

CommissionLineChartCopy Anchor Link

Line chart for trend visualization with:

• Animated draw effect on load
• Auto-scaling Y-axis
• Grid lines for readability
• Hover tooltips on data points
• Smooth path rendering

Usage ExampleCopy Anchor Link

import { 
  CommissionComparisonChart, 
  CommissionPieChart, 
  CommissionLineChart 
} from "@/components/reports/CommissionComparisonChart"

// Comparison chart
<CommissionComparisonChart
  title="Monthly Comparison"
  data={monthlyData}
  formatValue={(v) => `$${v.toLocaleString()}`}
/>

// Distribution chart
<CommissionPieChart
  title="Location Distribution"
  data={locationData}
  showLegend={true}
/>

// Trend chart
<CommissionLineChart
  title="6-Month Trend"
  data={trendData}
  animate={true}
/>

API IntegrationCopy Anchor Link

Commission API ServiceCopy Anchor Link

Located in packages/api-client/src/services/commissionsApi.ts

Key endpoints:

• /api/commissions/rules - Rule management
• /api/commissions/calculations - Calculation records
• /api/commissions/summaries - Summary reports
• /api/commissions/jobs - Workflow jobs
• /api/commissions/validate - Validation endpoint
• /api/commissions/preview - Preview calculations

State ManagementCopy Anchor Link

Zustand store: packages/auth/src/stores/commissionsStore.ts

Store sections:

• Commission rules state
• Calculations state
• Summaries state
• Job management state
• Preview/validation state
• Pagination handling

Usage ExamplesCopy Anchor Link

Creating a Commission RuleCopy Anchor Link

const { createCommissionRule } = useCommissionsStore()

await createCommissionRule({
  name: "Standard Doctor Commission",
  ruleType: "percentage",
  basePercentage: 15,
  userId: "doctor_123",
  applicableServices: ["consultation"],
  effectiveFrom: new Date()
})

Running a Calculation JobCopy Anchor Link

const { createCalculationJob } = useCommissionsStore()

await createCalculationJob({
  type: "bulk_calculation",
  title: "Monthly Commission - March 2024",
  period: "monthly",
  startDate: "2024-03-01",
  endDate: "2024-03-31",
  requireApproval: true,
  notifyOnCompletion: true
})

Handling Job Status UpdatesCopy Anchor Link

// Auto-refresh with status change detection
useEffect(() => {
  const interval = setInterval(async () => {
    await fetchCalculationJobs()
    
    // Check for status changes
    calculationJobs.forEach(job => {
      if (prevStatus !== job.status && job.status === 'completed') {
        notifyCommissionJobComplete(job.id, job.title, true)
      }
    })
  }, 5000)
}, [calculationJobs])

Viewing AnalyticsCopy Anchor Link

// Analytics comparison example
const { commissionSummaries, fetchCommissionSummaries } = useCommissionsStore()

// Compare periods
const compareData = {
  currentPeriod: "2024-03",
  previousPeriod: "2024-02",
  comparisonType: "period"
}

// Calculate growth metrics
const calculateGrowth = (current: number, previous: number) => {
  return ((current - previous) / previous) * 100
}

TestingCopy Anchor Link

Mock DataCopy Anchor Link

Development mode includes comprehensive mock data:

• Sample commission rules
• Calculation jobs with various states
• Preview results
• Validation scenarios

Test ScenariosCopy Anchor Link

1. Rule Creation

   • Valid rule configuration
   • Validation errors
   • Duplicate detection

2. Calculation Workflow

   • Successful calculation
   • Validation failures
   • Job cancellation
   • Retry logic

3. Access Control

   • Admin full access
   • Consultant restricted view
   • Permission boundaries

Real-Time UpdatesCopy Anchor Link

The commission tracking system now includes real-time updates powered by a provider-agnostic WebSocket implementation using Ably for HIPAA-compliant messaging.

FeaturesCopy Anchor Link

1. Live Job Progress

   • Real-time progress indicators for running calculations
   • Instant status changes without polling
   • Progress percentage and item count updates

2. Instant Notifications

   • Job completion alerts
   • Error notifications
   • Approval status changes
   • Payment confirmations

3. Connection Status

   • Visual indicators showing real-time connection status
   • Automatic reconnection handling
   • Graceful degradation when offline

ImplementationCopy Anchor Link

// Enable real-time updates in your component
import { useRealtimeCommissions } from '@kulcare/auth'

const { isConnected } = useRealtimeCommissions({
  enabled: true,
  showNotifications: true
})

// Track specific job progress
import { useCommissionJobProgress } from '@kulcare/auth'

const { progress, percentage, status } = useCommissionJobProgress(jobId)

ConfigurationCopy Anchor Link

Add Ably credentials to your environment:

VITE_ABLY_KEY=your-ably-key
VITE_ABLY_ENVIRONMENT=us  # Optional: 'us' or 'eu' for data residency

Future EnhancementsCopy Anchor Link

1. WebSocket Migration Options

   • Custom WebSocket server implementation
   • Alternative providers (Socket.io, AWS IoT)
   • Self-hosted solution for data sovereignty

2. Advanced Analytics Enhancements

   • Predictive commission forecasting using ML
   • Performance correlation analysis
   • Automated rule optimization
   • Real-time analytics with streaming data
   • Custom report builder
   • Advanced filtering and segmentation

3. Integration Features

   • Accounting system sync
   • Payment gateway integration
   • Automated tax calculations

Related DocumentationCopy Anchor Link

• Premium Reporting System
• User Management
• Access Control
• Feature Flags
• Real-Time Integration Guide
• WebSocket Integration Design