🩺 MedVoice AI

The AI front desk that never sleeps — for medical practices.

MedVoice AI answers your clinic's phone, talks naturally with patients, understands what they need, and routes every call correctly — appointments, refills, urgent triage, or a human transfer. Every call is recorded, transcribed, and surfaced in a clean dashboard for your staff.

HIPAA · E911 · TCPA aware — compliance enforced at the infrastructure level.

---

✨ Why MedVoice AI

Think of it as a 24/7 front-desk helper for medical offices. When a patient calls:

• 📞 Answers automatically — no missed calls, no hold music limbo
• 🗣️ Talks in natural voice — real-time speech, not a rigid IVR menu
• 🧠 Understands intent — appointment, refill, billing, urgent issue, or a question
• 🔀 Routes correctly — AI response, human transfer, or voicemail
• 🚨 Triages urgency — critical calls jump straight to a human with a 911 disclaimer
• 📊 Logs everything — recordings, transcripts, and analytics in one dashboard

Built for: clinics · family medicine · specialty practices · small-to-medium healthcare teams.

---

🖥️ Product Tour

Dashboard — today's call activity at a glance

Live counters for inbound calls, active calls, average handle time, and resolution rate, plus a 30-day urgency breakdown (Critical / Urgent / Routine).

Call Log — searchable history with audio + transcripts

Filter by date range, disposition, and urgency. Export to CSV. Play S3-hosted recordings and read the full transcript for any call.

Phone Tree Builder — design the call flow visually

A drag-and-drop node editor (React Flow). Compose Greeting, Menu, AI Agent, Triage, Transfer, Voicemail, and After-Hours nodes, then configure each one in the side panel and save a new version.

Analytics — performance metrics and trends

Resolution rate, average handle time, call volume by hour, and intent distribution across a selectable 7 / 14 / 30-day window.

---

🛠️ Tech Stack

Layer	Technology	Role
Frontend	Next.js 14 (App Router) · React Flow · Recharts	Dashboard, visual phone-tree builder, analytics charts
Backend	FastAPI (async) · Uvicorn	REST API + Twilio webhooks + media-stream WebSocket
Database	PostgreSQL 15 · SQLAlchemy · Alembic	Multi-tenant data, async via asyncpg
Telephony	Twilio Programmable Voice	Inbound calls, bidirectional media streaming
Speech-to-Text	Deepgram Nova-2	Real-time streaming transcription (mulaw 8kHz)
Text-to-Speech	ElevenLabs Turbo v2.5	Streaming voice synthesis
AI Reasoning	OpenAI GPT-4o / GPT-4o-mini	Intent classification + response generation
Cache / Queue	Redis 7	Phone-tree cache + Celery broker
Background Jobs	Celery 5	Post-call transcription, alerts, DB writes
Storage	AWS S3 (SSE-KMS)	Encrypted recordings + presigned playback URLs
Auth	Clerk	JWT auth + multi-tenant org management
Monitoring	Sentry · Nginx	Error tracking + TLS / WebSocket reverse proxy

---

🔄 How a Call Flows

  Patient dials   ┌──────────┐   ┌─────────────┐   ┌──────────────┐   ┌────────────┐
   the clinic ──► │  Twilio  │──►│  Deepgram   │──►│   GPT-4o     │──►│ ElevenLabs │──► Patient
    number        │  Voice   │   │  (STT)      │   │  intent +    │   │   (TTS)    │     hears
                  └──────────┘   └─────────────┘   │  response    │   └────────────┘    a reply
                       │                           └──────────────┘
                       │                                  │
                       ▼                                  ▼
                 Phone Tree Engine                  Triage scoring
              (state machine, Redis)            (≥8 → instant transfer)
                       │
                       ▼
            Disposition: AI answer · transfer · voicemail · appointment
                       │
                       ▼
            Celery: upload recording, finalize transcript, notify staff
                       │
                       ▼
                  Dashboard 📊

1. Patient calls your practice number → Twilio answers.
2. MedVoice greets the caller and streams audio both ways.
3. Deepgram transcribes; GPT-4o detects intent and generates a reply.
4. The Phone Tree Engine advances state; triage can override and transfer immediately.
5. The call ends with the right disposition; staff sees it all in the dashboard.

See archetecture.md for the full end-to-end architecture, data models, and node schema.

---

🚀 Quick Start

1) Clone & configure environment

git clone https://github.com/malakazlan/DOC_CALL.git
cd DOC_CALL
cp .env.example .env   # fill in your real keys and URLs

2) Create database tables

In the Supabase SQL Editor, run backend/supabase_schema.sql.

3) Run the backend (FastAPI)

cd backend
python -m venv .venv

Activate the virtual environment:

OS	Command
Windows PowerShell	.\.venv\Scripts\Activate.ps1
Windows CMD	.venv\Scripts\activate.bat
macOS / Linux	source .venv/bin/activate

Then install and run:

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

4) Run the frontend (Next.js)

Create frontend/.env.local with your Clerk keys and the API URL, then:

cd frontend
npm install
npm run dev

Open http://localhost:3000 🎉

🐳 Prefer Docker? docker compose up brings up the full stack.

---

📁 Project Structure

medvoice-ai/
├── backend/                  # FastAPI API
│   ├── app/
│   │   ├── core/             # Phone-tree engine, intent, triage
│   │   ├── models/           # SQLAlchemy ORM
│   │   ├── routers/          # Twilio, practices, phone-trees, calls
│   │   ├── services/         # STT, TTS, LLM, voice agent, recording
│   │   └── workers/          # Celery tasks
│   ├── supabase_schema.sql   # Run in Supabase to create tables
│   └── requirements.txt
│
├── frontend/                 # Next.js 14
│   ├── app/dashboard/        # Dashboard, calls, phone-tree, analytics
│   ├── components/
│   └── lib/
│
├── docs/                     # Product screenshots
├── docker-compose.yml
└── archetecture.md           # Full system architecture

Full breakdown in STRUCTURE.md.

---

🔐 Compliance Notes

• HIPAA — PHI encrypted at rest (S3 SSE-KMS, encrypted DB volume) and in transit (TLS 1.2+). Caller numbers stored hashed; audit trail on all data access.
• E911 — emergency disclaimer played on every call; immediate 911 instruction for the highest urgency scores.
• TCPA — inbound-only by design; recording-consent prompt on every call, with 2-party-state disclosures auto-selected.

---

⚠️ Twilio Trial Accounts

If your Twilio account is on a trial plan, incoming calls are limited by Twilio's rules. To accept calls from any number worldwide, upgrade Twilio to a paid account.

---

📦 Repository

🔗 github.com/malakazlan/DOC_CALL

_{MedVoice AI — AI phone automation for U.S. medical practices.}