pediatric-ai-scribe-v3/README.md

Ped-AI

Ped-AI is a pediatric clinical documentation, education, and bedside decision-support app. This fork has moved well beyond the original scribe app: it now combines encounter documentation, clinical workflows, Learning Hub CMS, admin controls, MCP-backed clinical assistant integration, Redis-backed operational state, and hardened deployment defaults.

The app runs as an authenticated Express/Postgres service with a browser frontend and optional integrations for LiteLLM, AWS, OpenAI-compatible APIs, Nextcloud WebDAV, S3-compatible storage, OpenBao, Redis, OIDC, TOTP, and Cloudflare Turnstile.

Current Scope

Clinical Documentation

• Live encounter capture with structured pediatric HPI generation.
• Dictation cleanup for narrative notes.
• SOAP, sick visit, well visit, hospital course, chart review, precharting, and ED encounter workflows.
• Parent-facing education handouts generated from clinician notes, with diagnosis, medication, emergency-care guidance, and preferred-language support.
• Pediatric developmental milestone tooling.
• Templates, physician memory, and per-tab model overrides.
• Server-side speech-to-text routing through configured providers.

Bedside Tools

• Pediatric calculators and emergency dosing helpers.
• PE guide and clinical reference content.
• Vaccines, catch-up schedules, growth/vitals, bilirubin, BSA, GCS, equipment, and resuscitation helpers.
• Mobile-friendly PWA layout for bedside use.
• Per-user phone extension and pager directory with soft-delete, search, ZIP export, and JSON/ZIP import for handoff between users.

Learning Hub

• CMS for articles, clinical pearls, quizzes, and presentations.
• Tiptap article editor, quiz builder, category management, and draft/publish flow.
• AI-assisted content generation from topic text, uploaded files, or connected Nextcloud WebDAV files.
• Marp slide editing with preview and PPTX export.
• Keyword, semantic, and hybrid search using Postgres/pgvector where configured.

My Resources

• Private teaching material any signed-in user can generate for themselves — nobody else sees it.
• Presentations are designed as slide decks (comparisons, tables, callouts, figures beside text), not written as markdown for a parser to guess at.
• Grounded in the indexed clinical library, and optionally PubMed and the web, each admin-enabled.
• Optional illustrations, several per resource, placed through the deck.
• Revise in place, and download as PowerPoint, Word or PDF. See docs/my-resources.md.

Clinical Assistant

• Optional MCP-backed clinical assistant integration.
• Prompt suggestions backed by Redis operational cache.
• No clinical answer response caching.
• Designed to retrieve from indexed clinical material while keeping provider selection explicit.

Admin And Security

• Sign in with a password or a six-digit code emailed to you — offered side by side, because a code depends on mail arriving and a password does not.
• Role-based access, TOTP 2FA, OIDC/SSO, email verification, and optional Turnstile. Passwords are argon2id, with bcrypt rows rehashed on their next sign-in.
• Registration can be open, closed, or invite-only with generated codes. A code can be revoked while live, and deleted only once it is spent.
• Admin panel for users, settings, prompts, models, logs, and Learning Hub content.
• Audit, API, access, and client-error logs with redaction hardening.
• OpenBao secret loading support at container startup.
• S3-compatible document storage support.

Removed Browser STT

Browser Whisper has been removed from the runtime. The app should not ship browser Whisper workers, browser-local Whisper model downloads, Transformers.js browser STT, or Browser Whisper setup docs.

Speech-to-text is handled server-side through configured providers such as Google/Gemini, AWS Transcribe, LiteLLM, or OpenAI Whisper. Browser-native Web Speech remains gated behind an explicit user setting when present in the browser — it is off unless a user turns it on, because Chrome and Edge send that audio to Google.

Quick Start

cp .env.example .env
./scripts/build-image.sh
docker compose up -d --no-build

The default compose exposes the app on 127.0.0.1:3552 and starts:

• pediatric-ai-scribe for the Node app.
• pedscribe-db for Postgres with pgvector.
• ped-ai-redis for operational Redis state.

Health check:

