114 lines
6.1 KiB
Markdown
114 lines
6.1 KiB
Markdown
# 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`](../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:
|
|
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](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 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)** — 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](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
|
|
- **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.
|