pediatric-ai-scribe-v3/docs/architecture.md

Architecture

Self-hosted, single-tenant clinical documentation platform. Dockerized Node.js server + PostgreSQL + vanilla-JS SPA. No build step on the frontend.

Stack

Layer	Technology
Runtime	Node.js 20 (Alpine) + Express 4
Database	PostgreSQL 16 with pgvector extension
Frontend	Vanilla JavaScript SPA, service-worker cache
Mobile	Capacitor 6 wrapper (Android + iOS)
Container	Docker Compose (app + db)
Reverse proxy	External (Caddy, Nginx, Traefik — any)

Repository layout

server.js                        # Express entry
Dockerfile                       # node:20-alpine base
docker-compose.yml               # app + postgres
migrations/                      # node-pg-migrate files (versioned)
scripts/
  maintenance.js                 # REINDEX / collation-drift CLI
  release.sh                     # semver bump + tag + push

src/
  db/
    database.js                  # pg pool, idempotent baseline init, helpers
    migrate.js                   # programmatic node-pg-migrate runner
  middleware/
    auth.js                      # JWT + session-table validation, sliding idle
    logging.js                   # request log
  utils/
    ai.js                        # callAI() multi-provider router
    models.js                    # model registry + server-side whitelist
    prompts.js                   # prompt templates (DB-overridable)
    crypto.js                    # AES-256-GCM (PHI at rest)
    passwords.js                 # argon2id with bcrypt fallback + rehash
    sessions.js                  # token hashing, UA parser, session-id gen
    platform.js                  # isMobileClient() detection
    redact.js                    # PHI redactor for audit details
    auditQueue.js                # batched audit/api/access log writer
    fileType.js                  # magic-byte upload verification
    promptSafe.js                # <UNTRUSTED_*> LLM prompt wrapper
    logger.js                    # audit/api/access + Loki shipper
    errors.js                    # generic 500 responder
    models.js, prompts.js, ai.js # AI provider + model + prompt management
    embeddings.js                # Vertex / LiteLLM / OpenAI embeddings
    transcribe*.js, tts*.js      # STT / TTS provider clients
  routes/                        # 27 Express routers (auth, hpi, soap, …)

public/                          # SPA
  index.html                     # shell, loads components on demand
  sw.js                          # service worker (cache shell, network-first API)
  js/                            # 24 vanilla JS modules
  components/                    # per-tab HTML fragments
  css/styles.css
  models/                        # bundled Whisper WASM + model files

mobile/                          # Capacitor wrapper
  capacitor.config.json          # appId com.pedshub.scribe
  src/                           # launcher (server-URL picker)
  android/                       # generated AS project + native Java

.github/workflows/
  auto-version.yml               # conventional-commits → semver bump → tag
  android-release.yml            # signed APK on tag push
  docker-publish.yml             # multi-arch image on tag push
  version-bump.yml               # manual dispatch override
  build-apk.yml                  # legacy TWA APK

Request pipeline

request
  → helmet          (CSP, HSTS, X-Content-Type-Options, …)
  → CORS            (APP_URL + CORS_ORIGINS whitelist, fail-closed in prod)
  → cookieParser
  → express.json    (10 MB cap)
  → rate limiters   (general 200 req/min, per-endpoint tighter on auth)
  → static          (public/ with no-cache on HTML, 1h on JS/CSS; ?v=BUILD_ID busts cache per deploy)
  → route           (27 routers under /api/*)
    → authMiddleware (on protected routes: JWT, DB session check, 24h idle, last_activity update)
  → handler
  → response

On boot, server.js:

• Validates JWT_SECRET and DATA_ENCRYPTION_KEY — refuses to start in production without them.
• Runs initDatabase() (idempotent baseline) then node-pg-migrate (versioned delta).
• Checks pg_database collation version; auto-REINDEXes + refreshes on drift.
• Reads git HEAD for BUILD_ID; injects ?v=BUILD_ID into every local /js/*.js and /css/*.css reference in index.html.
• Registers SIGTERM/SIGINT handlers that drain the audit queue and close the pool before exit.

Auth model

Hybrid, runtime-selected by User-Agent and X-Client header:

Client	Token transport	Persistence	Idle policy
Web browser	ped_auth httpOnly cookie, sameSite=lax	30 d maxAge (sliding)	24 h from last write request
Capacitor app (PedScribe-Android / Capacitor UA)	Authorization: Bearer <jwt>	iOS Keychain / Android EncryptedSharedPreferences via capacitor-secure-storage-plugin	No server-side idle check (persistent)

Sessions are validated against user_sessions.token_hash on every request. Any logout / password-change / admin-revoke drops the row and the next request gets 401. The service worker clears its caches on logout so a stale shell never shows PHI on a shared workstation.

Conventional-commits auto-tag workflow can push a new semver tag using a RELEASE_PAT PAT secret so downstream release workflows fire on the tag push (the default GITHUB_TOKEN is blocked from triggering other workflows by design).

Frontend

Single HTML document with #auth-screen and #main-app sections. Tabs are per-feature HTML fragments under public/components/ fetched on demand. JS modules talk via window globals and CustomEvent on document — no bundler, no framework. Loader order is fixed in index.html.

authFetch.js installs a global fetch interceptor that treats any 401 on an authenticated request as a signal to clear local session state and redirect to login. A BroadcastChannel('pedscribe-auth') pushes that signal to sibling tabs so logging out in one tab drops UI in every open tab.

Docker topology

Container	Image	Internal port	External
pediatric-ai-scribe	ped-ai-local:latest (built from repo)	3000	127.0.0.1:3552
pedscribe-db	pgvector/pgvector:pg16	5432	not exposed

Named volumes: pgdata (database), scribe-logs (filesystem audit logs). Application health-check polls GET /api/health.

A reverse proxy terminates TLS and forwards to 127.0.0.1:3552. The app is never bound to a public interface directly.

Service worker

sw.js implements two strategies:

• Shell assets (/, /js/*, /css/*, /components/*) — cache-first.
• /api/* — network-first with cached fallback. Ensures fresh data online, last-known-good when offline.

Precached on install: index.html, core JS, main stylesheet, login component. Cleared on logout (caches.keys() → caches.delete()).