docs/ARCHITECTURE.md

CarePath Architecture

CarePath is one FastAPI deployment with two separately named clinical workflows. The combined entrypoint is scribe/carepath/main.py; it owns the Scribe API, imports the Interpreter routers from interpreter/app, and mounts both built Vite frontends after API routes.

Product Boundaries

Workflow	Backend boundary	Browser surface
Ghi chép bệnh án AI	scribe/carepath, /api/v1/*	scribe/frontend/ at /, including /ghi-chep-lam-sang/
Khám bệnh nhân nước ngoài	interpreter/app, /api/* and /ws/*	scribe/frontend/ at /kham-song-ngu/

Both browser surfaces now ship from scribe/frontend/. The separate interpreter console was deleted when the bilingual visit replaced it; /phien-dich-y-khoa/ and /console/ return an explicit 404 for anyone holding an old link. The two API namespaces intentionally do not overlap.

scribe/training/ is exclusively the Scribe's offline DARAG/GEC training and quality track. It does not train or serve the Interpreter. interpreter/eval/ is a separate deterministic translation-safety harness that stays with the Interpreter.

Boundaries That Must Stay Explicit

• Scribe output is a clinician-reviewed draft; it does not replace clinical judgment.
• Interpreter output is translation only. High or critical risk stays blocked from patient display and TTS until clinician confirmation.
• Interpreter audio is memory-only: no raw-audio persistence, no microphone capture before consent, and failures fail closed.
• Risk lexicons and glossary seeds are editable JSON/CSV data, not code.
• Providers, environment variables, HTTP/WebSocket payloads, uploaded files, and database rows are trust boundaries and must be parsed before use.

Delivery and Proof

The shared process serves built static assets in production; Vite dev servers remain the development path. Existing Python, eval, frontend, browser, build, and Lighthouse commands are the validation ladder. Do not add a second service, state framework, or test runner unless a selected story proves the need.