67e416c6d9
Some checks failed
Forgejo Android APK / Root app tests (push) Successful in 47s
Forgejo Docker Build / Root app tests (push) Successful in 48s
Forgejo Android APK / Build signed APK (push) Successful in 2m38s
Forgejo Docker Build / Build Docker image (push) Successful in 12s
Forgejo Docker Build / Deploy to the host (push) Failing after 2s
Three pairs of docs described the same thing twice, and the copies had drifted
apart. Merged each into one file, keeping the unique content from both:
- ARCHITECTURE.md -> architecture.md (its operational map: ownership, request
flow, runtime boundaries, source of truth, deployment shape)
- DEVELOPMENT.md -> developer-guide.md (change workflow, Clinical Assistant
high-risk areas, frontend rendering rules, deployment checks)
- transcription-options.md -> speech.md (the clinic setup table, and the list
of browser-Whisper paths that must stay removed)
Then audited what remained against the code and the live database rather than
against the previous docs. Corrected:
- Google Vertex was still documented as a provider across nine files. The SDK
is gone; AI_PROVIDER=vertex now logs an advisory and falls back to
OpenRouter, and Gemini is reached through LiteLLM. Fixed the provider
selection order to match src/utils/ai.js, which starts from LITELLM_API_BASE.
- promptSafe was documented on 8 routes; it is on 13.
- Node 20 -> 24, "24 vanilla JS modules" -> no fixed count, and
transcribe.js/tts.js -> sttProvider.js/ttsProvider.js, which is what exists.
- STT/TTS are LiteLLM-only; README listed direct Google, AWS Transcribe and
ElevenLabs paths that are not in the runtime.
- Learning Hub PPTX export was documented as pptxgenjs, which is not a
dependency. It is pandoc against a reference deck.
- POST /api/admin/milestones/seed does not exist; it is /bulk-import.
- NEXTCLOUD_URL and NTFY_TOPIC are not read anywhere. Nextcloud is per-user in
the users table, and the ntfy topic is derived as pedscribe-{userId}.
- A prose paragraph sat inside the Clinical Assistant settings table, so half
the rows rendered as text.
Filled the gaps the audit exposed:
- database.md was missing 12 of 29 tables, including user_resources,
personal_notes, login_codes, registration_invites and generated_image_jobs.
- developer-guide.md was missing 11 routers and 10 frontend modules.
- api-reference.md detailed 121 of 244 endpoints and said so, but whole
features were absent. Added an endpoint index covering Clinical Assistant,
My Resources, Notes, Diagrams, ED Encounters, invites and sign-in codes.
- configuration.md was missing METRICS_TOKEN, REDIS_URL, API_RATE_LIMIT_MAX,
the LITELLM_* model variables, the DB_* ones maintenance.js reads, and the
per-purpose S3 resolution scheme.
- clinical-assistant.md documented 2 of its 17 environment variables.
- features-explained.md had no entry for My Resources or Clinical Assistant.
Renamed the three remaining SHOUTING filenames to kebab-case, which is what the
docs viewer's prettyName() was working around, and rewrote README's index,
which listed architecture.md twice and omitted nine files.
Noted but not changed: the Turnstile site key is hardcoded in index.html rather
than read from TURNSTILE_SITE_KEY, and /api/health/detailed can report
tts: 'elevenlabs' though no ElevenLabs path exists.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dv6sqaY6Vq3ChZHMem3cnU
197 lines
9.1 KiB
Markdown
197 lines
9.1 KiB
Markdown
# 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](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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```env
|
|
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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Run syntax checks for touched files when doing focused backend work:
|
|
|
|
```bash
|
|
node --check server.js
|
|
node --check src/routes/transcribe.js
|
|
```
|
|
|
|
Run the Playwright smoke suite against the e2e compose stack:
|
|
|
|
```bash
|
|
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.
|