danvics/pediatric-ai-scribe-v3
1
0
Fork 0
Code Issues Pull requests Projects Releases 16 Packages Wiki Activity Actions
pediatric-ai-scribe-v3/docs/logic/architecture.md
Daniel ceccd18387
Some checks failed
Forgejo Docker Build / Root app tests (push) Successful in 47s
Details
Forgejo Docker Build / Build Docker image (push) Successful in 22s
Details
Forgejo Docker Build / Deploy to the host (push) Failing after 1s
Details
docs: take the Learning Hub out of the docs 
The feature was removed; the docs still described it as live. Worst of
it was api-reference.md, which documented nine /api/learning endpoints
and fourteen /api/admin/learning CMS endpoints — routes that answer 404
— plus POST /api/user/webdav-path, whose column was dropped by
migration. Anyone reading them was reading fiction.

Checked against the running system rather than assumed: no learning
table exists, users.webdav_learning_path is gone, generated_image_links
is gone, and no route mounts /api/learning or /api/admin/learning.

Two things that look like Learning Hub and are not, so they stay:

- learningRetrieval.js is live — My Resources uses it. Its settings keep
  the learning.* names because renaming them would orphan whatever an
  administrator has already set. retrieval-tuning.md now says so instead
  of listing the rows under two different feature names.
- the moderator role is still assignable. It gated the CMS and now
  grants nothing; authentication.md says that rather than implying
  powers it does not have. moderatorMiddleware has no callers left,
  which is worth removing on its own.

auth-admin-learning.md is now auth-admin.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dv6sqaY6Vq3ChZHMem3cnU
2026-09-12 22:24:29 +02:00

4 KiB
Raw Blame History

Application Architecture Logic

This is the long-form companion to ../architecture.md. Older versions of this file tried to document every source line and frontend wrapper pattern; that became stale as Ped-AI moved selected areas to ES modules, added cookie-based web auth, migrations, Redis, metrics, patient education, and mobile support.

Current Shape

  • Runtime: Node.js 24 + Express 4 in Docker.
  • Data: PostgreSQL 16 with pgvector, plus Redis for operational cache/prompt suggestion groundwork.
  • Schema: idempotent baseline init in src/db/database.js plus versioned migrations in migrations/ through node-pg-migrate.
  • Frontend: vanilla JS SPA. Many files are still classic deferred scripts; isolated newer areas use ES modules. There is no frontend bundler.
  • Auth: web uses the ped_auth httpOnly cookie; mobile uses secure token storage and Authorization: Bearer headers. user_sessions is authoritative.
  • AI: src/utils/ai.js routes to LiteLLM, OpenRouter, Bedrock, or Azure based on startup configuration and server-side model allowlists.
  • Speech: server-side STT through LiteLLM plus explicit opt-in browser Web Speech preview. Browser Whisper/browser-local model downloads are not part of the runtime.
  • Observability: /metrics, structured JSONL logs, Postgres audit/API/access logs, and optional direct Loki push.

Composition Root

server.js owns the boot and routing order:

  1. Load environment and core middleware.
  2. Apply Helmet/CSP, CORS, cookie parsing, metrics, JSON limits, rate limiters, static file serving, and logging.
  3. Mount auth, admin, clinical workflow, storage, user data, metrics, and utility routers.
  4. Serve the SPA fallback for non-API paths.
  5. Drain audit queues and close Postgres on shutdown.

For exact current route mounts, read server.js and src/routes/*.js.

Frontend Pattern

  • public/index.html is the SPA shell.
  • public/components/*.html contains lazy-loaded tab fragments.
  • public/js/app.js handles tab activation and dispatches CustomEvent('tabChanged', { detail: { tab } }).
  • Feature scripts initialize their DOM only when the relevant tab is active.
  • Shared browser helpers are still exposed through window.* where needed.
  • New isolated frontend work should prefer small ES modules where the existing page load order supports it, but do not rewrite unrelated clinical flows just for style.

Data And PHI

  • Sensitive fields use src/utils/crypto.js AES-256-GCM helpers.
  • user_memories.name and user_memories.content are encrypted for new rows.
  • audio_backups.audio_data is gzipped and encrypted, then deleted after its short expiry window.
  • saved_encounters expire by site.auto_delete_days.
  • Audit details are PHI-redacted before database insert.

Operational Boundaries

  • Ped-AI owns the clinical UI, prompts, provider selection, note helpers, patient education, and local user data.
  • External MCP/Nextcloud services own retrieval/indexing when used by clinical assistant features.
  • Clinical answer response caching is intentionally avoided; Redis is for operational metadata and prompt suggestions, not answer reuse.

High-Risk Areas

Treat these as small-diff zones unless you are deliberately testing a broader refactor:

  • Auth/session/crypto: src/middleware/auth.js, src/routes/auth.js, src/routes/oidc.js, src/utils/crypto.js, src/utils/sessions.js.
  • Recording/STT plumbing: AudioRecorder in public/js/app.js, public/js/audioBackup.js, public/js/speechRecognition.js, src/routes/transcribe.js.
  • Encounter persistence: src/routes/encounters.js and public/js/encounters.js.
  • Validated calculators/reference data: public/js/calc-math.js, public/js/calculators.js, public/data/**, bedside calculator modules, and tests under test/.
  • ED MDM/finalization prompts and billing-related helpers.

Keep Current

Do not add file-line citations here unless a test locks them down. Prefer describing responsibilities and pointing to file paths. If implementation moves, update this doc in the same commit.