67e416c6d9
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
6 KiB
Features Explained
This file is a practical operator-oriented overview of major Ped-AI features. It intentionally describes the current fork, not historical browser Whisper behavior.
Clinical Documentation
Ped-AI generates pediatric clinical notes from typed input, dictation, or recorded audio. Major workflows include live encounters, dictation cleanup, sick visits, well visits, SOAP notes, hospital courses, chart review, ED documentation, and developmental milestones.
Model selection is available per task where the UI exposes a tab-level selector. Admin defaults provide the baseline model and user/task choices can override that baseline.
Generated notes can expose post-note helper panels. Billing suggestions and don't-miss review are clinician-facing. Patient education handouts are parent-facing drafts generated from the edited note, with optional diagnosis, medication, and preferred-language context. The clinician must verify the handout before sharing it.
Phone Extensions And Pagers
The bedside tools include a per-user phone extension and pager directory. Entries support active/trash views, search, soft delete/restore, permanent purge, ZIP export, and JSON/ZIP import. Import preview flags exact active duplicates, exact trashed matches that can be restored, and possible duplicates before committing changes.
Speech
Final transcription is server-side through LiteLLM. Configure upstream STT providers in LiteLLM rather than in Ped-AI.
Browser-native Web Speech is only an explicit opt-in preview path. It is not the final clinical transcript and may use browser-vendor cloud services.
Browser Whisper and browser-local model workers are removed. Do not expect a pre-download model button, public Whisper worker, or bundled Xenova model path.
Text To Speech
The voice preview button calls LiteLLM TTS and plays the returned audio in the browser. If preview is silent, check that a LiteLLM voice is selected, the gateway is configured, the user is authenticated, and browser autoplay has not blocked playback.
Learning Hub
Learning Hub is both a learner-facing content area and an admin/moderator CMS.
- Articles and pearls render sanitized content.
- Quizzes support single-answer, multi-select, and true/false questions.
- Presentations use Marp-style markdown with preview and PPTX export.
- AI generation can use topic text, uploaded source files, or connected Nextcloud WebDAV files.
- Categories can organize content without deleting the content when category assignments change.
Nextcloud WebDAV
Users can connect a Nextcloud account with an app password. Learning Hub AI generation can browse files from the connected WebDAV account, and users can set a default browse path to avoid repeatedly navigating to the same clinical content folder.
Documents And S3
Document upload is optional and depends on S3-compatible storage configuration. Treat uploaded documents as PHI unless you have a separate deployment reason not to.
Audio Backups
Audio backups exist to recover failed transcription attempts.
- They are created when transcription fails.
- They are encrypted before persistent storage.
- They expire automatically.
- Users can retry or delete them from Settings.
My Resources
Personal teaching material a user generates for themselves: a presentation or a document, built from a subject and optional instructions, optionally grounded in PubMed, web search, and the clinical corpus, and optionally carrying generated figures.
Decks are stored as a typed deck rather than as markdown, and
scripts/render_pptx.py (python-pptx) renders that deck to PowerPoint;
scripts/render_docx.py (python-docx) renders the same typed source to Word.
Export also offers PDF, via Gotenberg, and plain markdown. An optional vision
review pass renders the deck, looks at the slides, and returns layout fixes; it
is off by default.
Full detail in my-resources.md.
Clinical Assistant
Answers clinical questions against the indexed corpus rather than from model
memory: Ped-AI asks the MCP retrieval service for sources, builds a grounded
prompt, and renders the answer with citations and source cards. Answers are
deliberately never cached. Full detail in
clinical-assistant.md.
Admin Panel
Admins can manage users, roles, registration, security settings, model defaults, prompts, logs, and Learning Hub content. Production deployments should enable SSO/2FA and restrict admin access.
Feature Status
| Feature | Status | Notes |
|---|---|---|
| Clinical note generation | Active | Provider depends on AI_PROVIDER, defaulting to LiteLLM when a gateway is configured. |
| Server transcription | Active | Routed through LiteLLM; the upstream vendor is a gateway choice. |
| Browser Web Speech preview | Optional | Explicit opt-in only. |
| Browser Whisper | Removed | No public worker or model download path. |
| Learning Hub CMS | Active | Articles, pearls, quizzes, presentations. |
| Nextcloud WebDAV | Active | Used for file browsing/content import. |
| Patient handouts | Active | Parent-facing, note-derived, preferred-language draft. |
| Extension transfer | Active | ZIP export plus JSON/ZIP import preview. |
| Audio backups | Active | Failure recovery only. |
| TTS preview | Active | Depends on configured provider. |
| Clinical Assistant | Active | Grounded answers over MCP retrieval, with citations and source cards. |
| My Resources | Active | Personal teaching decks and documents, rendered by python-pptx / python-docx. |
| Deck vision review | Optional | Off by default; one pass, admin-configurable model. |
| Passwordless sign-in codes | Active | Emailed 6-digit code; password sign-in always stays available. |
| Personal notes | Active | Including dictation, with trash and restore. |
Troubleshooting
- Check browser console for frontend errors.
- Check
docker logs pediatric-ai-scribe -ffor backend errors. - Check
/api/healthfor service status. - Check provider credentials and model names before debugging UI state.
- For Learning Hub file import failures, verify Nextcloud URL, username, app password, and folder path.