A production-ready AI-powered telephony platform for healthcare clinics that automates patient communication through intelligent voice conversations. Built with FastAPI, ElevenLabs Conversational AI, and Twilio, this platform handles appointment scheduling, patient inquiries, and administrative tasks while maintaining HIPAA-compliant standards.

• AI-Powered Voice Conversations: Natural language processing for handling inbound and outbound calls
• Appointment Management: Schedule, reschedule, cancel, and confirm appointments with real-time availability
• Multi-Clinic Support: Isolated tenant architecture supporting multiple clinics with custom configurations
• Knowledge Base Integration: Clinic-specific Q&A knowledge base with automatic context injection
• Call Analytics: Comprehensive call metrics, sentiment analysis, and performance tracking

• EHR Systems: AthenaHealth and Epic FHIR integration for patient data and appointment sync
• Calendly: Bidirectional calendar synchronization
• Telephony: Twilio integration for phone number management and call routing
• Conversational AI: ElevenLabs agents with customizable voice and personality

• Outbound Call Automation: Appointment reminders, confirmations, and follow-ups
• Patient Record Management: Secure patient data handling with verification protocols
• Staff Management: Role-based access control (Admin, Doctor, Receptionist, Nurse, Manager)
• Insurance Verification: Real-time eligibility checks and coverage validation
• Call Transcripts: Automatic conversation transcription and summarization

• Python 3.10 or higher
• PostgreSQL 14 or higher
• Twilio account with API credentials
• ElevenLabs account with API key
• (Optional) AthenaHealth API credentials
• (Optional) Epic FHIR API credentials

git clone <repository-url>
cd clini

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

pip install -r requirements.txt

Create a .env file in the root directory:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/clinic_ai

# Twilio Configuration
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
WEBHOOK_BASE_URL=https://your-domain.com

# ElevenLabs Configuration
ELEVENLABS_API_KEY=your_elevenlabs_api_key

# EHR Integrations (Optional)
ATHENA_CLIENT_ID=your_athena_client_id
ATHENA_CLIENT_SECRET=your_athena_client_secret
ATHENA_API_BASE_URL=https://api.athenahealth.com
ATHENA_PRACTICE_ID=your_practice_id

EPIC_CLIENT_ID=your_epic_client_id
EPIC_CLIENT_SECRET=your_epic_client_secret
EPIC_FHIR_BASE_URL=https://fhir.epic.com/interconnect-fhir-oauth
EPIC_REDIRECT_URI=http://localhost:8000/callback

# Application Settings
SECRET_KEY=your_secret_key_here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Run Alembic migrations
alembic upgrade head

# Or create tables directly (development only)
python -c "from database import create_tables; create_tables()"

# Development mode with auto-reload
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Or using the main entrypoint
python main.py

The API will be available at http://localhost:8000
Interactive API documentation: http://localhost:8000/docs
Alternative docs: http://localhost:8000/redoc

clini/
├── alembic/                 # Database migrations
├── config/                  # Configuration files
├── integration/             # External service integrations
│   ├── athena_health_client.py
│   ├── epic_fhir_client.py
│   └── webhook_tools.py
├── routes/                  # API route handlers
│   ├── admin_routes.py
│   ├── agent_setup_routes.py
│   ├── auth.py
│   ├── conversation_routes.py
│   └── ...
├── services/                # Business logic services
│   ├── agent_setup_service.py
│   ├── conversation_service.py
│   ├── twilio_service.py
│   └── ...
├── system_prompts/          # AI system prompts
├── database.py              # Database configuration
├── models.py                # SQLAlchemy models
├── schemas.py               # Pydantic schemas
├── main.py                  # FastAPI application entry point
└── requirements.txt         # Python dependencies

• Framework: FastAPI 0.115+
• Database: PostgreSQL with SQLAlchemy ORM
• Migrations: Alembic
• Authentication: JWT (JSON Web Tokens)
• Telephony: Twilio
• Conversational AI: ElevenLabs
• EHR Integration: AthenaHealth API, Epic FHIR R4
• Validation: Pydantic
• Async HTTP: httpx

• POST /clinic/register - Register a new clinic
• POST /clinic/login - Clinic authentication
• POST /api/setup/agent - Create and configure AI agent
• POST /api/setup/phone-number - Purchase Twilio phone number
• GET /api/conversations - Retrieve conversation history
• GET /api/conversations/{conversation_id} - Get conversation details
• GET /admin/* - Administrative endpoints

Full interactive API documentation is available at /docs when the server is running.

The API uses JWT-based authentication. Include the token in the Authorization header:

Authorization: Bearer <your_jwt_token>

• Clinic: Clinic information and AI configuration
• Patient: Patient records and insurance information
• Staff: Clinic staff with role-based permissions
• Appointment: Appointment scheduling and management
• Call: Call records with transcripts and analytics
• KnowledgeBase: Clinic-specific Q&A knowledge
• InsurancePlan: Accepted insurance plans and coverage

See models.py for complete schema definitions.

1. Register Clinic: POST /clinic/register
2. Create AI Agent: POST /api/setup/agent
3. Purchase Phone Number: POST /api/setup/phone-number
4. Upload Knowledge Base: POST /api/setup/knowledge-base
5. Configure Agent Settings: Update clinic configuration

1. Inbound call received via Twilio
2. Twilio forwards to ElevenLabs webhook
3. ElevenLabs agent processes conversation
4. Our platform receives webhook events
5. Conversation state synced to database
6. Transcripts and analytics generated

# Test database connection
python test_db_connection.py

# Test ElevenLabs API connectivity
python test_elevenlabs_api.py

# Test environment configuration
python test_env_config.py

• Use managed PostgreSQL (AWS RDS, Google Cloud SQL)
• Set up reverse proxy (Nginx) for SSL termination
• Configure environment variables securely
• Enable database connection pooling
• Set up automated backups
• Use process manager (systemd, supervisord)
• Configure CORS for production domains
• Set up monitoring and logging

# Using Gunicorn with Uvicorn workers
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

1. Follow existing code style and patterns
2. Add type hints to new functions
3. Write docstrings for public methods
4. Use Alembic for database schema changes
5. Test your changes before submitting

Proprietary - Internal use only

For issues, questions, or contributions, please contact the development team.

• FastAPI Documentation
• ElevenLabs API Docs
• Twilio Documentation
• SQLAlchemy Documentation

Version: 1.0.0
Last Updated: 2025