Timesheet Upload Feature

Overview

The timesheet upload feature allows clinicians and administrators to upload handwritten or digital timesheets for AI processing and validation. This feature integrates with the billing system to automatically extract visit data and create billing records using OpenAI's Vision API.

Features

1. File Upload

• Supported Formats: PDF, JPEG, PNG, TIFF
• File Size Limit: 10MB
• Upload Sources:
  • Admin: Always "manual" (hidden from UI)
  • Public Link: Always "clinician_link" (automatic)

2. AI Processing with OpenAI

• OpenAI Vision API: Uses GPT-4o for intelligent text extraction
• Automatic Processing: Files are automatically processed for data extraction
• Confidence Scoring: Each extraction includes a confidence score (0-100%)
• Status Tracking: pending → processing → completed/failed

3. Data Extraction

• Extracted Fields: Date, start time, end time, total hours, patient name, clinician name, visit type, notes
• Metadata Storage: Original file, AI confidence, extraction details
• JSON Storage: All extracted data stored in structured format

4. Validation Workflow

• Manual Review: Human validation of AI results
• Status Management: pending → validated/rejected
• Audit Trail: Track who validated what and when

How to Use

Uploading a Timesheet

Option 1: Admin Dashboard (Authenticated Users)

1. Navigate to Billing Dashboard

   • Go to /admin/billing
   • Click the "Upload Timesheet" button in the top navigation

2. Select File

   • Click "Select File" and choose your timesheet
   • Supported formats: PDF, JPEG, PNG, TIFF
   • Maximum size: 10MB
   • Upload source automatically set to "manual"

3. Upload

   • Click "Upload Timesheet"
   • Watch the progress bar
   • File will be uploaded to private Supabase Storage

4. Copy Clinician Link

   • Use the "Copy Clinician Link" button to get a shareable link for clinicians
   • Link automatically sets upload source to "clinician_link"

Option 2: Public Clinician Link (Unauthenticated Users)

1. Use Direct Link

   • Navigate to /timesheet-upload/[organizationId]/[clinicianId]
   • No login required
   • Organization and clinician IDs are embedded in the URL

2. Upload Process

   • Same file validation and upload process
   • Automatically tagged with clinician_link source
   • Secure organization-based storage

Monitoring AI Processing Status

1. Check Timesheet Tab

   • Switch to the "Timesheets" tab in the dashboard
   • View all uploaded timesheets with their current status

2. Status Indicators

   • Pending: File uploaded, waiting for AI processing
   • Processing: AI analysis in progress
   • Completed: AI processing finished successfully
   • Failed: AI processing failed, retry available

3. Confidence Scores

   • Green (80%+): High confidence, likely accurate
   • Yellow (60-79%): Medium confidence, review recommended
   • Red (<60%): Low confidence, manual review required

Validating Results

1. Review Extracted Data

   • Click on completed timesheets to view extracted information
   • Verify date, times, and hours are correct

2. Approve or Reject

   • Approve: Mark as validated, data becomes available for billing
   • Reject: Mark as rejected, requires correction and re-upload

3. Retry Failed Processing

   • For failed AI processing, click "Retry OCR" to process again
   • Useful for poor quality scans or AI processing errors

Security & Permissions

Row Level Security (RLS)

• Users can only access timesheets from their organization
• File uploads restricted to organization-specific storage folders
• Validation actions logged with user and timestamp

File Access Control

• Private Storage: Files not publicly accessible
• Signed URLs: Temporary access for authenticated users
• Organization Isolation: Files stored by organization ID
• Public Upload: Clinician link allows unauthenticated uploads to specific orgs

Integration with Billing

Data Flow

1. Upload → File stored in private Supabase Storage
2. AI Processing → OpenAI Vision API extracts data
3. Validation → Human review and approval
4. Billing → Data available for visit creation and billing

Billing Status Impact

• Validated timesheets contribute to billing calculations
• AI confidence scores affect billing status determination
• Extracted data used to create visit records automatically

Troubleshooting

Common Issues

1. Upload Fails

   • Check file size (must be < 10MB)
   • Verify file format (PDF, JPEG, PNG, TIFF)
   • Ensure valid organization ID format

2. AI Processing Fails

   • Check image quality (clear, well-lit, good contrast)
   • Verify text is readable and not handwritten in cursive
   • Check OpenAI API key configuration

3. Low Confidence Scores

   • Review original file quality
   • Check for smudges, shadows, or poor lighting
   • Consider manual data entry for critical records

Best Practices

1. File Quality

   • Use high-resolution scans (300 DPI minimum)
   • Ensure good lighting and contrast
   • Avoid shadows, creases, or damage

2. Content Clarity

   • Use clear, printed text when possible
   • Avoid cursive handwriting
   • Ensure all required fields are visible

3. Regular Monitoring

   • Check AI processing status regularly
   • Validate results promptly
   • Address failed processing quickly