# Development

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

## Local Start

```bash
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:

```bash
npm test
```

Run a focused syntax check when touching backend entrypoints:

```bash
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

1. Read the relevant route, utility, frontend module, and tests before editing.
2. Make the smallest correct change.
3. Add or update a regression test when changing clinical rendering, model routing, auth, settings, or source handling.
4. Run focused tests first if available.
5. Run `npm test` before deploy or commit.
6. Deploy with Docker only after tests pass.
7. 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:

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

Unsafe pattern:

```js
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:

```bash
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.