025290d64a
Some checks failed
Forgejo Android APK / Root app tests (push) Successful in 47s
Forgejo Docker Build / Root app tests (push) Successful in 45s
Forgejo Android APK / Build signed APK (push) Successful in 2m1s
Forgejo Docker Build / Build Docker image (push) Successful in 9s
Forgejo Docker Build / Deploy to the host (push) Failing after 0s
My Resources generates better slides than Learning Hub ever did — a typed deck the model fills in, rendered by python-pptx with fit-to-slide text, figures, a vision review and themes, against Learning Hub's markdown-through-pandoc — and the articles and quizzes now live in the quiz app. Keeping a second, weaker generator and a whole CMS beside it was not earning its maintenance. Removed: three routers, the Learning Hub and Content Manager tabs, their components and frontend modules, the five database tables, the WebDAV browser, the content embedding column and its vector index. Content was exported first — every article as markdown plus a full SQL dump of all five tables — to ops-backups/learning-hub-export-*. That export is the restore path; the migration's down() can recreate the shape but never the rows, and says so. Two things this simplifies rather than merely deletes: generated_image_links existed only to record which published content an image appeared in, and it was the sole reason a generated image could be read by someone who did not make it. Images are now owner-only — the visibility rule is one WHERE clause instead of a join across two tables and a published flag. embeddings.js keeps the model discovery the admin panel uses and loses searchSimilar and generateContentEmbedding, which queried a table that no longer exists. Kept deliberately: Nextcloud connect, disconnect and export, which are how a generated note reaches a real filesystem and have nothing to do with Learning Hub; learningRetrieval, which despite its name is the clinical corpus search My Resources depends on; and the pandoc reference deck, still the fallback when the python renderer fails, moved from assets/learning to assets/deck now that the old name misleads. Tests: four Learning-Hub-only files removed, and the individual cases inside shared files that asserted its behaviour. Where a test used a Learning endpoint only as a convenient example — the account-boundary token test, the policy matrix — it now uses one that still exists, so the property it proves is unchanged. 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.