103 lines
3.2 KiB
Markdown
103 lines
3.2 KiB
Markdown
# 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.
|