b53aa34248
Three concurrent themes from this session:
═══════════════════════════════════════════════════════════════════
ED ENCOUNTERS — per-stage cards + consolidate→MDM finalize
═══════════════════════════════════════════════════════════════════
UX redesign per Daniel's feedback ("every stage note should be shown,
if AI is told to modify that particular note then the modified version
is used in final mdm"):
- Each generated stage stays on screen as its own editable card with
its own embedded "Don't Miss" panel. No more single rolling note
element that gets replaced on each generation.
- gatherCurrentNotes() reads contenteditable text from each stage card
before any operation (advance, finalize, persist) so inline edits
flow into the next AI call and the final consolidate.
- Stage badge is now state-accurate. "Stage N (recording)" with yellow
background after Add-more before generation; "Stage N" with gray
after generation. Fixes the bug where the badge flipped to Stage 2
the moment Add-more was clicked.
- Save & Done now runs TWO server-side AI calls in /finalize:
1. edConsolidate (new prompt) → polished single final note that
integrates every stage chronologically (HPI / ROS / PE / ED Course /
A&P with disposition).
2. edFinalize (rewritten with full inline 2023 AMA E/M element
rubric — problems / data / risk definitions, level mapping with
concrete examples) → MDM JSON.
- Two new cards render after finalize: blue-bordered Final Consolidated
Note + green-bordered MDM. Stage cards become read-only.
- partial_data on the saved row now stores {stages, finalNote, mdm,
finalized} so resume re-renders the full state.
Why two-call finalize: a single combined prompt makes the model cut
corners on one task. Two focused calls cost ~2× latency at the very end
of an encounter — acceptable since finalize is a one-time terminal
action, not a per-stage hot path.
Files: public/components/ed-encounter.html, public/js/ed-encounters.js,
src/routes/edEncounters.js, src/utils/prompts.js (edConsolidate added,
edFinalize rewritten).
═══════════════════════════════════════════════════════════════════
EXTENSIONS / PAGERS — visual polish
═══════════════════════════════════════════════════════════════════
Multiple iterations based on Daniel's feedback:
- Layout: align-items:flex-start so action buttons stay pinned top-right
when long numbers wrap (was align-items:center → buttons drifted into
the text area, causing visible overlap).
- Number: word-break:break-all + min-width:0 + font-feature-settings:tnum
so long numbers wrap within their column instead of pushing under the
buttons. Click-to-copy with a 0.55s green flash + ✓ copied badge.
- Phone/pager Font Awesome icon next to the number in the type color —
at-a-glance type signal (replacing an earlier 3px left stripe that
Daniel found visually bulky).
- Name: font-weight 700, font-size 14.5px, color g900, letter-spacing
-0.012em — scan-target headline typography for long lists.
- Alternating subtle backgrounds by index (white vs #fafbfc) so a long
list reads as distinct rows.
- Hover: card lifts 1px with a soft shadow; action buttons fade from
55% to 100% opacity. Cubic-bezier transition on transform.
- Entrance: staggered fade-up animation per card (35ms × index, capped
at 12). prefers-reduced-motion media query disables motion.
- Empty state: 48px FA icon + heading instead of plain gray text.
Files: public/js/extensions.js, public/css/styles.css.
═══════════════════════════════════════════════════════════════════
DOCS REORGANIZATION + APPLICATION-LOGIC DOCS + ADMIN VIEWER
═══════════════════════════════════════════════════════════════════
Document moves (preserving git history via git mv):
BROWSER_WHISPER_SETUP.md → docs/browser-whisper-setup.md
BROWSER_WHISPER_TROUBLESHOOTING.md → docs/browser-whisper-troubleshooting.md
DEVELOPER_GUIDE.md → docs/developer-guide-extended.md
EMBEDDINGS_SETUP.md → docs/embeddings-setup.md
FEATURES_EXPLAINED.md → docs/features-explained.md
IMPROVEMENTS.md → docs/improvements.md
OPENID_SETUP.md → docs/openid-setup.md
TRANSCRIPTION_OPTIONS.md → docs/transcription-options.md
README.md updated with the new paths + a Documentation section that
links to docs/logic/ at the top.
New application-logic doc series (~8,300 lines total) at docs/logic/.
Built with 5 parallel doc-writing agents per Daniel's "use multiple
agents" directive. Each doc explains how a part of the app actually
works — application logic, data flow, design decisions, sacred zones,
how-to-extend recipes — at a depth that lets a new dev (or an AI
assistant) modify the code confidently.
docs/logic/README.md — index + recommended reading order
docs/logic/architecture.md (2166 L) — frontend IIFE pattern, lazy tab
load, backend route convention,
schema, encryption, deployment
docs/logic/clinical-notes.md (1546L) — every note tab + helper trio
docs/logic/bedside-and-calculators.md (1373L) — bedside ES module
pocket + calculators + PE Guide
+ suture selector
docs/logic/auth-admin-learning.md (1281L) — auth (local+OIDC+2FA) +
admin panel + Learning Hub
(Quiz engine logic at sub-detail
only — TODO follow-up)
docs/logic/ai-and-voice.md (1128 L) — callAI 5-provider routing,
prompts, voice/STT, helper trio
docs/logic/ed-encounters.md (821 L) — multi-stage ED + MDM (this
session's worked example)
Admin-only docs viewer:
- New route /api/admin/docs/{tree,file}: recursively walks docs/, returns
the tree as JSON; /file?path=X validates path stays inside docs/ and
renders markdown via marked. Both gated by req.user.role==='admin'.
- New tab "Docs" (book icon) in the sidebar, hidden by default and
revealed in auth.js when user.role==='admin' (same pattern as the
existing Admin and CMS tabs).
- New component public/components/admin-docs.html: split-pane layout
with a tree sidebar + filter input + a markdown reader pane.
- New module public/js/admin-docs.js: lazy-loads the tree on first tab
activation, renders collapsible folders, persists expanded state and
last-opened path via UIState. Server-rendered HTML so no client
markdown parser needed.
- CSS for the viewer (responsive split-pane, code-block styling, table
scrolling, etc.).
- Mounted at /api/admin/docs (NOT /api) — important: mounting a router
with router.use(authMiddleware) at /api accidentally 401s every other
/api/* path (caught and fixed during testing — /api/health was 401'ing).
Files: docs/* (moved + new), README.md, public/components/admin-docs.html
(new), public/js/admin-docs.js (new), src/routes/adminDocs.js (new),
public/index.html (tab + section + script), public/js/auth.js (admin
gate + logout cleanup), public/css/styles.css (viewer styles), server.js
(mount).
═══════════════════════════════════════════════════════════════════
KNOWN GAPS (TODO follow-ups)
═══════════════════════════════════════════════════════════════════
- Learning Hub quiz engine (MCQ / multi-select / T-F scoring + attempt
tracking + progress dashboard) is covered at the architectural level
in docs/logic/auth-admin-learning.md but not drilled into the quiz
data model and scoring flow. Worth a focused follow-up doc.
- ED finalize: if MDM step JSON parse fails, server returns 502 with
the consolidated finalNote in the error payload, but client doesn't
surface the partial result. Add a "MDM failed, retry" affordance.
- No e2e Playwright coverage for ED encounters or the new docs viewer.
9.5 KiB
Pediatric AI Scribe — Improvement Roadmap
A non-technical overview of what the app does today and how it can be taken further.
What the App Does Today
Pediatric AI Scribe is a clinical documentation tool for pediatric physicians. It listens to doctor-patient encounters (or accepts typed/pasted notes) and uses AI to generate structured medical notes — HPIs, SOAP notes, hospital courses, chart reviews, well visit and sick visit documentation.
It also includes pediatric calculators (blood pressure percentiles, BMI, growth charts, bilirubin nomograms, vital signs reference), a Learning Hub for educational content and quizzes, and a full security layer (two-factor authentication, session management, audit logging, single sign-on).
The app runs as a self-hosted web application with a mobile-friendly PWA interface.
Areas for Improvement
1. Visual Growth Charts
Current state: Growth percentiles are displayed as numbers (e.g., "75th percentile, Z-score 0.67").
Improvement: Plot actual WHO/CDC percentile curves (the familiar growth chart lines pediatricians use) with the patient's data point shown on the chart. This would make results immediately interpretable at a glance, matching the paper charts physicians are trained on. Support for plotting multiple visits over time would make it even more useful for tracking growth trends.
2. Blood Pressure Calculator Accuracy
Current state: The BP calculator uses simplified reference values at the 50th height percentile only.
Improvement: Implement the full Rosner quantile spline regression method (the same math used by the Baylor College of Medicine reference calculator). This would give exact BP percentiles adjusted for the patient's actual height, not just an approximation. The regression coefficients are publicly available and can be integrated directly.
3. Multi-Visit Tracking
Current state: Each encounter is independent. There is no way to see a patient's history across visits.
Improvement: Allow physicians to associate notes with a patient identifier (MRN, initials, or a pseudonym) and view previous encounters for that patient. This would enable:
- Growth tracking over time (plot multiple points on growth curves)
- Trend monitoring (weight gain/loss, blood pressure trends)
- Quick access to past notes during follow-up visits
This would need careful design around data retention and privacy since it changes the app from a transient tool to one that stores longitudinal data.
4. EHR Integration
Current state: Notes are copied manually and pasted into the EHR.
Improvement: Direct integration with common EHR systems:
- FHIR API — connect to Epic, Cerner, or other FHIR-enabled EHRs to push notes directly into the patient chart
- HL7 messaging — for institutions using traditional interfaces
- Smart on FHIR — launch the app from within the EHR as an embedded tool
This is the highest-impact improvement for adoption but also the most complex to implement (requires EHR vendor partnerships and institutional approval).
5. Offline Mode
Current state: The app requires an internet connection for AI generation and cloud-based transcription. Browser Whisper works offline for transcription only.
Improvement: Add a local AI model option (e.g., a small medical LLM running on the device or local server) so the entire workflow — record, transcribe, generate note — can happen without any network calls. This would be valuable for:
- Rural clinics with unreliable internet
- Maximum privacy (no data leaves the building)
- Disaster/field medicine scenarios
6. Specialty Expansion
Current state: Focused on general pediatrics with some subspecialty support in chart review.
Improvement: Add specialty-specific note templates and AI prompts for:
- Pediatric cardiology (echo reports, cath summaries)
- Pediatric neurology (EEG reports, seizure logs)
- Neonatology (daily progress notes, discharge summaries)
- Pediatric surgery (operative notes, pre-op assessments)
- Pediatric psychiatry (intake assessments, progress notes)
Each specialty has unique documentation requirements that could be addressed with tailored prompts and input forms.
7. Billing Code Suggestions
Current state: The well visit tab includes some billing code references.
Improvement: Automatically suggest ICD-10 and CPT codes based on the generated note content. After the AI generates a note, it could analyze the diagnoses, procedures, and visit complexity to suggest appropriate billing codes. This saves time on coding and reduces missed charges.
8. Quality Metrics Dashboard
Current state: Admin panel shows basic usage statistics (total API calls, users).
Improvement: Add a dashboard showing:
- Average note generation time by type
- Most-used AI models and their accuracy (based on how often users edit the output)
- Transcription accuracy metrics (if corrections are tracked)
- Usage patterns by time of day and day of week
- Cost tracking across AI providers
This would help administrators optimize model selection and identify training opportunities.
9. Patient Education Materials
Current state: The Learning Hub serves educational content to physicians.
Improvement: Add a patient-facing education module that generates age-appropriate handouts based on the diagnosis. For example, after generating a note for a child with asthma, the app could produce a parent-friendly handout explaining the diagnosis, medications, and when to seek emergency care — in the parent's preferred language.
10. Multi-Language Support
Current state: English only.
Improvement: Add support for:
- Generating notes in other languages (Spanish, French, Arabic, etc.)
- Transcribing encounters conducted in other languages
- Patient education materials in the family's language
- UI translation for non-English-speaking staff
Medical Spanish alone would significantly expand the app's reach in the United States.
11. Voice Commands During Recording
Current state: Recording is continuous — the physician presses start and stop.
Improvement: Add voice command recognition during recording:
- "New section" — marks a section break in the transcript
- "Off the record" — pauses transcription temporarily (for sidebar conversations)
- "Add diagnosis: [condition]" — tags a diagnosis without typing
- "Skip" — ignores the last segment
This would make the recording workflow more natural and reduce post-generation editing.
12. Collaborative Notes
Current state: Single-user editing. Notes are created and edited by one physician.
Improvement: Allow multiple team members to work on the same encounter:
- Attending reviews and co-signs a resident's note
- Nurse adds vital signs and chief complaint before the physician sees the patient
- Specialist adds their consultation note to the same encounter
This mirrors the real workflow in training institutions and group practices.
13. Mobile-Optimized Recording
Current state: Recording works on mobile but stops when the screen locks or the app is backgrounded (browser limitation).
Improvement: Build a native mobile wrapper (using Capacitor or React Native) that can record audio in the background even when the screen is off. This is the single biggest usability improvement for mobile users and removes the most common complaint.
14. Template Library
Current state: Physician memories and corrections provide some personalization.
Improvement: Add a shared template library where physicians can create, share, and browse note templates:
- "My asthma follow-up template"
- "Standard newborn discharge summary"
- "ED laceration repair template"
- Import/export templates between institutions
15. Audit and Compliance Reporting
Current state: Audit logs exist in the database but there is no reporting UI.
Improvement: Add an admin-facing compliance dashboard:
- Who accessed what, when (filterable by user, date, action)
- Export audit logs to CSV/PDF for compliance reviews
- Automated alerts for unusual access patterns
- HIPAA compliance checklist with green/red status indicators
- BAA tracking (which providers have signed BAAs)
Priority Recommendations
If resources are limited, focus on these high-impact improvements first:
| Priority | Improvement | Impact | Effort |
|---|---|---|---|
| 1 | Visual growth charts | High — physicians expect visual curves | Medium |
| 2 | Accurate BP calculator | High — clinical accuracy matters | Medium |
| 3 | Billing code suggestions | High — direct revenue impact | Medium |
| 4 | Multi-language support | High — expands reach significantly | Large |
| 5 | Audit/compliance reporting | Medium — required for institutional adoption | Small |
| 6 | EHR integration (FHIR) | Very high — but requires partnerships | Very large |
What Makes This App Unique
Compared to existing medical scribes and documentation tools:
- Pediatric-specific — prompts, calculators, milestones, and growth charts designed for children, not adapted from adult tools
- Self-hosted — runs on your own infrastructure, not a SaaS that holds your data
- Provider-agnostic — works with any AI provider (swap between them without changing anything)
- Privacy-first — optional fully offline transcription, auto-expiring data, no permanent PHI storage
- Learning system — AI improves its output based on each physician's editing patterns
- All-in-one — documentation, calculators, education, and administration in a single platform