🩺 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

---

OpenID Connect / SSO (optional — PocketID, Keycloak, Azure AD, etc.)

Enable Single Sign-On authentication with any OpenID Connect provider. Users can log in with their SSO provider, and existing accounts are automatically linked by email.

Supported providers: PocketID, Keycloak, Azure AD / Entra ID, Okta, Google Workspace, and any OIDC-compliant provider.

Quick Setup

1. Register this app with your OIDC provider using callback URL:

   https://your-domain.com/api/auth/oidc/callback
   

2. Log into the app as admin and navigate to Admin Panel → Settings

3. Configure OIDC settings:

   • Enable OIDC
   • Set Issuer URL (e.g., https://id.example.com)
   • Enter Client ID and Client Secret from your provider
   • Customize the button label (e.g., "Sign in with PocketID")

4. Save and test the login

Detailed setup guide with examples for all providers: OPENID_SETUP.md

Linking Existing Users

When a user signs in via SSO, the system automatically links their account if the email matches an existing user. No manual intervention needed.

For advanced scenarios (manual linking, CLI commands, troubleshooting), see OPENID_SETUP.md.

---

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