# Pediatric AI Scribe — Developer Guide
**Version:** 6.0 | **Stack:** Node.js / Express / PostgreSQL / Vanilla JS

---

## Table of Contents

1. [Project Overview](#1-project-overview)
2. [Architecture](#2-architecture)
3. [Directory Structure](#3-directory-structure)
4. [Environment Variables](#4-environment-variables)
5. [Database Schema](#5-database-schema)
6. [Authentication System](#6-authentication-system)
7. [Backend API Reference](#7-backend-api-reference)
8. [Frontend Architecture](#8-frontend-architecture)
9. [AI Integration](#9-ai-integration)
10. [Learning Hub & CMS](#10-learning-hub--cms)
11. [Deployment](#11-deployment)
12. [Known Issues & Security Notes](#12-known-issues--security-notes)
13. [Adding New Features](#13-adding-new-features)
14. [Resetting Admin Password via Console](#14-resetting-admin-password-via-console)

---

## 1. Project Overview

Pediatric AI Scribe is a clinical documentation platform for pediatric healthcare providers. It uses AI (via OpenRouter, AWS Bedrock, or Azure OpenAI) to generate:

- HPI notes from live encounter recordings
- SOAP notes from dictation
- Hospital course summaries
- Chart reviews
- Well-visit notes (including SSHADESS, ROS/PE, milestones)
- Sick visit notes
- Learning Hub content (articles, quizzes, clinical pearls, presentations)

**Key design principle:** Single-page application. All tabs are lazy-loaded HTML components (`/public/components/*.html`). JavaScript modules initialize only when their tab is first activated via the `tabChanged` custom event.

---

## 2. Architecture

```
Browser (Vanilla JS + Tiptap)
       |
       | HTTP (JWT Bearer token in Authorization header)
       |
Express.js (Node.js) — server.js
       |
       |— Helmet (CSP, security headers)
       |— CORS (restricted to APP_URL in production)
       |— express-rate-limit (login: 10/15min, register: 5/hr, resend-verify: 3/15min, general: 60/min)
       |— cookie-parser
       |— Routes (/src/routes/)
       |
PostgreSQL (pg driver, no ORM)
       |
       |— users, app_settings, audit_log, saved_encounters
       |— user_memories, learning_*, access_log, api_log
```

### How Requests Flow

1. **Browser** sends HTTP request with `Authorization: Bearer <jwt>` header
2. **Express middleware chain:** Helmet (security headers) → CORS → rate limiter → body parser → logging middleware → route handler
3. **Auth middleware** (`src/middleware/auth.js`) decodes JWT, queries `users` table, attaches `req.user` with `{ id, email, name, role }`
4. **Route handler** processes the request — for AI routes, calls `callAI()` which routes to the configured provider
5. **Database** is accessed via the `pg` driver directly (no ORM). All queries use parameterized placeholders (`$1`, `$2`) to prevent SQL injection
6. **Response** is JSON for API calls, or static files served from `/public`

### AI Providers

Configured via environment variables. The provider is selected at startup in `src/utils/ai.js` using this priority:

1. **AWS Bedrock** — if `AWS_BEDROCK_REGION` is set. HIPAA eligible with BAA. Uses `@aws-sdk/client-bedrock-runtime`. Anthropic models use the native Messages API (`InvokeModel`); all others use the Converse API.
2. **Azure OpenAI** — if `AZURE_OPENAI_ENDPOINT` is set. HIPAA eligible. Uses the OpenAI SDK pointed at your Azure endpoint.
3. **OpenRouter** — default fallback if `OPENROUTER_API_KEY` is set. Routes to 20+ models from various providers. Not HIPAA compliant.

The provider cannot be changed at runtime — it's determined once at startup. To switch providers, update `.env` and restart the container.

### Database Layer

The app uses **raw SQL via the `pg` driver** — no ORM (Sequelize, Prisma, etc.). This is intentional:

- **Simplicity:** Every query is visible and explicit. No magic, no migrations framework, no model definitions to sync.
- **Performance:** No ORM overhead or N+1 query problems.
- **Schema management:** `src/db/database.js` runs `CREATE TABLE IF NOT EXISTS` on startup, plus `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` for migrations. This means the schema is always up-to-date when the app starts.
- **Future ORM migration:** If needed, the queries are standard PostgreSQL and can be wrapped by any ORM. The main work would be defining models and replacing direct `db.get()`/`db.run()` calls.

The `database.js` file exports a helper object (`db`) with convenience methods:
- `db.get(sql, params)` — returns first row or `null`
- `db.all(sql, params)` — returns all rows as array
- `db.run(sql, params)` — executes INSERT/UPDATE/DELETE, returns `{ rowCount }`
- `db.getSetting(key)` / `db.setSetting(key, value)` — shorthand for `app_settings` table

---

## 3. Directory Structure

```
/
├── server.js                   # Express app entry point (route registration, Helmet CSP,
│                               #   rate limiters, static file serving, error handlers)
├── package.json                # Dependencies (~25 production deps, no devDeps)
├── Dockerfile                  # Multi-stage Node.js 20 Alpine build
├── docker-compose.yml          # Production compose (uses Docker Hub image)
├── docker-compose.local.yml    # Local development (builds from source, port 3552)
├── admin-cli.js                # CLI tool for admin tasks (create user, reset password)
├── DEVELOPER_GUIDE.md          # This file
│
├── src/
│   ├── db/
│   │   └── database.js         # DB connection pool (pg.Pool), schema init
│   │                           #   (CREATE TABLE IF NOT EXISTS for all tables),
│   │                           #   column migrations (ALTER TABLE ADD COLUMN IF NOT EXISTS),
│   │                           #   helper methods: db.get(), db.all(), db.run(),
│   │                           #   db.getSetting(), db.setSetting()
│   ├── middleware/
│   │   ├── auth.js             # authMiddleware (JWT decode → req.user),
│   │                           #   adminMiddleware (role === 'admin'),
│   │                           #   moderatorMiddleware (role === 'admin' || 'moderator')
│   │   └── logging.js          # Logs every request to api_log table (method, path, user, IP, duration)
│   ├── routes/
│   │   ├── auth.js             # Login, register, 2FA, password reset, /me
│   │   ├── admin.js            # User management (admin only)
│   │   ├── adminConfig.js      # Site settings, feature flags, AI prompts, models
│   │   ├── encounters.js       # Save/load/delete draft encounters
│   │   ├── memories.js         # User templates (physical exam, ROS, etc.)
│   │   ├── hpi.js              # Generate HPI from encounter/dictation transcript
│   │   ├── soap.js             # Generate SOAP note
│   │   ├── hospitalCourse.js   # Generate hospital course summary
│   │   ├── chartReview.js      # Generate outpatient chart review
│   │   ├── milestones.js       # Generate developmental milestone narrative
│   │   ├── wellVisit.js        # Well-visit note generation (ROS/PE/ICD-10)
│   │   ├── sickVisit.js        # Sick visit note generation
│   │   ├── refine.js           # Refine/shorten any generated document
│   │   ├── transcribe.js       # Whisper audio transcription
│   │   ├── tts.js              # Text-to-speech (if configured)
│   │   ├── nextcloud.js        # Nextcloud WebDAV connect/export/disconnect
│   │   ├── learningHub.js      # User-facing: feed, content, quiz submission
│   │   ├── learningAdmin.js    # CMS: categories, content, questions CRUD
│   │   ├── learningAI.js       # AI generation for Learning Hub content
│   │   └── logs.js             # Usage/audit/API/access logs + client error
│   └── utils/
│       ├── ai.js               # callAI(messages, options) — routes to OpenRouter/Bedrock/Azure.
│       │                       #   Handles Anthropic InvokeModel (Messages API) vs Converse API,
│       │                       #   thinking block extraction, fallback model retry, duration tracking.
│       ├── models.js           # OPENROUTER_MODELS[], BEDROCK_MODELS[], AZURE_MODELS[]
│       │                       #   Each model: { id, name, cost, tag, category, bedrockId, maxOut, regions }
│       │                       #   getBedrockModelId() maps app IDs to Bedrock/inference profile IDs.
│       │                       #   getAvailableModels() filters by region. getAvailableModelsWithOverrides()
│       │                       #   applies admin-disabled/custom models from DB.
│       ├── prompts.js          # Default prompt templates for every AI route. Loaded on startup,
│       │                       #   then overridden by DB values (app_settings: 'prompt.*' keys).
│       │                       #   PROMPTS.get('key') returns the DB override or default.
│       ├── config.js           # App configuration helpers
│       └── logger.js           # Winston logger (file + console, JSON format)
│
├── public/
│   ├── index.html              # Single HTML shell, loads all components
│   ├── 404.html                # Custom 404 page
│   ├── css/
│   │   └── styles.css          # All CSS (single file, ~750 lines)
│   ├── js/
│   │   ├── app.js              # Core: tab switching via data-tab buttons, loadComponent()
│   │   │                       #   fetches HTML from /components/, global helpers (showToast,
│   │   │                       #   showLoading, getAuthHeaders, getSelectedModel, etc.)
│   │   ├── auth.js             # Login/register/forgot-password forms, JWT storage in
│   │   │                       #   localStorage ('ped_scribe_token'), enterApp()/clearSession(),
│   │   │                       #   resend verification link handler, 2FA code input
│   │   ├── admin.js            # Admin panel: user management, site settings, SMTP config,
│   │   │                       #   model enable/disable, prompt editor, announcement banner
│   │   ├── liveEncounter.js    # MediaRecorder → Whisper transcription → AI HPI generation.
│   │   │                       #   Handles start/stop recording, timer, save/load encounters
│   │   ├── voiceDictation.js   # Web Speech API (real-time) or Whisper (recorded) dictation
│   │   ├── hospitalCourse.js   # Paste/dictate hospital course → AI summary
│   │   ├── chartReview.js      # Paste/dictate chart data → AI outpatient review
│   │   ├── soap.js             # Paste/dictate → AI SOAP note
│   │   ├── milestones.js       # Age-based milestone checklist → AI narrative
│   │   ├── wellVisit.js        # Well Visit guide: vaccine schedule display, age calculator
│   │   ├── shadess.js          # SSHADESS psychosocial form + ROS/PE checkboxes → AI note
│   │   ├── sickVisit.js        # Chief complaint + HPI → AI sick visit SOAP
│   │   ├── nextcloud.js        # Nextcloud WebDAV connect/disconnect/export settings UI
│   │   ├── encounters.js       # Save/load/delete encounter drafts (shared across all tabs)
│   │   ├── memories.js         # User template CRUD (physical exam defaults, ROS, etc.)
│   │   ├── learningHub.js      # Learning Hub (user feed, content viewer, quiz engine) +
│   │   │                       #   CMS (category CRUD, content editor with Tiptap, question
│   │   │                       #   builder, AI generation panel, Nextcloud file picker,
│   │   │                       #   slide preview modal). Single file, ~1400 lines.
│   │   ├── milestonesData.js   # Static milestone data by age group (2mo → 6yr)
│   │   └── pediatricScheduleData.js  # CDC vaccine schedule data + catch-up schedule
│   ├── components/             # Lazy-loaded tab HTML (injected by loadComponent)
│   │   ├── encounter.html      ├── dictation.html   ├── hospital.html
│   │   ├── chart.html          ├── soap.html        ├── wellvisit.html
│   │   ├── sickvisit.html      ├── vaxschedule.html ├── catchup.html
│   │   ├── learning.html       ├── cms.html         ├── admin.html
│   │   └── settings.html
│   └── vendor/
│       └── tiptap.bundle.js    # Tiptap 2 + extensions (esbuild bundle, self-hosted)
```

---

## 4. Environment Variables

Set in `.env` file (copy `.env.example` to get started):

```bash
# ── Required ──────────────────────────────────────────────────
DATABASE_URL=postgresql://user:<password>@host:5432/dbname
JWT_SECRET=change-this-to-a-random-64-char-string

# ── AI Provider (choose one or let it default to OpenRouter) ──
OPENROUTER_API_KEY=sk-or-...         # Default provider
# OR
AZURE_OPENAI_ENDPOINT=https://...    # Azure (HIPAA eligible)
AZURE_OPENAI_API_KEY=...
AZURE_DEPLOYMENT_NAME=gpt-4o-mini
AZURE_OPENAI_API_VERSION=2024-08-01-preview
# OR
AWS_BEDROCK_REGION=us-east-1         # AWS Bedrock (HIPAA eligible)
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

# ── Optional ──────────────────────────────────────────────────
OPENAI_API_KEY=sk-...                # For Whisper transcription only
APP_URL=https://yourdomain.com       # Enables secure CORS + Secure cookies
NODE_ENV=production                  # Enables production optimizations
PORT=3000                            # Default: 3000

# ── Email (for password reset, registration verification) ──────
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASS=...
SMTP_FROM=Pediatric AI Scribe <noreply@example.com>
```

**Note:** If no SMTP is configured, registration auto-verifies and password reset won't work. Configure SMTP or use the console reset method (see Section 14).

---

## 5. Database Schema

All tables are created automatically on first run by `src/db/database.js`. The file runs `CREATE TABLE IF NOT EXISTS` for every table, followed by `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` migrations for upgrades.

### Core Tables

#### `users`
| Column | Type | Notes |
|--------|------|-------|
| id | SERIAL PK | |
| email | TEXT UNIQUE | Lowercase |
| password | TEXT | bcrypt hash (cost 12) |
| name | TEXT | Display name |
| role | TEXT | `'user'` \| `'moderator'` \| `'admin'` |
| totp_enabled | BOOLEAN | 2FA status |
| totp_secret | TEXT | TOTP secret (base32) |
| disabled | BOOLEAN | Soft disable |
| email_verified | BOOLEAN | |
| verify_token / verify_expires | TEXT / BIGINT | Email verification |
| reset_token / reset_expires | TEXT / BIGINT | Password reset |
| nextcloud_url / nextcloud_user / nextcloud_token / nextcloud_folder | TEXT | Nextcloud integration |
| webdav_learning_path | TEXT | Default WebDAV path for Learning Hub file picker |
| created_at | TIMESTAMPTZ | |

#### `app_settings`
Key-value store for all site configuration. Read via `db.getSetting(key)`, written via admin panel or direct DB.

Important keys:
- `registration_enabled` — `'true'` / `'false'`
- `announcement.enabled` / `announcement.text` / `announcement.type`
- `smtp.*` — SMTP config (overrides env vars)
- `ai.prompt.*` — AI prompt overrides
- `model.*` — enabled/disabled models

#### `saved_encounters`
Draft encounters (7-day auto-expiry). Columns: `label`, `enc_type`, `transcript`, `generated_note`, `partial_data` (JSON), `status`, `expires_at`.

#### `user_memories`
User templates fed into AI generation. `category` is one of: `physical_exam`, `ros`, `encounter_format`, `family_history`, `assessment_plan`, `custom`.

### Learning Hub Tables

#### `learning_categories`
Simple category list with `name`, `slug`, `sort_order`.

#### `learning_content`
Articles, quizzes, pearls, presentations. Key columns: `title`, `slug`, `body` (HTML for articles/pearls/quizzes; Marp markdown for presentations), `content_type` (`article` | `quiz` | `pearl` | `presentation`), `published`, `author_id`.

#### `learning_questions`
Quiz questions linked to `learning_content`. `question_type`: `mcq` | `true_false` | `multi`. `explanation` = general explanation shown after answering.

#### `learning_options`
Answer options for quiz questions. `is_correct: boolean`, `explanation` = shown when this wrong option is chosen.

#### `learning_progress`
Quiz attempt scores per user per content item.

---

## 6. Authentication System

**Current implementation: JWT in localStorage**

### Flow
1. `POST /api/auth/login` → returns `{ success, token, user }`
2. Frontend stores token in `localStorage` as `ped_scribe_token` and in `window.AUTH_TOKEN`
3. All API calls include `Authorization: Bearer <token>` header via `getAuthHeaders()`
4. `src/middleware/auth.js` validates the Bearer token, attaches `req.user`
5. Logout: `clearSession()` removes token from localStorage (client-side only)

### Token
- Signed with `JWT_SECRET` env var
- 7-day expiry
- Payload: `{ userId: number }`

### Roles
- `user` — standard access (clinical tools only)
- `moderator` — can create/edit Learning Hub content
- `admin` — full access including user management and site settings

### Middleware
- `authMiddleware` — validates JWT, populates `req.user`
- `adminMiddleware` — run after auth, requires `role === 'admin'`
- `moderatorMiddleware` — run after auth, requires `role === 'admin' OR 'moderator'`

### 2FA
Uses TOTP (speakeasy). If enabled, login returns `{ requires2FA: true }` and the client must POST the TOTP code to complete login.

### Session Check on Page Load (auth.js)
```javascript
var savedToken = localStorage.getItem('ped_scribe_token');
if (savedToken) {
  fetch('/api/auth/me', { headers: { 'Authorization': 'Bearer ' + savedToken } })
  .then(/* if ok → enterApp(), else → clearSession() */);
}
```
The `has-session` CSS class on `<html>` hides the auth screen immediately when a localStorage token exists, preventing a white flash.

---

## 7. Backend API Reference

All routes are prefixed `/api`. Routes requiring auth are marked (A). Admin-only: (ADM). Moderator+: (MOD).

### Auth — `/api/auth/`
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/login` | — | Email + password login. Returns `{ token, user }` |
| POST | `/register` | — | Create account (checks `registration_enabled` setting) |
| GET | `/me` | A | Returns current user object |
| POST | `/logout` | — | Clears server-side state (currently no-op, kept for future) |
| POST | `/setup-2fa` | A | Generates TOTP secret + QR code |
| POST | `/verify-2fa` | A | Confirms TOTP code, enables 2FA |
| POST | `/disable-2fa` | A | Disables 2FA (requires password) |
| POST | `/forgot-password` | — | Sends reset email |
| POST | `/reset-password` | — | Sets new password via reset token |
| GET | `/registration-status` | — | Returns `{ registrationEnabled: bool }` |
| GET | `/verify-email` | — | Verifies email via token in query string |

### Clinical — AI Generation
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/generate-hpi-encounter` | A | HPI from live encounter transcript |
| POST | `/generate-hpi-dictation` | A | HPI from dictation |
| POST | `/generate-soap` | A | SOAP note |
| POST | `/generate-hospital-course` | A | Hospital course summary |
| POST | `/generate-chart-review` | A | Chart review |
| POST | `/generate-milestone-narrative` | A | Milestone narrative |
| POST | `/generate-milestone-summary` | A | 3-sentence milestone summary |
| POST | `/well-visit/note` | A | Full well-visit note |
| POST | `/sick-visit/note` | A | Sick visit SOAP |
| POST | `/transcribe` | A | Whisper audio → text (multipart/form-data, field: `audio`) |
| POST | `/refine` | A | Refine existing document |
| POST | `/shorten` | A | Shorten existing document |
| POST | `/clarify` | A | Find missing info in a document |

### Encounters (Save/Load)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/encounters` | A | List user's saved encounters |
| POST | `/encounters` | A | Save/update encounter draft |
| DELETE | `/encounters/:id` | A | Delete a draft |

### User Templates
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/memories` | A | List user's templates |
| POST | `/memories` | A | Create template |
| PUT | `/memories/:id` | A | Update template |
| DELETE | `/memories/:id` | A | Delete template |
| GET | `/memories/context` | A | Returns templates formatted for AI injection |

### Nextcloud
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/nextcloud/connect` | A | Connect + test Nextcloud credentials |
| POST | `/nextcloud/export` | A | Export text file to Nextcloud |
| POST | `/nextcloud/disconnect` | A | Remove Nextcloud credentials |

### Learning Hub (User-Facing)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/learning/categories` | A | List categories |
| GET | `/learning/feed` | A | Paginated published content |
| GET | `/learning/category/:slug` | A | Content by category |
| GET | `/learning/content/:slug` | A | Single content item + questions |
| POST | `/learning/submit-quiz` | A | Submit quiz answers, returns scored results |
| GET | `/learning/search` | A | Full-text search |

### Learning Hub CMS (Moderator+)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/admin/learning/categories` | MOD | All categories with counts |
| POST | `/admin/learning/categories` | MOD | Create category |
| PUT | `/admin/learning/categories/:id` | MOD | Update category |
| DELETE | `/admin/learning/categories/:id` | MOD | Delete category |
| GET | `/admin/learning/content` | MOD | All content (including drafts) |
| GET | `/admin/learning/content/:id` | MOD | Single item with questions |
| POST | `/admin/learning/content` | MOD | Create content |
| PUT | `/admin/learning/content/:id` | MOD | Update content |
| DELETE | `/admin/learning/content/:id` | MOD | Delete content + questions |
| POST | `/admin/learning/content/:id/questions` | MOD | Add question to content |
| PUT | `/admin/learning/questions/:id` | MOD | Update question + options |
| DELETE | `/admin/learning/questions/:id` | MOD | Delete question |
| GET | `/admin/learning/stats` | MOD | Dashboard stats |

### Learning Hub AI (Moderator+)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/admin/learning/ai-generate` | MOD | Generate content from topic/file/Nextcloud (multipart/form-data) |
| POST | `/admin/learning/ai-refine` | MOD | Refine body HTML with instructions |
| POST | `/admin/learning/preview-slides` | MOD | Render Marp markdown → `{ css, slides[] }` for preview |
| POST | `/admin/learning/generate-pptx` | MOD | Marp markdown → `.pptx` download (pptxgenjs) |
| GET | `/admin/learning/webdav-browse` | MOD | PROPFIND Nextcloud folder |
| POST | `/admin/learning/webdav-path` | MOD | Save user's default WebDAV path |

### Admin (Admin Only)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/admin/users` | ADM | List all users |
| POST | `/admin/users` | ADM | Create user |
| PUT | `/admin/users/:id` | ADM | Update user (role, disable) |
| DELETE | `/admin/users/:id` | ADM | Delete user |
| GET/POST | `/admin/config/*` | ADM | Site settings (announcement, SMTP, models, prompts, etc.) |

### Logs & Health
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/health` | — | Returns `{ status: 'running', version, provider }` |
| GET | `/models` | — | Returns available AI models list |
| POST | `/logs/client-error` | — | Client-side error logging (public) |
| GET | `/logs/usage` | ADM | API usage log |
| GET | `/logs/audit` | ADM | Audit log |

---

## 8. Frontend Architecture

### Tab Loading (Lazy Components)
Every tab's HTML lives in `/public/components/<tabname>.html`. When a tab button is clicked, `loadComponent()` in `app.js` fetches the HTML, injects it into the tab section, then fires `tabChanged` event.

```javascript
// app.js
document.dispatchEvent(new CustomEvent('tabChanged', { detail: { tab: tabName } }));
```

**Critical pattern:** Every JS module that needs to access tab DOM elements MUST listen for `tabChanged`, not `DOMContentLoaded`:

```javascript
// Correct pattern for every tab module
(function() {
  var _inited = false;
  document.addEventListener('tabChanged', function(e) {
    if (e.detail.tab !== 'myTab' || _inited) return;
    _inited = true;
    // Now safe to querySelector elements — they exist in the DOM
    var btn = document.getElementById('my-btn');
    btn.addEventListener('click', ...);
  });
})();
```

If you use `DOMContentLoaded` instead, the elements won't exist yet (they're loaded async) and you'll get `null.addEventListener` errors.

### Global Functions (defined in app.js)
These are available everywhere — no imports needed:

| Function | Description |
|----------|-------------|
| `getAuthHeaders()` | Returns `{ 'Content-Type': 'application/json', 'Authorization': 'Bearer <token>' }` |
| `getSelectedModel()` | Returns model ID from active tab's selector or global selector |
| `showLoading(msg)` | Shows full-screen loading overlay |
| `hideLoading()` | Hides loading overlay |
| `showToast(msg, type)` | Shows toast notification. `type`: `'success'`\|`'error'`\|`'info'`\|`'warning'` |
| `setOutputText(el, text)` | Sets text on contenteditable div, converting `\n` to `<br>` |
| `transcribeAudio(blob)` | Sends audio blob to `/api/transcribe`, returns `{ success, text }` |
| `createSpeechRecognition()` | Returns Web Speech API recognition instance |
| `createTimer(el)` | Returns timer object with `.start()` / `.stop()` |

### Rich Text Editor (Tiptap)
The body editor in the CMS uses Tiptap 2 (headless, no styling framework). The bundle is pre-built at `/public/vendor/tiptap.bundle.js` and exposes `window.Tiptap = { Editor, StarterKit, Link, Underline, TextStyle, Color }`.

To rebuild the bundle after updating Tiptap packages:
```bash
cat > tiptap-entry.js << 'EOF'
import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import Link from '@tiptap/extension-link';
import Underline from '@tiptap/extension-underline';
import { TextStyle } from '@tiptap/extension-text-style';
import { Color } from '@tiptap/extension-color';
window.Tiptap = { Editor, StarterKit, Link, Underline, TextStyle, Color };
EOF
npx esbuild tiptap-entry.js --bundle --format=iife --minify --outfile=public/vendor/tiptap.bundle.js
rm tiptap-entry.js
```

---

## 9. AI Integration

### `src/utils/ai.js` — `callAI(messages, options)`

The single function used by all routes. It routes to the correct provider automatically.

```javascript
const { callAI } = require('../utils/ai');

const result = await callAI(
  [{ role: 'user', content: 'Generate a note...' }],
  {
    model: 'google/gemini-2.5-flash', // optional, uses default if omitted
    temperature: 0.3,                 // optional, default 0.3
    maxTokens: 4000                   // optional, default 4000
  }
);

// result = { success: true, content: '...', model: '...', provider: '...', duration: ms }
```

### Bedrock Model Notes

**Inference Profiles:** Most newer models (Anthropic vendor model 4.x, Meta Llama 4, DeepSeek R1, Amazon Nova, Writer) require cross-region inference profiles. These use a `us.` prefix on the model ID (e.g. `us.anthropic.agent-config-sonnet-4-6`). Direct model IDs will return "on-demand throughput not supported" errors.

**Max Output Tokens:** Some models have low output limits (Cohere Command R/R+: 4096, AI21 Jamba: 4096). The `maxOut` field in `models.js` auto-clamps `maxTokens` in `callBedrock()`.

**JSON Sanitization:** Some models (notably vendor model Sonnet 4.6, Opus 4.6) output literal newline characters inside JSON string values. `learningAI.js` includes a `sanitizeJsonString()` function that escapes these before parsing.

### Prompt System
Prompts are defined in `src/utils/prompts.js`. Admins can override any prompt via the Admin panel (`/admin/config/prompts`). Overrides are stored in `app_settings` table and loaded into memory on startup (with 3s grace period for DB readiness).

To add a new prompt:
1. Add a default in `prompts.js`
2. Use `PROMPTS.get('your-prompt-key')` in your route
3. The admin panel will auto-discover it

### AI Generate for Learning Hub
The `src/routes/learningAI.js` file handles all Learning Hub AI generation.

**For presentations:** The AI is prompted to return raw Marp markdown (not JSON). The response is stored in the `body` column. Detection: `content_type === 'presentation'`.

**For articles/quizzes/pearls:** The AI returns JSON:
```json
{
  "title": "...",
  "subject": "...",
  "body": "<p>HTML content</p>",
  "questions": [
    {
      "question_text": "...",
      "question_type": "mcq",
      "explanation": "...",
      "options": [
        { "option_text": "...", "is_correct": true, "explanation": "..." }
      ]
    }
  ]
}
```

---

## 10. Learning Hub & CMS

### Content Types
| Type | Body format | Has questions |
|------|-------------|---------------|
| `article` | HTML (Tiptap) | Optional |
| `quiz` | HTML (brief intro) | Always |
| `pearl` | HTML | Optional |
| `presentation` | Marp markdown | Never |

### Quiz Question Types
- `mcq` — Single choice (radio buttons), 4 options, 1 correct
- `true_false` — 2 options: "True" / "False", 1 correct
- `multi` — Multiple select (checkboxes), scoring: all correct chosen AND no incorrect chosen

### PPTX Generation
`POST /admin/learning/generate-pptx` parses Marp markdown (splits on `---`), extracts `#` headings as slide titles, bullet points as content, and uses `pptxgenjs` to create a real `.pptx`. **No Chromium required** — pure Node.js.

### Slide Preview
`POST /admin/learning/preview-slides` uses `@marp-team/marp-core` to render Marp markdown to HTML, then extracts individual `<section>` elements. Returns `{ css, slides[] }`. The frontend renders these one at a time in a full-screen modal with arrow key + swipe navigation.

### Content Display
In the Learning Hub viewer, content `body` is rendered via `sanitizeHtml()` in `learningHub.js`. This function allows a safe subset of HTML tags only (no `<script>`, no `on*` attributes, no `style` attributes except `class`).

---

## 11. Deployment

### Local Development
```bash
cp .env.example .env   # Fill in your credentials
docker compose -f docker-compose.local.yml build --no-cache
docker compose -f docker-compose.local.yml up -d
# App runs at http://localhost:3552
```

### Logs & Debugging

**View container logs (live):**
```bash
docker logs -f pediatric-ai-scribe
```

**View last N lines:**
```bash
docker logs --tail 50 pediatric-ai-scribe
```

**Filter for specific issues:**
```bash
# AI/Bedrock errors
docker logs pediatric-ai-scribe 2>&1 | grep -i "Bedrock\|LearningAI\|callAI"

# Auth errors
docker logs pediatric-ai-scribe 2>&1 | grep -i "Auth\|login\|verify"

# All errors
docker logs pediatric-ai-scribe 2>&1 | grep -i "error\|ERR\|fail"
```

**Key log prefixes:**
| Prefix | Source |
|--------|--------|
| `[Bedrock] Model:` | AI response metadata (block types, stop reason) |
| `[LearningAI]` | JSON parse failures with raw output context |
| `[Auth]` | Login, registration, verification events |
| `[TTS]` | Text-to-speech generation |
| `🤖 Provider:` | Startup: which AI provider is active |
| `✅ AWS Bedrock:` | Startup: Bedrock configured successfully |

**Database logs (PostgreSQL):**
```bash
docker logs pedscribe-db
```

### Production (Docker Hub image)
```bash
# docker-compose.yml (production)
services:
  app:
    image: danielonyejesi/pediatric-ai-scribe-v3:latest
    ports: ["3000:3000"]
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: pedscribe
      POSTGRES_USER: pedscribe
      POSTGRES_PASSWORD: your_secure_password
    volumes:
      - pgdata:/var/lib/postgresql/data
```

### Docker Hub
Repository: `danielonyejesi/pediatric-ai-scribe-v3`

Tags use versioned format: `v5.0`, `v5.1`, etc. Production should always pin to a specific tag.

### Git Repository
Repository: `ifedan-ed/pediatric-ai-scribe-v3` (private)

### Build & Push Process
```bash
# 1. Test locally first
docker compose -f docker-compose.local.yml build --no-cache
docker compose -f docker-compose.local.yml up -d
# Test at http://localhost:3552

# 2. When ready, tag and push to Docker Hub
docker tag scribe-pediatric-scribe:latest danielonyejesi/pediatric-ai-scribe-v3:v5.x
docker push danielonyejesi/pediatric-ai-scribe-v3:v5.x

# 3. Update production docker-compose.yml to use new tag
```

---

## 12. Known Issues & Security Notes

### Active Known Issues
1. **`nodemailer` HIGH vulnerability** — v6.9.x has an email domain interpretation conflict. Upgrade to `^6.10.0` when available.
2. **`unsafe-inline` in CSP** — `scriptSrc` includes `'unsafe-inline'` to support inline event handlers in HTML components. Should migrate to event listeners and remove this directive.
3. **JWT in localStorage** — Tokens stored in `localStorage` are readable by JavaScript and therefore vulnerable to XSS attacks. A future migration to `httpOnly` cookies would eliminate this risk. See notes in auth.js and Section 6.
4. **`window.prompt()` in `runAiRefineBody`** — Uses browser native prompt, which can be blocked in certain contexts. Should be replaced with an inline input field.
5. **`webdav-learning-path` endpoint** — Sits behind `moderatorMiddleware` but is a user preference that non-moderator users might reasonably need. Consider moving to plain `authMiddleware`.

### Security Hardening Already In Place
- Helmet.js with custom CSP (no external script sources)
- CORS restricted to `APP_URL` in production
- Rate limiting on login (10/15min), register (5/hr), forgot-password (5/hr), resend-verification (3/15min), general API (60/min)
- bcrypt cost 12 for password hashing
- JWT with 7-day expiry
- SQL injection protection: all queries use parameterized `?` / `$1` placeholders
- Dynamic table names validated against an explicit allowlist (`ALLOWED_SLUG_TABLES`)
- User input in HTML contexts goes through `sanitizeHtml()` (tag allowlist, strips `on*` attributes)
- File upload MIME type validated by extension + content type
- Admin/moderator route protection via middleware

---

## 13. Adding New Features

### Adding a New Clinical Tab
1. Create `public/components/mytab.html` with the tab's UI
2. Add to `index.html`:
   - Tab button: `<button class="tab-btn" data-tab="mytab">...</button>`
   - Tab section: `<section id="mytab-tab" class="tab-content" data-component="mytab"></section>`
   - Script tag: `<script defer src="/js/myTab.js"></script>`
3. Create `public/js/myTab.js`:
   ```javascript
   (function() {
     var _inited = false;
     document.addEventListener('tabChanged', function(e) {
       if (e.detail.tab !== 'mytab' || _inited) return;
       _inited = true;
       // Wire up DOM elements here
     });
   })();
   ```
4. Create `src/routes/myTab.js` with the API route
5. Register in `server.js`: `app.use('/api', require('./src/routes/myTab'));`

### Adding a New AI Prompt
1. In `src/utils/prompts.js`, add to the defaults object:
   ```javascript
   'my-prompt': 'You are a pediatric physician...'
   ```
2. In your route: `const prompt = PROMPTS.get('my-prompt') + '\n\n' + userInput`
3. The admin panel will show an editor for this prompt automatically.

### Adding a New Learning Hub Content Type
1. Add the new type to the `content_type` selector in `cms.html`
2. Handle it in `toggleEditorMode()` in `learningHub.js`
3. Add to the type detection in `buildGeneratePrompt()` in `learningAI.js`
4. Handle rendering in `learningHub.js` `loadContent()` function
5. No DB migration needed — `content_type` is a free-text column

---

## 14. Resetting Admin Password via Console

If you lose admin access and have no SMTP for password reset, use the Docker console:

```bash
# Step 1: Get a shell in the running app container
docker exec -it pediatric-ai-scribe sh

# Step 2: Open Node.js REPL
node

# Step 3: Hash your new password
const bcrypt = require('bcryptjs');
const hash = await bcrypt.hash('YourNewPassword123!', 12);
console.log(hash);
// Copy the hash output

# Step 4: Exit Node REPL
.exit

# Step 5: Open a DB shell
# (Exit app container first, then:)
docker exec -it pedscribe-db psql $POSTGRES_USER $POSTGRES_DB

# Step 6: Update the password (paste the hash)
UPDATE users
SET password = '$2a$12$...(your-hash-here)...'
WHERE email = 'your-admin@email.com';

# Verify:
SELECT email, left(password, 7) as hash_prefix FROM users WHERE email = 'your-admin@email.com';

# Exit:
\q
```

### Enabling Registration via Console
```bash
docker exec -it pedscribe-db psql $POSTGRES_USER $POSTGRES_DB
UPDATE app_settings SET value = 'true' WHERE key = 'registration_enabled';
\q
```

### Creating First Admin User (empty database)
The first user to register is automatically made admin. Enable registration, register, then disable registration again.

Or directly:
```bash
# In the Node REPL inside the app container:
const bcrypt = require('bcryptjs');
const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const hash = await bcrypt.hash('YourPassword', 12);
await pool.query(
  "INSERT INTO users (email, password, name, role, email_verified) VALUES ($1, $2, $3, 'admin', true)",
  ['admin@yourdomain.com', hash, 'Admin']
);
pool.end();
```

---

## 15. Version History (Recent)

| Tag | Key changes |
|-----|-------------|
| v3.19 | Login flash fixed (auth screen hidden by CSS default); presentation quiz option; feed labels corrected |
| v3.18 | pdf-parse downgraded to v1.1.1; WebDAV selection UX fixed; topic context on upload/WebDAV tabs; inline refine bar replaces window.prompt(); CSP: removed unsafe-inline (all onclick= converted to data-action delegation); webdav-path moved to /api/user/webdav-path (auth-only) |
| v3.17 | AI panel context-aware options fixed (style.display replaces classList — CSS cascade bug); quiz card redesign |
| v3.16 | DEVELOPER_GUIDE.md created |
| v3.15 | Auth reverted to localStorage tokens; slide preview padding fixed |
| v3.14 | AI panel context-aware options (word count, slide count, quiz toggle); delete wording per type |
| v3.13 | Delete confirm inline bar CSS bug fixed; slide preview in-page modal (arrow/swipe nav); Marp textarea placeholder |
| v3.12 | Delete inline confirm bar; lighter login screen; Presentation type (Marp + pptxgenjs PPTX) |
| v3.11 | AI content generation for Learning Hub (topic/file/Nextcloud, pdf-parse, pptxgenjs) |
| v3.10 | Custom 404 page; server returns 404 for unknown paths |
| v3.8  | Quill replaced with Tiptap 2 (self-hosted bundle, inline link bar) |
| v5.0  | Resend verification link on login + rate limit (3/15min) |
| v5.1–v5.4 | Bedrock model fixes: inference profiles, region filtering, thinking block handling |
| v5.5  | Comprehensive Bedrock fix: all us. prefix IDs, maxTokens clamping |
| v5.6  | Re-add Qwen3 235B |
| v5.7  | Remove Opus 4.6 (JSON issues) |
| v5.8  | Fix JSON parse: sanitize literal newlines in strings; re-add Opus 4.6 |
| v5.9  | Re-add Opus 4.6 with sanitizer; updated DEVELOPER_GUIDE |
| v6.0  | Increase PDF/doc context to 50k chars; maxTokens ceiling to 8k |

## 16. Current Docker Image

**Latest stable:** `danielonyejesi/pediatric-ai-scribe-v3:v6.0`

```bash
docker pull danielonyejesi/pediatric-ai-scribe-v3:v6.0
```

---

## 17. PDF & Document Uploads

### How It Works

The Learning Hub AI generator accepts documents via two paths — both produce the same result:

1. **Direct upload** — user selects a file from their computer (up to 20 MB)
2. **Nextcloud WebDAV** — user browses their Nextcloud and picks a file

The flow:
1. `extractText()` in `learningAI.js` detects file type by MIME/extension
2. **PDF:** `pdf-parse` v1.1.1 extracts all text pages into a single string
3. **PPTX/DOCX/TXT:** extracted via appropriate parser or read as UTF-8
4. Text is truncated to **50,000 characters** (~25-30 pages) and sent as context in the AI prompt
5. AI generates structured content (title, HTML body, quiz questions) from the full context

### Supported File Types
| Extension | Handler | Notes |
|-----------|---------|-------|
| `.pdf` | `pdf-parse` | Extracts text only — images, charts, tables are lost |
| `.pptx` | Text extraction from slides | Slide text only |
| `.docx` | Text extraction | Body text only |
| `.txt`, `.md`, `.csv` | Read as UTF-8 | Full content preserved |

### Limits
- **Upload size:** 20 MB (`multer` limit in `learningAI.js`)
- **Context sent to AI:** 50,000 characters (configurable in `buildGeneratePrompt()`)
- **AI response tokens:** 8,000 max (ceiling — model stops when done)

### Why No Vector Embeddings / RAG

Embeddings and RAG (Retrieval Augmented Generation) are unnecessary for this use case:

- **Single document → single generation** — the full text fits in the model's context window
- Most Bedrock models support 100K-200K token inputs — 50,000 chars is well within that
- Embeddings would add complexity (pgvector, chunking, retrieval pipeline) with no benefit

If you later need to **search across hundreds of stored documents** or handle 200+ page PDFs, then consider pgvector + chunked retrieval. For now, the direct approach is correct.

---

## 18. Scalability

### Current Architecture (Single Instance)
The app runs as a single Node.js process. This is fine for a team/department deployment (tens to hundreds of concurrent users).

### What Scales Well Already
- **Stateless JWT auth** — no server-side session store; any instance can validate any token
- **PostgreSQL** — handles concurrent connections well; supports read replicas
- **Lazy-loaded component HTML** — reduces initial page size; tabs load on demand
- **AI calls** — fully async; expensive calls don't block other requests

### Bottlenecks to Address Before Horizontal Scaling

| Issue | Current | Fix for multi-instance |
|-------|---------|----------------------|
| Rate limiting | In-memory (per process) | Replace with Redis (`rate-limit-redis`) |
| File uploads | `multer` in RAM | Route uploads to S3/object storage |
| Scheduled cleanup | `setTimeout` in server.js | Use a dedicated cron job or DB-scheduled task |

### How to Scale Horizontally
```yaml
# docker-compose with 3 app replicas + nginx load balancer
services:
  app:
    image: danielonyejesi/pediatric-ai-scribe-v3:latest
    deploy:
      replicas: 3
    environment:
      DATABASE_URL: postgresql://...  # shared external Postgres
      REDIS_URL: redis://redis:6379   # add when rate-limit-redis is wired
  nginx:
    image: nginx:alpine
    # upstream: round-robin across app replicas
  redis:
    image: redis:7-alpine
  postgres:
    image: postgres:16-alpine
```

Cloud deployment options (all work with the current Docker image):
- **AWS ECS/Fargate** — managed containers, easy auto-scaling
- **Railway / Render / Fly.io** — simple push-to-deploy with Docker
- **Kubernetes** — full control, overkill for most deployments

---

## 19. Security Architecture — localStorage vs httpOnly Cookies

The app stores JWT tokens in `localStorage`. This is a deliberate choice appropriate for this scale. The key security facts:

**Current protections in place (more important than storage location):**
- `Content-Security-Policy: script-src 'self'` — blocks all external scripts and inline JS (v3.18)
- Input sanitization via `sanitizeHtml()` allowlist on all user-generated HTML
- All 26 `onclick=` inline event handlers removed (v3.18) — reduces XSS surface
- Rate limiting on auth endpoints
- Helmet.js security headers
- Parameterized SQL queries throughout

**The reality about localStorage vs httpOnly cookies:**
> "Unless you're a bank or large enterprise, it doesn't really matter. Focus on preventing XSS, because that's what actually matters... fundamentally, the security benefit of using httpOnly cookies is very minimal. If your site suffers any kind of XSS, it makes it slightly more difficult for an attacker to use the auth token." — Security engineering community consensus

httpOnly cookies prevent token *copying* but not token *use* — an XSS attacker can still make authenticated requests on the user's behalf regardless of where the token is stored.

**If you later want httpOnly cookies:** The infrastructure is already in place (cookie-parser, CORS `credentials:true`). The change is: (1) set cookie on login, (2) remove token from `getAuthHeaders()`, (3) add `/api/auth/logout` to clear cookie. See notes in `auth.js`. This was implemented and reverted in v3.14 — it works but adds CSRF considerations.

**Token lifetime:** Currently 7 days. For higher security, reduce to 1-2 hours and add refresh token rotation.

---

---

*Last updated: March 2026 — v6.0*
*Generated for developer handover.*
