Development

This is the practical guide for changing Ped-AI safely.

Local Start

cp .env.example .env
docker compose up -d --build
curl -fsS http://127.0.0.1:3552/api/health

Run tests from the repository root:

npm test

Run a focused syntax check when touching backend entrypoints:

node --check server.js
node --check src/routes/clinicalAssistant.js

Code Map

Path	Purpose
`server.js`	Express entrypoint, middleware, static serving, route mounting
`src/routes/`	API route handlers
`src/utils/ai.js`	Text model routing through configured providers
`src/utils/clinicalAnswer.js`	Clinical Assistant answer prompt and source-grounding rules
`src/utils/clinicalRetrieval.js`	MCP result normalization and source title cleanup
`src/utils/clinicalMcpClient.js`	MCP streamable HTTP client/session handling
`src/utils/litellm.js`	LiteLLM API/admin header helpers
`src/db/database.js`	PostgreSQL pool and compatibility helpers
`public/js/app.js`	SPA shell, tab loading, shared browser actions
`public/js/admin.js`	Admin panel logic
`public/js/assistant/`	Clinical Assistant rendering, sources, images, export, API helpers
`public/js/learningHub/`	Newer modular Learning Hub frontend code
`test/`	Node test suite and frontend module regression tests

Change Workflow

Read the relevant route, utility, frontend module, and tests before editing.
Make the smallest correct change.
Add or update a regression test when changing clinical rendering, model routing, auth, settings, or source handling.
Run focused tests first if available.
Run npm test before deploy or commit.
Deploy with Docker only after tests pass.
Verify /api/health after deploy.

Clinical Assistant Changes

Clinical Assistant changes should usually include tests because small rendering or prompt changes can affect clinical trust.

High-risk areas:

citation linking,
table rendering,
source title cleanup,
named-source provenance rules,
image intent detection,
MCP result normalization,
provider/model selection.

When a real answer renders badly, save a de-identified example as a fixture or direct test input. Do not make broad global repairs that convert arbitrary numbers into citation links.

Frontend Rendering Rules

Use textContent for plain text. Use innerHTML only for static templates, sanitized markdown, or HTML built entirely from escaped values.

Safe patterns:

el.textContent = userText;
el.innerHTML = escapeHtml(userText).replace(/\n/g, '<br>');
el.innerHTML = sanitizeHtml(renderMarkdown(modelOutput));

Unsafe pattern:

el.innerHTML = modelOutput;

If a dynamic value enters an HTML string, escape it at the point of insertion. If it is an attribute value, escape quotes too.

Deployment Checks

After deployment:

curl -fsS http://127.0.0.1:3552/api/health
docker compose ps pediatric-scribe

If the browser still shows old frontend behavior, force-refresh or check the injected BUILD_ID asset query string.

Documentation Expectations

Keep docs close to operational truth. If a behavior changes, update the most specific doc in the same change. Prefer short, current docs over long historical explanations.

3.2 KiB Raw Blame History