🩺 Pediatric AI Scribe v3

AI-powered clinical documentation platform for pediatric medicine. Generates HPIs, hospital courses, chart reviews, SOAP notes, and developmental milestone assessments from voice recordings or dictation — in seconds, in plain copy-ready text.

Features

• Live Encounter → HPI — record a live doctor-patient conversation, AI generates a structured OLDCARTS HPI
• Voice Dictation → HPI / SOAP — dictate your narrative, AI cleans and restructures it
• Hospital Course Generator — paste progress notes, AI generates prose, day-by-day, organ-system (ICU), or psych format summaries
• Chart Review / Precharting — summarize outpatient, subspecialty, and ED notes into a precharting brief
• SOAP Note Generator — full SOAP or subjective-only from dictation
• Well Visit / Preventive Care — AAP 2025 Bright Futures periodicity; vaccines, screenings, billing codes; By Visit Age, Milestones, SSHADESS (12+), and Visit Note subtabs
• Sick Visit Note — quick documentation with auto-suggested ROS and PE systems from chief complaint
• Developmental Milestones — AAP/Nelson milestone tracker (birth–11 years) with narrative, structured list, or 3-sentence summary; copy to Visit Note
• SSHADESS Assessment — adolescent psychosocial screening for ages 12+; auto-fills into Visit Note
• Vaccine Schedule — full AAP immunization schedule reference
• Catch-Up Schedule — catch-up immunization guide
• Plain text output — all documents generated without markdown, ready to paste into any EHR
• Read Aloud — browser TTS reads generated documents; ElevenLabs (Adam voice) supported
• Copy & Export — one-click copy or export to Nextcloud
• Refine & Shorten — edit any document with plain-language AI instructions
• Per-tab model selector — choose fast vs. smart vs. reasoning models per task
• Collapsible sidebar — desktop sidebar collapses to icon rail, state persisted
• Save & Resume — encounters saved with unique IDs; persist across page refresh
• Admin Panel — user management, registration control, audit logs
• 2FA — TOTP-based two-factor authentication
• Multi-provider AI — OpenRouter, AWS Bedrock, or Azure OpenAI

---

Quick Start (Docker)

1. Clone and configure

git clone https://github.com/ifedan-ed/pediatric-ai-scribe-v3.git
cd pediatric-ai-scribe-v3
cp .env.example .env

Edit .env — at minimum set:

OPENROUTER_API_KEY=sk-or-v1-...
OPENAI_API_KEY=sk-...          # for Whisper transcription
JWT_SECRET=<64-char random string>
DB_PASSWORD=<strong password>
APP_URL=https://your-domain.com

Generate a strong JWT secret:

openssl rand -hex 32

2. Start

docker compose up -d

App runs on port 3552 by default. The first user to register becomes admin automatically.

3. Admin CLI (inside container)

docker exec pediatric-ai-scribe node admin-cli.js list-users
docker exec pediatric-ai-scribe node admin-cli.js create-admin admin@example.com password123 "Dr. Admin"
docker exec pediatric-ai-scribe node admin-cli.js make-admin user@example.com
docker exec pediatric-ai-scribe node admin-cli.js reset-password user@example.com newpassword
docker exec pediatric-ai-scribe node admin-cli.js toggle-registration
docker exec pediatric-ai-scribe node admin-cli.js stats

---

Docker Hub

docker pull danielonyejesi/pediatric-ai-scribe-v3:latest

Minimal docker-compose without building

services:
  app:
    image: danielonyejesi/pediatric-ai-scribe-v3:latest
    ports:
      - "3552:3000"
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: pedscribe
      POSTGRES_USER: pedscribe
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pedscribe"]
      interval: 10s
      retries: 5

volumes:
  pgdata:

---

AI Provider Configuration

Switch providers by changing AI_PROVIDER in .env. No code changes needed.

OpenRouter (default — cheapest, NOT HIPAA)

AI_PROVIDER=openrouter
OPENROUTER_API_KEY=sk-or-v1-...

AWS Bedrock (HIPAA compliant with BAA)

AI_PROVIDER=bedrock
AWS_BEDROCK_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

Or use an IAM role (no keys needed when running on EC2/ECS — just set the region).

Available Bedrock models (auto-selected when AI_PROVIDER=bedrock):

• vendor model Opus 4.6 — best language nuance (anthropic.agent-config-opus-4-6-20251001-v1:0)
• vendor model Sonnet 4.6 — recommended (anthropic.agent-config-sonnet-4-6-20251001-v1:0)
• vendor model Sonnet 4 (anthropic.agent-config-sonnet-4-20250514-v1:0)
• vendor model 3.5 Sonnet (anthropic.agent-config-3-5-sonnet-20241022-v2:0)
• vendor model 3 Haiku — cheapest (anthropic.agent-config-3-haiku-20240307-v1:0)
• Llama 3.1 70B / 8B
• Mistral Large

