67e416c6d9
Some checks failed
Forgejo Android APK / Root app tests (push) Successful in 47s
Forgejo Docker Build / Root app tests (push) Successful in 48s
Forgejo Android APK / Build signed APK (push) Successful in 2m38s
Forgejo Docker Build / Build Docker image (push) Successful in 12s
Forgejo Docker Build / Deploy to the host (push) Failing after 2s
Three pairs of docs described the same thing twice, and the copies had drifted
apart. Merged each into one file, keeping the unique content from both:
- ARCHITECTURE.md -> architecture.md (its operational map: ownership, request
flow, runtime boundaries, source of truth, deployment shape)
- DEVELOPMENT.md -> developer-guide.md (change workflow, Clinical Assistant
high-risk areas, frontend rendering rules, deployment checks)
- transcription-options.md -> speech.md (the clinic setup table, and the list
of browser-Whisper paths that must stay removed)
Then audited what remained against the code and the live database rather than
against the previous docs. Corrected:
- Google Vertex was still documented as a provider across nine files. The SDK
is gone; AI_PROVIDER=vertex now logs an advisory and falls back to
OpenRouter, and Gemini is reached through LiteLLM. Fixed the provider
selection order to match src/utils/ai.js, which starts from LITELLM_API_BASE.
- promptSafe was documented on 8 routes; it is on 13.
- Node 20 -> 24, "24 vanilla JS modules" -> no fixed count, and
transcribe.js/tts.js -> sttProvider.js/ttsProvider.js, which is what exists.
- STT/TTS are LiteLLM-only; README listed direct Google, AWS Transcribe and
ElevenLabs paths that are not in the runtime.
- Learning Hub PPTX export was documented as pptxgenjs, which is not a
dependency. It is pandoc against a reference deck.
- POST /api/admin/milestones/seed does not exist; it is /bulk-import.
- NEXTCLOUD_URL and NTFY_TOPIC are not read anywhere. Nextcloud is per-user in
the users table, and the ntfy topic is derived as pedscribe-{userId}.
- A prose paragraph sat inside the Clinical Assistant settings table, so half
the rows rendered as text.
Filled the gaps the audit exposed:
- database.md was missing 12 of 29 tables, including user_resources,
personal_notes, login_codes, registration_invites and generated_image_jobs.
- developer-guide.md was missing 11 routers and 10 frontend modules.
- api-reference.md detailed 121 of 244 endpoints and said so, but whole
features were absent. Added an endpoint index covering Clinical Assistant,
My Resources, Notes, Diagrams, ED Encounters, invites and sign-in codes.
- configuration.md was missing METRICS_TOKEN, REDIS_URL, API_RATE_LIMIT_MAX,
the LITELLM_* model variables, the DB_* ones maintenance.js reads, and the
per-purpose S3 resolution scheme.
- clinical-assistant.md documented 2 of its 17 environment variables.
- features-explained.md had no entry for My Resources or Clinical Assistant.
Renamed the three remaining SHOUTING filenames to kebab-case, which is what the
docs viewer's prettyName() was working around, and rewrote README's index,
which listed architecture.md twice and omitted nine files.
Noted but not changed: the Turnstile site key is hardcoded in index.html rather
than read from TURNSTILE_SITE_KEY, and /api/health/detailed can report
tts: 'elevenlabs' though no ElevenLabs path exists.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dv6sqaY6Vq3ChZHMem3cnU
2.5 KiB
2.5 KiB
Module Conventions
Ped-AI currently uses mixed JavaScript module styles. This is intentional during incremental modernization.
Current Convention
| Area | Module Style | Notes |
|---|---|---|
Backend server.js, src/** |
CommonJS | Use require and module.exports for now |
| New frontend modules | ESM | Use import and export |
| Older frontend files | Classic browser globals | Convert only when touching the feature intentionally |
| Dual browser/test files | Case-by-case | Keep classic style only when tests or browser globals require it |
Do not add root-level "type": "module" without a full backend migration plan. It would change how every .js file is interpreted by Node.
CommonJS Example
var express = require('express');
var router = express.Router();
module.exports = router;
ESM Example
import { escapeHtml } from './assistant/citations.js';
export function renderSourcesList(sources) {
return '';
}
Frontend Modernization Path
- New frontend code should be ESM where possible.
- Existing globals can remain until that feature is refactored.
- Keep browser script load order stable while refactoring.
- Export pure helper functions so Node tests can import them.
- Use
CustomEventor explicit imports instead of adding new global APIs when practical.
Acceptable Globals
Globals are acceptable when they are part of the current shell contract.
Examples:
window.activateTab,window.getAuthHeaders,- shared UI helpers still consumed by legacy feature files.
Do not add new globals when an import or event would be clearer.
Rendering And innerHTML
innerHTML is allowed only when one of these is true:
- the HTML is a static template controlled by the app,
- all dynamic values are escaped before insertion,
- the HTML has passed through the approved sanitizer,
- the content is a trusted app component fetched from
public/components/.
Prefer textContent for plain text.
Unsafe:
el.innerHTML = userText;
el.innerHTML = modelOutput;
Safer:
el.textContent = userText;
el.innerHTML = escapeHtml(userText).replace(/\n/g, '<br>');
el.innerHTML = sanitizeHtml(renderMarkdown(modelOutput));
Test Expectations
When converting a frontend file to ESM, add or update tests for:
- exported helper functions,
- expected globals still present if legacy code needs them,
- no browser-native
prompt,alert, orconfirm, - no unescaped dynamic text inserted through
innerHTML.