ceccd18387
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
93 lines
4 KiB
Markdown
93 lines
4 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 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.
|