` 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 `` 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.*