93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
# 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.
|