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 20 + 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 OpenRouter, Bedrock, Azure, Vertex, or LiteLLM based on startup configuration and server-side model allowlists.
Speech: server-side STT providers 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:

Load environment and core middleware.
Apply Helmet/CSP, CORS, cookie parsing, metrics, JSON limits, rate limiters, static file serving, and logging.
Mount auth, admin, Learning Hub, clinical workflow, storage, user data, metrics, and utility routers.
Serve the SPA fallback for non-API paths.
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.

4.1 KiB Raw Blame History