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
|
||
|---|---|---|
| .. | ||
| ai-and-voice.md | ||
| architecture.md | ||
| auth-admin-learning.md | ||
| bedside-and-calculators.md | ||
| clinical-notes.md | ||
| ed-encounters.md | ||
| README.md | ||
Application Logic — index
Deep, dev-friendly documentation of how each part of the ped-ai app actually works. Written so a human developer can understand the codebase without spelunking, and so an AI assistant can confidently modify code without breaking high-risk workflows.
These docs explain application logic — what the user does, what the
system does in response, what the data flow is, and why the design
looks the way it does. They are not API reference (see
../api-reference.md) and not deployment
recipes (see ../deployment.md).
Read in this order
For someone brand new to the codebase:
-
architecture.md — Start here. The big picture: current frontend pattern, lazy tab loading, backend route convention, PostgreSQL schema, encryption at rest, Dockerfile + compose layout, and high-risk zones.
-
clinical-notes.md — How every clinical note tab works. The shared "record → transcribe → generate → save" lifecycle, then per-tab deep dives for Encounter HPI, Dictation HPI, Sick Visit, Well Visit, SOAP, Hospital Course, Chart Review, and Personal Notes. Includes the helper trio (refine / billing-codes / don't-miss).
-
ed-encounters.md — The ED encounter feature (multi-stage notes, per-stage don't-miss, consolidate→MDM finalize). Newest, most explicit explanation of how a clinical workflow gets composed in this codebase. Read this for a worked example.
-
bedside-and-calculators.md — Bedside emergencies module, the pediatric calculators (BP percentile, Fenton growth, bilirubin nomograms, etc.), the PE Guide, vax schedule, milestones. Includes the suture selector. Important: lists every clinical formula that must NOT be modified without test vectors.
-
ai-and-voice.md — AI provider routing (
callAI), the centralizedPROMPTSobject with DB overrides, thewrapUserText+INJECTION_GUARDsafety pattern, server-side STT routing, TTS, and the AudioRecorder. Voice/STT plumbing is high-risk — the doc describes it without proposing changes. -
auth-admin-learning.md — Authentication (local + OIDC SSO + 2FA), session management, OpenBao secret loading at container start, the Admin panel (model allowlist, prompt overrides, milestone editor), and the Learning Hub (AI-authored quizzes / outlines / Marp presentations).
What's NOT here
- Reference data details. Every clinical formula's math lives in the source files; this doc series points to the formula and explains what it does but doesn't reproduce the lookup tables.
- API endpoint signatures. See
../api-reference.md. - Operational runbooks. See
../deployment.md,../configuration.md. - Recent change history. See git log + the rollback tags
(
pre-ts-migration-2026-04-26,pre-ed-encounters-2026-04-26, etc.).
Voice + conventions
Each doc follows the same structure:
- Overview — what this part is and why it exists
- User flow — what the physician does and sees
- Data flow — what HTTP calls happen, what the server does
- File map — which files do what
- Key design decisions — why it works the way it does
- High-risk zones — what requires small, tested changes
- How to extend — concrete recipes for adding a new X
When a doc mentions a high-risk zone, changes should be small, well-tested, and directly tied to the requested behavior. Current high-risk areas:
| Zone | Why |
|---|---|
public/js/encounters.js save/load/idempotency |
Save/version/idempotency logic has been carefully tuned; refactors keep silently breaking it. |
Voice/STT plumbing (audioBackup.js, speechRecognition.js, voicePreferences.js, transcriptionSettings.js, recorder paths in each clinical tab) |
Recording UX has been hardened against many edge cases; refactor only with smallest-diff bug fixes. |
| Validated clinical formulas (BP percentile LMS, Fenton 2013, bilirubin AAP 2022, Bhutani, APLS / Best-Guess weight, PE Guide SCALES) | Validated against peditools / AAP tables; modifying without test vectors risks miscoding patient care. |
Auth + crypto (crypto.js, passwords.js, sessions.js, auth.js, oidc.js) |
Security; changes without security review are unsafe. |
MDM rubric in PROMPTS.edFinalize |
Load-bearing for billing accuracy; trim only with explicit AMA/coding source citation. |
Cross-cutting topics
A few topics span multiple docs. Use these as your jump-off points:
| Topic | Where to look |
|---|---|
| Frontend globals, ES modules, and lazy tab loading | architecture.md |
Lazy tab loading (loadComponent, tabChanged event) |
architecture.md |
getUserMemoryContext → templates feeding into AI prompts |
clinical-notes.md §6, ed-encounters.md §9 |
The helper trio: refineDocument, suggestBillingCodes, suggestDontMiss |
ai-and-voice.md §12, clinical-notes.md §5 |
wrapUserText + INJECTION_GUARD prompt-injection defense |
ai-and-voice.md §5 |
saveEncounter API + optimistic locking + idempotency keys |
architecture.md §13, clinical-notes.md §4, ed-encounters.md §5 |
cryptoUtil.encryptString / encryptBuffer "enc1:" format |
architecture.md §12 |
AI provider routing (callAI) |
ai-and-voice.md §2-3 |
| 2023 AMA E/M MDM rubric | ed-encounters.md §6 |
User templates (user_memories table, template_* categories) |
clinical-notes.md §6, ed-encounters.md §9 |
How to keep these docs current
Each doc has a date implicit in the most recent feature it describes. When you add a feature, update the relevant doc in the same commit. When you remove a feature (e.g., the Dragon-style AI corrections removal in late April 2026), remove its section + leave a one-line historical note in the relevant doc.
When you write a new doc, follow the same structure as these (Overview / User flow / Data flow / File map / Design decisions / Sacred zones / How to extend) and add it to this index.