danvics/pediatric-ai-scribe-v3
1
0
Fork 0
Code Issues Pull requests Projects Releases 16 Packages Wiki Activity Actions
pediatric-ai-scribe-v3/README.md
Daniel fa2e7523d6
Some checks failed
Forgejo Docker Build / Build Docker image (push) Blocked by required conditions
Details
Forgejo Docker Build / Deploy to the host (push) Blocked by required conditions
Details
Forgejo Android APK / Root app tests (push) Successful in 50s
Details
Forgejo Docker Build / Root app tests (push) Successful in 48s
Details
Forgejo Android APK / Build signed APK (push) Has been cancelled
Details
docs: My Resources, sign-in codes, invitations, and what the image carries 
Nothing documented My Resources, the slide renderer, PubMed or web search, and
the authentication doc predated both sign-in codes and registration invitations.

docs/my-resources.md is new and covers the feature end to end: what a resource
is, where its material comes from, why both searches run in the route rather
than as tools the model never called, why keyword engines get the topic while
retrieval gets the instruction too, how a presentation is designed as a deck
rather than written as markdown, the separate multi-image path, and what the
export pipeline is made of.

docs/authentication.md gains sign-in codes — storage, lifetime, reuse,
supersession, guessing, and that two-factor still applies — and registration
invitations, including the exact condition that decides when a code may be
deleted and why it is written to match the status the list displays. Both new
rate limits are in the table, with a note that Express matches app.use paths on
segment boundaries, so a new sign-in endpoint needs its own limiter or it has
none at all.

docs/deployment.md now says what the runtime image carries and why — pandoc for
Word, python3 with apk-installed lxml and pillow for the slide renderer,
python-pptx pinned, and that PDF conversion is not in the image at all but goes
to Gotenberg, so Word and PowerPoint still work when it is down.

docs/configuration.md picks up LOGIN_RATE_LIMIT_MAX, LOGIN_CODE_RATE_LIMIT_MAX
and GOTENBERG_URL, none of which were listed. README gains a My Resources
section and indexes the two new docs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dv6sqaY6Vq3ChZHMem3cnU
2026-09-11 20:49:10 +02:00

8.1 KiB
Raw Blame History

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, Vertex/Gemini, 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

  • Local auth, role-based access, TOTP 2FA, OIDC/SSO, email verification, and optional Turnstile.
  • 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.

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 include LiteLLM, OpenRouter, AWS Bedrock, Azure OpenAI, and Google Vertex AI. Supported STT routing includes Google/Gemini, AWS Transcribe, OpenAI Whisper, and LiteLLM. Supported TTS routing includes Google Cloud TTS, LiteLLM/OpenAI-compatible audio, and ElevenLabs where configured.

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 for the current system map and service boundaries.
  • docs/DEVELOPMENT.md for day-to-day code-change workflow.
  • docs/SCALING.md for scaling priorities and readiness work.
  • docs/CLINICAL_ASSISTANT.md for MCP-backed assistant behavior and safety rules.
  • docs/MODULE_CONVENTIONS.md for CommonJS, ESM, globals, and rendering rules.
  • docs/architecture.md for high-level architecture.
  • docs/api-reference.md for API routes.
  • docs/authentication.md for auth, OIDC, and security configuration.
  • docs/ai-providers.md for model/provider setup.
  • docs/speech.md for server-side STT/TTS setup.
  • docs/learning-hub.md for the CMS and education workflow.
  • docs/my-resources.md for private teaching material, the slide renderer, and search sources.
  • docs/retrieval-tuning.md for how much corpus each feature retrieves, and what it costs.
  • docs/configuration.md for environment variables.
  • docs/deployment.md for production deployment.
  • docs/mobile-build.md for the Capacitor wrapper and app-store build notes.
  • docs/logic/README.md for 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.