# 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 sacred zones.

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`](../api-reference.md)) and not deployment
recipes (see [`../deployment.md`](../deployment.md)).

## Read in this order

For someone brand new to the codebase:

1. **[architecture.md](architecture.md)** — Start here. The big picture:
   IIFE frontend pattern, lazy tab loading, backend route convention,
   PostgreSQL schema, encryption at rest, Dockerfile + compose layout,
   sacred zones. (~2,000 lines, the longest doc — but the foundation.)

2. **[clinical-notes.md](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](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-and-calculators.md)** —
   Bedside emergencies module (the one ES-module pocket of the
   frontend), 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-and-voice.md)** — The 5-provider AI routing
   (`callAI`), the centralized `PROMPTS` object with DB overrides, the
   `wrapUserText` + `INJECTION_GUARD` safety pattern, server-side STT
   routing (Whisper / AWS Transcribe / Vertex / LiteLLM), browser
   Whisper, the AudioRecorder. Voice/STT plumbing is **sacred** — the
   doc describes it without proposing changes.

6. **[auth-admin-learning.md](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`](../api-reference.md).
- **Operational runbooks.** See [`../deployment.md`](../deployment.md),
  [`../configuration.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
- **Sacred zones** — what NOT to refactor without explicit approval
- **How to extend** — concrete recipes for adding a new X

When a doc mentions a sacred zone, it means there's a project-memory
rule that this code must not be refactored without per-change approval
from Daniel. The full sacred-zone roster:

| 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`, `browserWhisper.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. |

## Total size

~8,300 lines of new application-logic documentation across 6 files. If
that feels like a lot, remember: the codebase is ~33,000 lines of
frontend JS + ~14,000 lines of backend JS. The docs are dense by design
— "200% detailed" was the explicit ask. Search them like a reference;
don't try to read end to end.

## Cross-cutting topics

A few topics span multiple docs. Use these as your jump-off points:

| Topic | Where to look |
|---|---|
| The IIFE pattern + `window.x = y` cross-file globals | architecture.md §2-3 |
| Lazy tab loading (`loadComponent`, `tabChanged` event) | architecture.md §3-4 |
| `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 |
| 5-provider AI 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.