curl -fsS http://127.0.0.1:3552/api/health

Prometheus metrics are exposed at GET /metrics with the ped_ai_ metric prefix.

The first registered user becomes an admin unless registration has already been configured differently.

Core Environment

Set real values in .env before production use.

APP_URL=https://your-domain.example
JWT_SECRET=<64-char-random-secret>
DB_PASSWORD=<strong-database-password>

AI_PROVIDER=litellm
LITELLM_API_BASE=https://your-litellm.example/v1
LITELLM_API_KEY=<key>

TRANSCRIBE_PROVIDER=litellm
LITELLM_STT_MODEL=whisper-1

REDIS_URL=redis://ped-ai-redis:6379

Supported text AI providers are LiteLLM, OpenRouter, AWS Bedrock, and Azure OpenAI. Speech-to-text and text-to-speech both route through LiteLLM, so the upstream speech vendor is a gateway configuration choice rather than an app one; browser-native Web Speech stays off unless a user opts in.

Admin CLI

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

Maintenance

The app checks Postgres collation drift on startup and can reindex text indexes after image or OS-library changes.

docker exec pediatric-ai-scribe npm run maint:check
docker exec pediatric-ai-scribe npm run maint:reindex

Run the reindex command after major Postgres image changes, restoring a dump from another distro, or seeing lookup behavior that suggests collation/index drift.

Testing

Run the Node test suite:

npm test

Run syntax checks for touched files when doing focused backend work:

node --check server.js
node --check src/routes/transcribe.js

Run the Playwright smoke suite against the e2e compose stack:

docker compose -f docker-compose.yml -f docker-compose.e2e.yml up -d pediatric-scribe-e2e
npm run e2e

Deployment Notes

• Put the app behind HTTPS before clinical use.
• Use only AI/STT/TTS providers covered by your BAA and data-processing requirements.
• Configure OIDC/SSO and 2FA for production users.
• Keep JWT_SECRET, database credentials, provider keys, S3 keys, SMTP credentials, and OpenBao tokens out of git.
• Treat logs as sensitive operational data even with redaction enabled.
• Use the Caddy/reverse-proxy layer to expose only intended public routes.

Documentation

Primary references:

• docs/architecture.md — system map, repository layout, request pipeline, and service boundaries.
• docs/developer-guide.md — day-to-day code-change workflow, route and module reference.
• docs/module-conventions.md — CommonJS, ESM, globals, and rendering rules.
• docs/features-explained.md — what each feature is, in plain terms.
• docs/api-reference.md — API routes.
• docs/configuration.md — environment variables and live app_settings.
• docs/database.md — every table, its columns, and what is encrypted.
• docs/migrations.md — how schema changes are made and applied.
• docs/authentication.md — auth, OIDC, sign-in codes, invites, rate limits.
• docs/ai-providers.md — provider selection, prompts, injection hardening.
• docs/clinical-assistant.md — MCP-backed assistant behavior and safety rules.
• docs/retrieval-tuning.md — how much corpus each feature retrieves, and what it costs.
• docs/embeddings-setup.md — embedding model configuration.
• docs/global-prompt-administration.md — prompt overrides and the conversation budget.
• docs/speech.md — STT, TTS, recording, and audio backups.
• docs/learning-hub.md — the CMS and education workflow.
• docs/my-resources.md — private teaching material, the slide renderer, and search sources.
• docs/deployment.md — production deployment.
• docs/scaling.md — scaling priorities and readiness work.
• docs/openid-setup.md — OIDC provider setup.
• docs/mobile-build.md — the Capacitor wrapper and app-store build notes.
• docs/ops-docs-ped-ai-and-milvus.md — operational notes for the retrieval stack.
• docs/improvements.md — the running list of what to improve next.
• docs/logic/README.md — the deeper code walkthrough.

Some deep docs/logic/ files still describe historical implementation details. Prefer runtime code and tests when documentation conflicts with current behavior.

Clinical Safety

Ped-AI is documentation and education support software. It does not replace clinical judgment, local policy, medication verification, or attending review. Validate generated notes, calculations, and recommendations before use in patient care.