pediatric-ai-scribe-v3/docs/logic

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:

1. 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.

2. 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).

3. 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.

4. 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.

5. ai-and-voice.md — AI provider routing (callAI), the centralized PROMPTS object with DB overrides, the wrapUserText + INJECTION_GUARD safety pattern, server-side STT routing, TTS, and the AudioRecorder. Voice/STT plumbing is high-risk — the doc describes it without proposing changes.

6. 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.