05dcd1146d
Three separate reasons tests were failing, none of them a defect in the app. The calculators. e2e-harness.html loaded calculators.js and drugs-loader.js with `defer` after they were split into ES modules; index.html was updated at the time and this page was not. A module parsed as a classic script throws "Cannot use import statement outside a module" before a line runs, so no click handler was ever attached: the pills rendered from static HTML and did nothing. Only the first calculator appeared to pass, because it carries `active` in the markup and needs no click. That was 52 failures. Settings and FAQ. Both moved from the tab rail into the account-card menu; the helper still clicked button.tab-btn[data-tab=…] and timed out. Ten more. The AI mocks, which had stopped intercepting for two independent reasons and so were calling the real model on every run — spending credits and comparing genuine output against strings like "MOCK HPI from dictation". A '**/api/x' glob matches no URL on Playwright 1.50, and page.route fails silently when nothing matches; measured against a real URL, that glob and '*/**/api/x' both matched zero times where a regex matched. Fixing that alone was not enough: the app registers a service worker that answers every /api/ request with its own fetch(), and a request made inside a service worker never reaches page.route. Blocking registration in the config puts them back in the page. The mocked dictation test now finishes in 1.6s rather than 7.5s, which is what a real model call costs. Whole suite: 204 passed / 96 failed in 15.8 minutes, now 289 passed / 11 failed in 6.8. The remaining eleven are spread across nine specs with no shared cause and are not touched here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dv6sqaY6Vq3ChZHMem3cnU |
||
|---|---|---|
| .forgejo/workflows | ||
| .github | ||
| android | ||
| assets/learning | ||
| docs | ||
| e2e | ||
| migrations | ||
| mobile | ||
| monitoring | ||
| public | ||
| scripts | ||
| src | ||
| test | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| .gitmessage | ||
| .node-pg-migraterc.json | ||
| admin-cli.js | ||
| CONTRIBUTING.md | ||
| docker-compose.e2e.yml | ||
| docker-compose.local.yml | ||
| docker-compose.monitoring.yml | ||
| docker-compose.yml | ||
| docker-entrypoint.sh | ||
| Dockerfile | ||
| grafana-dashboard.json | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| server.js | ||
| TODO.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, 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.
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-scribefor the Node app.pedscribe-dbfor Postgres with pgvector.ped-ai-redisfor 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.mdfor the current system map and service boundaries.docs/DEVELOPMENT.mdfor day-to-day code-change workflow.docs/SCALING.mdfor scaling priorities and readiness work.docs/CLINICAL_ASSISTANT.mdfor MCP-backed assistant behavior and safety rules.docs/MODULE_CONVENTIONS.mdfor CommonJS, ESM, globals, and rendering rules.docs/architecture.mdfor high-level architecture.docs/api-reference.mdfor API routes.docs/authentication.mdfor auth, OIDC, and security configuration.docs/ai-providers.mdfor model/provider setup.docs/speech.mdfor server-side STT/TTS setup.docs/learning-hub.mdfor the CMS and education workflow.docs/configuration.mdfor environment variables.docs/deployment.mdfor production deployment.docs/mobile-build.mdfor the Capacitor wrapper and app-store build notes.docs/logic/README.mdfor 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.