Azure OpenAI (HIPAA compliant with BAA)

AI_PROVIDER=azure
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=...
AZURE_DEPLOYMENT_NAME=gpt-4o-mini
AZURE_OPENAI_API_VERSION=2024-02-01

---

Transcription (Speech-to-Text)

Two providers supported. The app auto-selects AWS Transcribe when AWS_BEDROCK_REGION is set, otherwise falls back to OpenAI Whisper.

Amazon Transcribe (recommended for clinical use — HIPAA eligible)

Uses your existing Bedrock AWS credentials. No S3 bucket required — audio streams directly to AWS.

Requires ffmpeg installed on the server (handles audio format conversion from browser WebM to PCM). The Docker image includes ffmpeg automatically.

# Auto-enabled when AWS_BEDROCK_REGION is set.
# To force it explicitly:
TRANSCRIBE_PROVIDER=aws

# Amazon Transcribe Medical — trained on clinical speech.
# Knows drug names, diagnoses, procedures. Recommended.
AWS_TRANSCRIBE_MEDICAL=true
AWS_TRANSCRIBE_SPECIALTY=PRIMARYCARE
# Other specialty options: CARDIOLOGY, NEUROLOGY, ONCOLOGY, RADIOLOGY, UROLOGY

Install ffmpeg on non-Docker servers:

# Ubuntu/Debian
sudo apt-get install -y ffmpeg

# Amazon Linux / RHEL
sudo yum install -y ffmpeg

# macOS
brew install ffmpeg

OpenAI Whisper (default fallback)

OPENAI_API_KEY=sk-...
# Optionally force Whisper even when AWS is configured:
# TRANSCRIBE_PROVIDER=openai

---

Email (optional — for verification & password reset)

Without SMTP configured, email verification is skipped and users are auto-verified on registration.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@yourdomain.com

---

Environment Variables Reference

Variable	Required	Description
OPENROUTER_API_KEY	If using OpenRouter	OpenRouter API key
AI_PROVIDER	No	openrouter (default), bedrock, or azure
AWS_BEDROCK_REGION	If using Bedrock	e.g. us-east-1
AWS_ACCESS_KEY_ID	If using Bedrock (no IAM role)	AWS access key
AWS_SECRET_ACCESS_KEY	If using Bedrock (no IAM role)	AWS secret key
AZURE_OPENAI_ENDPOINT	If using Azure	Azure OpenAI endpoint URL
AZURE_OPENAI_API_KEY	If using Azure	Azure API key
AZURE_DEPLOYMENT_NAME	If using Azure	Deployment name, e.g. gpt-4o-mini
OPENAI_API_KEY	For Whisper transcription	OpenAI key (Whisper fallback)
TRANSCRIBE_PROVIDER	No	aws or openai — auto-detected from AWS config
AWS_TRANSCRIBE_MEDICAL	No	true to use Transcribe Medical (clinical accuracy)
AWS_TRANSCRIBE_SPECIALTY	No	PRIMARYCARE (default), CARDIOLOGY, NEUROLOGY, etc.
ELEVENLABS_API_KEY	No	ElevenLabs TTS (optional)
JWT_SECRET	Yes	Random 64-char string — keep secret
DATABASE_URL	No	PostgreSQL URL (auto-set by docker-compose)
DB_PASSWORD	Yes	PostgreSQL password
APP_URL	Recommended	Public URL e.g. https://scribe.example.com (used for CORS, emails)
PORT	No	Internal port, default 3000
SMTP_HOST	No	SMTP server for email
SMTP_PORT	No	Default 587
SMTP_USER	No	SMTP username
SMTP_PASS	No	SMTP password / app password
SMTP_FROM	No	From address for emails

---

HIPAA Notice

This application processes data through third-party AI APIs.

• ✅ All connections use HTTPS/TLS
• ✅ Authentication required for all AI endpoints
• ✅ 2FA available
• ✅ No patient data stored on server (only audit logs)
• ⚠️ OpenRouter does not offer a BAA — do not use with real PHI
• ✅ AWS Bedrock and Azure OpenAI offer BAAs — suitable for PHI with proper configuration

Recommendation: Do not enter real patient data until your organization has executed BAAs with all AI providers in use.

---

Development

npm install
cp .env.example .env   # edit with your keys
# Requires a running PostgreSQL instance (see DATABASE_URL in .env)
node server.js