# Application Architecture Logic

This is the long-form companion to [`../architecture.md`](../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:

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, Learning Hub, 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.