Medical Records Processing System

A comprehensive medical records collection system with AI phone agent integration, real-time webhooks, voice configuration, and automated follow-ups.

Features

Core Medical Records Features

• Patient Management: Complete patient demographics and medical history tracking
• Medical Encounters: Timeline view with provider information and document attachments
• Document Processing: Automatic summarization with cost/time savings tracking
• Advanced Filtering: Filter by medical sections, dates, and providers
• ICD/CPT Code Integration: Automatic code mapping and contextual display

AI Phone Agent Integration

• Real-time Webhooks: Process call events (start, transcript, end) in real-time
• Voice Configuration: Support for multiple TTS providers (ElevenLabs, PlayHT, Azure, AWS Polly, Google TTS)
• Call Recording & Playback: Automatic recording storage with synchronized transcript display
• Live Call Monitoring: Real-time status updates and transcript streaming

Records Collection Queue

• Provider Outreach: Track and manage medical record requests
• AI Agent Assignment: Automatic assignment of AI agents to make calls
• Communication Logging: Track all emails, calls, and follow-ups
• Document Upload: Secure document storage in Supabase

Automated Follow-ups

• Rule-Based Engine: Configurable follow-up rules based on request age and status
• Multi-Channel Support: Email, SMS, AI calls, and internal notifications
• Smart Scheduling: Respect cooldown periods and business hours
• Template System: Customizable message templates

Analytics & Reporting

• Request Metrics: Track pending, completed, and failed requests
• AI Performance: Monitor call duration, success rates, and sentiment
• Weekly Trends: Visual charts for request volume and completion rates
• Provider Statistics: Track response rates by provider

Tech Stack

• Frontend: Next.js 14, React 18, Redux Toolkit, TypeScript
• Backend: Supabase (PostgreSQL, Auth, Storage, Real-time)
• UI: Tailwind CSS, Radix UI components
• Voice: Multiple TTS provider integrations
• Testing: Jest, React Testing Library
• Type Safety: Strict TypeScript with generated database types

Prerequisites

• Node.js 18+
• npm or yarn
• Supabase CLI
• PostgreSQL (via Supabase local development)

Installation

1. Clone the repository:

git clone https://github.com/your-org/medical-records-processing.git
cd medical-records-processing

2. Install dependencies:

npm install

3. Set up environment variables:

cp .env.example .env.local

Edit .env.local:

NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key
WEBHOOK_SECRET=your-webhook-secret
CRON_SECRET=your-cron-secret

4. Start Supabase:

npm run supabase:start

5. Apply migrations and seed data:

npm run supabase:reset

6. Start the development server:

npm run dev

Visit http://localhost:3000

Project Structure

src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── webhooks/      # Webhook endpoints
│   │   └── cron/          # Cron job endpoints
│   └── (pages)            # App pages
├── modules/               # Feature modules
│   ├── auth/             # Authentication
│   ├── patients/         # Patient management
│   ├── encounters/       # Medical encounters
│   ├── records/          # Records collection
│   │   ├── components/   # UI components
│   │   ├── services/     # Business logic
│   │   └── types.ts      # TypeScript types
│   └── shared/           # Shared resources
├── store/                # Redux store
├── lib/                  # Utilities
└── styles/               # Global styles

supabase/
├── migrations/           # Database migrations (sequential: 001_, 002_, etc.)
├── functions/           # Edge functions
└── seed/                # Seed data

Key Features in Detail

Webhook Processing

The system processes real-time webhook events from AI phone agents:

• call.started - Initialize live call tracking
• call.answered - Update call status
• call.ended - Process recording and generate summary
• transcript.partial - Live transcription updates
• transcript.final - Final transcript segments
• recording.ready - Handle recording availability

Voice Configuration

Configure AI voice settings per organization:

• Multiple voice providers with specific settings
• Real-time voice preview and testing
• Provider-specific parameters (stability, similarity boost, etc.)
• Language and accent selection

Call Recording Management

• Automatic download and secure storage of recordings
• Synchronized playback with transcript highlighting
• Key event timeline with clickable navigation
• Sentiment analysis and call quality metrics

Automated Follow-up System

Rule-based follow-up engine with:

• 3-Day Reminder: Email follow-up for pending requests
• 5-Day Escalation: AI call for no-response situations
• Priority Handling: Urgent requests get faster follow-ups
• Smart Cooldowns: Prevent follow-up fatigue

API Documentation

Webhook Endpoint

POST /api/webhooks/call
Content-Type: application/json
X-Webhook-Signature: HMAC-SHA256 signature

{
  "requestId": "req-123",
  "callId": "call-123",
  "event": "call.started",
  "timestamp": "2024-03-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Cron Endpoint

GET/POST /api/cron/follow-ups
Authorization: Bearer {CRON_SECRET}

Testing

Run unit tests:

npm test

Run tests with coverage:

npm run test:coverage

Run integration tests:

npm run test:integration

See Testing Guide for detailed testing instructions.

Database Schema

Key tables:

• patients - Patient demographics and information
• encounters - Medical visits and encounters
• record_requests - Record collection requests
• live_calls - Real-time call tracking
• call_recordings - Stored call recordings
• voice_settings - Voice configuration per organization
• webhook_logs - Webhook event history
• request_communications - All communications (emails, calls, etc.)

Deployment

Vercel Deployment

1. Install Vercel CLI:

npm i -g vercel

2. Deploy:

vercel

3. Set environment variables in Vercel dashboard

Supabase Production

1. Create a Supabase project at supabase.com
2. Run migrations:

supabase db push

3. Deploy Edge Functions:

supabase functions deploy

Cron Job Setup

See Cron Setup Guide for configuring automated follow-ups with:

• Vercel Cron
• GitHub Actions
• External cron services (Cron-job.org, EasyCron)
• Railway/Render scheduled jobs

Security

• HMAC signature verification for webhooks
• Row Level Security (RLS) in Supabase
• Secure file storage with access controls
• API authentication with Bearer tokens
• Environment-based configuration

Performance Optimizations

• Real-time updates via WebSocket subscriptions
• Efficient database indexing for vector search
• Lazy loading of call recordings
• Pagination for large datasets
• Optimistic UI updates

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• GitHub Issues: Create an issue
• Documentation: See /docs folder for detailed guides