# Clinical Note Workflows

Clinical note workflows share the same broad lifecycle:

1. User enters text or records audio.
2. Audio, when used, is transcribed by the configured server-side STT provider.
3. The frontend gathers demographics, structured form data, and optional user
   template context.
4. The route wraps user-derived text with `wrapUserText` and appends
   `INJECTION_GUARD` before calling `callAI`.
5. The generated note is inserted as safe text/sanitized output.
6. Post-note helpers can offer refine/shorten/clarify, billing suggestions,
   don't-miss review, and parent-facing patient handouts.
7. Users can save/load encounter drafts through the shared encounter system.

## Main Workflows

| Workflow | Frontend | Route | Notes |
|---|---|---|---|
| Live Encounter HPI | `public/js/liveEncounter.js` | `POST /api/generate-hpi-encounter` | Recording/transcript to HPI. |
| Dictation | `public/js/voiceDictation.js` | `POST /api/generate-hpi-dictation` or `POST /api/generate-soap` | Dictated summary to HPI or SOAP. |
| SOAP | `public/js/soap.js` | `POST /api/generate-soap` | Transcript/dictation to SOAP. |
| Sick Visit | `public/js/sickVisit.js` | `POST /api/sick-visit/note` | Chief complaint, transcript/dictation, ROS/PE, diagnosis context. |
| Well Visit | `public/js/wellVisit.js`, `public/js/shadess.js` | `POST /api/well-visit/note`, `POST /api/well-visit/shadess` | Schedule data, ROS/PE, SSHADESS, milestones, vaccines/screenings. |
| Hospital Course | `public/js/hospitalCourse.js` | `POST /api/generate-hospital-course` | Pasted notes/labs to course summary. |
| Chart Review | `public/js/chartReview.js` | `POST /api/generate-chart-review` | Pasted chart content to outpatient review. |
| ED Encounter | `public/js/ed-encounters.js` | `src/routes/edEncounters.js` | Multi-stage ED workflow; see `ed-encounters.md`. |
| Milestones | `public/js/milestones.js` | `POST /api/generate-milestone-narrative`, `POST /api/generate-milestone-summary` | Developmental milestone narratives. |

## User Templates

Settings saves templates/preferences in `user_memories`. The frontend calls
`getUserMemoryContext()` before generation and passes the result as
`physicianMemories`. Server routes wrap that context as low-priority
style/template guidance. `custom` memories and legacy `correction_*` rows are
not injected into prompts.

## Encounter Persistence

Shared save/load behavior lives in `public/js/encounters.js` and
`src/routes/encounters.js`.

- Encounters are scoped by `user_id`.
- Rows expire by `site.auto_delete_days`.
- `idempotency_key` prevents duplicate creates.
- `version` supports optimistic locking when clients send `expected_version`.
- Text fields are encrypted at rest for new writes.

## Patient Education

`attachPatientEducation` adds a Handout panel beside supported note outputs.
`POST /api/patient-education` generates a parent-facing plain-text draft from
the edited clinician note plus optional diagnosis, medication, age, language,
and reading-level context. The clinician remains responsible for review before
sharing.

## Safety Rules

- Do not insert generated clinical output with raw `innerHTML` unless it is
  intentionally sanitized.
- Do not add browser-native `prompt`, `alert`, or `confirm` workflows.
- Do not add inline DOM event handlers.
- Do not reintroduce browser Whisper/browser-local model downloads.
- Do not cache clinical answer text in Redis.
- Keep source transcript/context available for refine actions where relevant.