ceccd18387
The feature was removed; the docs still described it as live. Worst of it was api-reference.md, which documented nine /api/learning endpoints and fourteen /api/admin/learning CMS endpoints — routes that answer 404 — plus POST /api/user/webdav-path, whose column was dropped by migration. Anyone reading them was reading fiction. Checked against the running system rather than assumed: no learning table exists, users.webdav_learning_path is gone, generated_image_links is gone, and no route mounts /api/learning or /api/admin/learning. Two things that look like Learning Hub and are not, so they stay: - learningRetrieval.js is live — My Resources uses it. Its settings keep the learning.* names because renaming them would orphan whatever an administrator has already set. retrieval-tuning.md now says so instead of listing the rows under two different feature names. - the moderator role is still assignable. It gated the CMS and now grants nothing; authentication.md says that rather than implying powers it does not have. moderatorMiddleware has no callers left, which is worth removing on its own. auth-admin-learning.md is now auth-admin.md. 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.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.md — Authentication (local + OIDC SSO + 2FA), session management, OpenBao secret loading at container start, and the Admin panel (model allowlist, prompt overrides, milestone editor).
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.