Lumina-MSK/session_memory/7_Jun_26/ONBOARDING_INDEX.md

VKIST MSK Pilot — Intern Onboarding Index

Date: 7 Jul 2026
Audience: Phuc (ML / agentic), Quan (frontend / PWA), Dave Tran - Dat (lead)
Repo: pilot_msk_ultrasound_stack — clone already shared via GitHub

Read this file first, then open your role-specific guide:

Track	Document
Phuc — generative logic, agent, guardrails	ONBOARDING_PHUC_ML_ENGINEER.md
Quan — mobile UI, Figma, Stitch, PWA	ONBOARDING_QUAN_FRONTEND.md

Abbreviations: See §12 Glossary — FR, NFR, RAG, CoT, PHI, PWA, etc.

---

1. What this project is

VKIST MSK Pilot moves academic musculoskeletal ultrasound ML (angle → inflammation → segmentation → synovitis grade 0–3) into a clinical web platform for Vietnamese public hospitals (Bach Mai, Viet Duc class facilities).

Dimension	Summary
Cycle	Jun 2 – Sep 2, 2026 (strict 3-month window)
Method	Hybrid: waterfall phases + agile sprints
Stack	React PWA + FastAPI + Triton CV + 3-tier LLM (Edge Gemma → Gemini → MedGemma) + RAG over MOH guidelines
Users	Radiologists, surgeons, physiotherapists, patients/caregivers — each with different UI needs

Hard constraints (non-negotiable):

• Decree 13/2023 — no raw PHI leaves device without scrubbing
• No open-ended patient chat — structured, gated summaries only
• Air-gapped hospital LAN — cloud LLM only under NFR-16a (consent + audit + redaction)
• Legacy smartphones — zero-GPU fallback rendering for patient fleet

Full vision: [PILOT_PROJECT/PROJ_LEVEL_READING/PLAN/CONTEXT_VISION_SCOPE.md](../../PILOT_PROJECT/PROJ_LEVEL_READING/PLAN/CONTEXT_VISION_SCOPE.md)

Tóm tắt (VI): Dự án AI siêu âm khớp gối cho bệnh viện VN; 3 tháng; bảo mật Decree 13; các tinh năng hiện giờ đang optimize cho người dùng chính là bác sĩ cơ xương khớp - trong tương lai có thể cân nhắc bệnh nhân là đối tượng phát triển; làm tiếp phần Dave đã xây, không làm lại từ đầu.

---

2. How we work — continuation engineering

You are not here to read docs for three weeks. You inherit Dave's foundation and ship incremental PRs that close spec gaps toward sprint checkpoints.

flowchart LR
  foundation[Dave_Foundation]
  specs[Specs_and_UCs]
  backlog[Open_Backlog]
  checkpoint[Sprint_Checkpoint]
  internPR[Intern_Incremental_PR]
  foundation --> internPR
  specs --> backlog
  backlog --> internPR
  internPR --> checkpoint

1. Dave assigns one backlog ID (P-n or Q-n).
2. You read only the spec + code files for that ticket.
3. Ship a small PR (≤300 lines preferred); demo something runnable weekly.
4. Dave assigns the next ticket.

Tóm tắt (VI): Dave giao ticket → đọc đúng spec → PR nhỏ → demo hàng tuần → ticket tiếp theo.

---

3. Foundation already built (do not rebuild)

Dave's latest handoff: [session_memory/6_Jul_26.md](../6_Jul_26.md)

Area	Status	Key locations
FR-25 workspace shell	Working PoC	ClinicalWorkspacePage.tsx, WorkspaceShell.tsx, DiagnosticCanvas.tsx
CV inference	Live (FastAPI proxy)	POST /api/test/analyze/batch, mlInferenceCacheStore.ts
Clinical chat UI	Working	ClinicalChatPanel.tsx, useClinicalChat.ts
Edge Gemma 4 E2B	Working	llm.worker.ts, clinicalLlmRuntime.ts, OPFS
CoT streaming	Working (plain text)	clinicalChatStreamRegistry.ts, StreamingPlainText.tsx
Agent runtime	Working (mock tools)	agent_runtime/, agentLoop.ts
Cloud BFF	Wired	cloud_orchestrate.py, cloud_consult.py, agent_tools.py
35 Figma routes	Stub pages	figma-component-specs.md
Safety / guardrails	Spec + stubs	bert_adapter.py; guardrail.worker.ts missing
Patient PWA	Not started	Sprint 4

Tóm tắt (VI): Workspace, chat, agent, inference đã chạy; guardrail và UI mobile/patient còn thiếu — đó là việc của bạn.

---

4. Sprint checkpoints (what your PRs advance)

ID	Checkpoint	Sprint	Window	Owner
CP-1	Beta clinical modes (Planning + high reasoning)	2	Jul 10	Dave → Phuc polish
CP-2	Live agent tools (mock → BFF)	2–3	Jul 14–24	Phuc
CP-3	Guardrail slice v1	2–3	Jul 21 – Aug 7	Phuc + Dave
CP-4	Collaborative annotation UX	3	Jul 13–24	Dave; Quan UI support
CP-5	Patient list/cards → Figma mobile	3–4	Jul 28 – Aug 7	Quan
CP-6	Patient PWA (large text, 375px)	4	Jul 27 – Aug 7	Quan
CP-7	Accessibility on 2 screens	4–5	Aug 4–21	Quan
CP-8	RAG retrieval gate / referee stub	3–5	Aug 1–21	Phuc

Timeboxes: Phuc until ~Aug 31; Quan ~2 months (ends ~early Aug).

Tóm tắt (VI): Mỗi PR phải đẩy một checkpoint CP-n, không chỉ viết tài liệu.

---

5. Open backlog

Dave maintains priority. Do not self-assign large items.

Phuc — generative / agentic

ID	Gap	Starting code	Done when
P-1	Agent tools mock	tools/registry.ts, agent_tools.py	Live BFF; VITE_CLINICAL_CHAT_MOCK_TOOLS=false works
P-2	bert_adapter.py stubs	bert_adapter.py, safety/service.py	One real PASS/FAIL check on outbound text
P-3	guardrail.worker.ts missing	Create near llm.worker.ts	Worker hooks into chat before display
P-4	RAG not enforced in chat mode	runClinicalChatTurn.ts	Clinical answers require retrieval context
P-5	Planning + high reasoning beta	clinicalChatModes.ts, chatReasoningLevel.ts	Stable runs; beta flags removed
P-6	escalate_medgemma E2E	cloud_llm_gateway.py, tools/registry.ts	Demo with audit log entry
P-7	Conformal decoding eval	ml/spec/conformal_decoding_*.md	3 VI clinical test cases (research)

Quan — frontend / PWA

ID	Gap	Starting code	Done when
Q-1	35 stub routes	src/pages/*.tsx	2 priority screens match Figma
Q-2	Safety overlay not routed	SafetyEscalationOverlay.tsx	Reachable from workspace
Q-3	No mobile breakpoint	Patient pages	375px pass, touch ≥44px
Q-4	Accessibility open	Patient components	1 view WCAG-oriented pass
Q-5	No error boundaries	App.tsx	Friendly fallback on workspace route
Q-6	Patient dashboard	patient-card-*.tsx	Jargon-free, large type, VI copy
Q-7	Zero-GPU fallback UI	TBD banner	UI state when WebGL weak (Dave provides hook)
Q-8	Stitch sync after ship (lite)	Stitch board	Optional: update frame when PR merges; no standalone proposal doc

Tóm tắt (VI): Bảng backlog trên — chờ Dave giao ID cụ thể trước khi code.

---

6. Codebase map

Active code: PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/
Do not develop in: PILOT_PROJECT/workspace/LEGACY/ (read-only reference)

Note: Root PILOT_PROJECT/README.md references stale paths (Reading_docs/, CONTEXT.md). Use paths in this doc instead.

Module	Path	Phuc	Quan
Frontend	CODEBASE/frontend/	lib/llm/, workers/, useClinicalChat	Primary — pages/, components/, styles/
Backend	CODEBASE/backend/	Primary — routers, safety, adapters	Read-only
ML / NLP	CODEBASE/ml/	Primary — agent_runtime/, tests	Do not touch
Knowledge	CODEBASE/knowledge/	When P-4/P-8	Do not touch
Design	Design_Material/	Safety, API	UCs, screen specs
Session memory	session_memory/	6_Jul_26.md	26_Jun_26/Proj_context for layout

Frontend tree (Quan primary)

frontend/
├── spec/                    ← uix_prototype_coverage, figma-component-specs, DESIGN
└── implementation/src/
    ├── pages/               ← Quan: screens
    ├── components/atoms|molecules|shells/
    ├── styles/design-tokens.ts
    ├── hooks/               ← Phuc: useClinicalChat only
    ├── lib/llm/             ← Phuc ONLY
    └── workers/             ← Phuc ONLY

ML + backend tree (Phuc primary)

ml/implementation/nlp/agent_runtime/src/
  orchestrator/agentLoop.ts
  tools/registry.ts
  prompt/toolSystemPrompt.ts, toolOutputParser.ts

frontend/.../src/lib/llm/     ← edge inference, chat routing
backend/routers/              ← cloud_*, agent_tools
backend/services/             ← cloud_llm_gateway, agent_tools_service
backend/implementation/safety/, adapters/bert_adapter.py
knowledge/spec/               ← RAG when P-4/P-8

Tóm tắt (VI): Phuc = ml + backend + lib/llm; Quan = frontend pages/components; LEGACY không đụng.

---

7. Reading guide (summary)

Each role doc has three tiers. Quick reference:

Tier	When
Must read	Day 1–3, before first PR
Should read	When your ticket touches that area
Learn deeper	Keywords — grow over internship

See Phuc doc and Quan doc for full lists.

Tóm tắt (VI): Đọc bắt buộc trước PR đầu; đọc thêm theo ticket; học sâu theo từ khóa khi cần.

---

8. Dev toolkit

Shared (both)

Tool	Purpose
Cursor / Kilo	Agentic coding — load PILOT_PROJECT/AGENT_SKILL/ first
Git + GitHub	Branch per ticket; PR ≤300 lines
secrets/	Local only — see PILOT_PROJECT/secrets_template/README.md
session_memory/	Dave handoff — start with 6_Jul_26.md

Phuc additions

# Frontend + clinical chat
cd PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/implementation
npm install && npm run dev          # :5173

# Gemma lab
cd ../../ml/tests/gemma4_e2b && npm install && npm run dev   # :5174

# Agent smoke
cd ../agent_tools && npm install && npm run smoke

# Backend
cd ../../.. && conda activate vkist_ultra
PYTHONPATH=. python backend/tests/smoke_agent_tools_server.py

Key env: VITE_CLINICAL_CHAT_USE_LLM, VITE_CLINICAL_CHAT_MOCK_TOOLS, VITE_API_BASE_URL

Quan additions

cd PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/implementation
npm install && npm run dev   # :5173

Tool	Link
Figma (authority)	MSK_Workspace_UIX-Design
Stitch (acceleration)	Whiteboard 8188910238055386921
Responsive test	Chrome DevTools → iPhone SE 375px

Stitch board has web mocks today — Quan creates mobile variants and exports references for the coding agent (see Quan doc).

Tóm tắt (VI): Cursor/Kilo + Git; Phuc thêm conda/smoke tests; Quan thêm Figma + Stitch + DevTools mobile.

---

9. Bonus — Feynman Technique with agents

When a concept or code path feels hard, don't just ask the agent to fix it — ask it to teach it back to you using the Feynman Technique: explain simply, use an analogy, expose gaps, then verify your understanding.

When to use

Situation	Use Feynman prompt
You read code but can't explain it in your own words	✅
Agent generated a diff you don't fully understand	✅ Before commit
Spec uses jargon (RAG, CoT, BFF, …)	✅
You're stuck >30 min on the same concept	✅ Then ask Dave if still blocked

Universal template (copy into Cursor / Kilo)

Feynman explain — [TOPIC or FILE PATH]:

1. Explain like I'm a new intern with CS basics but new to this codebase.
2. Use one everyday analogy (non-medical if possible).
3. Walk the data/control flow in ≤8 numbered steps.
4. Define every abbreviation you use (or link to our glossary).
5. List 3 "common mistakes" a beginner would make here.
6. Ask me 2 short quiz questions — wait for my answers before continuing.
7. If I get them wrong, correct me simply.

Context: VKIST MSK Pilot, ticket [P-n or Q-n].
Do NOT write code yet — teach only.

After the agent teaches you

1. Rewrite the idea in 3–5 bullets in your own words (PR description, standup note, or personal log).
2. If you still can't rewrite without copying — you're not ready to commit that code; ask one follow-up or ping Dave.
3. Optional: paste your summary to Dave at weekly demo — proves understanding, not just output.

Role-specific Feynman prompts: Phuc §12 · Quan §14

Tóm tắt (VI): Khi khó hiểu — bảo agent giải thích đơn giản (Feynman), trả lời quiz, tự viết lại bằng lời mình; chưa hiểu thì chưa commit.

---

10. Collaboration contract

Rule	Detail
Assignment	Dave picks backlog ID — you don't self-select large scope
PR size	≤300 lines; one backlog ID per PR
Weekly demo	Runnable change required
Agentic tools	OK after reading ticket spec; pass AGENT_SKILL checklists
Research	≤40% time; only when tied to P-7 or approved milestone
Blocked >4h	Ping Dave with exact error + file path

Tóm tắt (VI): PR nhỏ, demo mỗi tuần, hỏi Dave khi kẹt quá 4 giờ.

---

11. Current assignments (Dave fills in)

Intern	Active ticket	Checkpoint	PR link	Status
Phuc	P-___	CP-___
Quan	Q-1 (/ worklist mobile)	CP-5

---

12. Glossary of abbreviations

Terms you will see daily in specs, code comments, and standups. Bookmark this section.

Project & process

Abbr.	Full form	Meaning in this project
VKIST	Viện Khoa học Công nghệ (context)	Research institute partner; MSK ultrasound AI origin
MSK	Musculoskeletal	Joint/tendon/ligament domain — knee ultrasound focus
PoC	Proof of Concept	Current sprint build — not production-certified yet
CP-n	Checkpoint n	Sprint deliverable milestone (see §4)
P-n / Q-n	Phuc-ticket / Quan-ticket	Backlog IDs in §5
UC-n	Use Case n	Clinical workflow spec (e.g. UC-48376 load scan session)
FR-n	Functional Requirement n	Feature requirement (e.g. FR-25 synovitis grading)
NFR-n	Non-Functional Requirement n	Quality constraint (latency, safety, privacy)
WS-25	Workspace 25	Clinician diagnostic workspace UI (65/35 layout)
HITL	Human-in-the-Loop	Clinician must review/confirm before AI output is final
UP5, UP1, …	User Persona n	Stakeholder archetype (UP5 = radiologist, UP1 = senior expert)

Clinical & domain (Vietnamese context)

Abbr.	Full form	Meaning
MOH	Ministry of Health (Vietnam)	Source of clinical guidelines for RAG corpus
DICOM	Digital Imaging and Communications in Medicine	Standard medical image format (ultrasound slices)
PACS	Picture Archiving and Communication System	Hospital image archive — DICOM source
EMR / HIS	Electronic Medical Record / Hospital Information System	Hospital patient record system
HL7 / FHIR	Health Level 7 / Fast Healthcare Interoperability Resources	Standards for EMR data exchange
Synovitis	—	Joint lining inflammation — graded 0–3 by this system
GradCAM	Gradient-weighted Class Activation Mapping	Heatmap showing which image regions drove AI grade
ULTS	Ultrasound	Modality used in FR-25
Circular 46	Thông tư 46/2018/TT-BYT	Vietnam clinical report format regulation
Decree 13	Nghị định 13/2023/NĐ-CP	Vietnam personal data protection law (PHI rules)

Security & privacy

Abbr.	Full form	Meaning
PHI	Protected Health Information	Patient-identifiable health data — never commit to git
PII	Personally Identifiable Information	Names, IDs, phone — scrubbed before cloud egress
RBAC	Role-Based Access Control	Permissions by clinician role (radiologist, therapist, …)
JWT	JSON Web Token	Session auth token (stored in Redis server-side)
NFR-16a	NFR exception 16a	PoC-only rule allowing cloud LLM with redaction + consent + audit
AES-256-GCM	Advanced Encryption Standard	Client-side encryption for local storage (target arch)

Architecture & infrastructure

Abbr.	Full form	Meaning
PWA	Progressive Web App	Installable web app — Sprint 4 patient target
BFF	Backend-for-Frontend	FastAPI layer that proxies agent tools + cloud LLM for browser
API	Application Programming Interface	HTTP endpoints (/api/v1/...)
K3s	Lightweight Kubernetes	On-prem hospital cluster (target deployment)
Triton	NVIDIA Triton Inference Server	GPU server for CV models + embeddings (:8001 gRPC)
FastAPI	—	Python web framework for backend (:8000)
NGINX	—	Reverse proxy / SSL termination in front of FastAPI
MinIO	—	S3-compatible object store for DICOM blobs, reports
pgvector	PostgreSQL vector extension	Vector DB for MOH guideline semantic search (HNSW index)
HNSW	Hierarchical Navigable Small World	Approximate nearest-neighbor index for RAG retrieval
GCP	Google Cloud Platform	Hosts Gemini (Vertex AI)
Modal	Modal.com	Serverless GPU platform hosting MedGemma
LAN	Local Area Network	Hospital internal network — air-gapped primary mode
CI/CD	Continuous Integration / Deployment	Jenkins + GitLab pipeline
SSE	Server-Sent Events	One-way streaming from server to browser

ML, NLP & generative AI

Abbr.	Full form	Meaning
CV	Computer Vision	Image ML pipeline (angle → inflammation → segmentation)
NLP	Natural Language Processing	Clinical text cleanup, explanations, chat
LLM	Large Language Model	Generative text models (Gemma, Gemini, MedGemma)
RAG	Retrieval-Augmented Generation	Fetch MOH guideline chunks before generating answer
CoT	Chain-of-Thought	Model "thinking" trace before final answer (thought channel)
TTFT	Time to First Token	Latency until first streamed word appears (NFR-7: ≤200 ms target)
E2B / E4B	Gemma 4 2B / 4B params	Edge (browser) vs server Ollama model sizes
WebLLM	Web Large Language Model	In-browser inference via WebGPU + WASM
OPFS	Origin Private File System	Browser storage for ~1.9 GB Gemma checkpoint
WASM	WebAssembly	Binary format for in-browser ML (MediaPipe, LiteRT)
WebGPU	—	Browser GPU API — required for edge Gemma
WebGL	—	Older browser 3D API — fallback path for weak devices
BERT	Bidirectional Encoder Representations from Transformers	Classifier for drift/guardrail/referee (partially stubbed)
EmbeddingGemma	—	768-dim embedding model for RAG vector search
MedGemma	—	Tier-3 clinical deep-reasoning LLM (Modal, NFR-16a)
Gemini	—	Tier-2 orchestration/translation LLM (GCP Vertex AI)
Gemma	—	Tier-1 edge conversation LLM (browser MediaPipe)
Agent	—	Multi-step tool-calling loop (<tool_call> / <final> protocol)
Guardrail	—	Safety filter on generated text (hallucination, scope breach)
RAG-Referee	—	3-axis citation validator for MedGemma output
Circuit breaker	—	Clinician challenges AI grade via Socratic dialogue before sign-off
Socratic dialogue	—	Structured Q&A between clinician and AI about a grade
DeepLab / UNet	—	Segmentation model architectures in CV pipeline
ConvNeXt / MedViT	—	Angle classification model families (legacy stack)
LiteRT	—	On-device inference runtime (TensorFlow Lite successor)
TFLite / TFJS	TensorFlow Lite / TensorFlow.js	Client-side ML runtimes
ONNX	Open Neural Network Exchange	Model interchange format for Triton deployment
VRAM	Video RAM	GPU memory — relevant for Triton/Modal sizing

Frontend & UI

Abbr.	Full form	Meaning
UI / UIX	User Interface / User Interface eXperience	Screens, layout, interaction design
SPA	Single Page Application	React app — one HTML shell, client-side routing
TS / TSX	TypeScript / TypeScript + JSX	Frontend language + React syntax
Zustand	—	Lightweight React state store (target arch; PoC uses context)
Dexie.js	—	IndexedDB wrapper for offline cache
IndexedDB	—	Browser local database for inference cache, session replay
MRN	Medical Record Number	Patient hospital ID shown in TopBar
FR-26	Functional Requirement 26	Future patient-facing dashboard scope
a11y	Accessibility	WCAG-oriented design (contrast, font scale, touch targets)

Tools & workflow

Abbr.	Full form	Meaning
PR	Pull Request	Code review unit — keep ≤300 lines
IDE	Integrated Development Environment	VS Code / Cursor
Dev Mode	Figma Dev Mode	Inspect panel for spacing, tokens, CSS
SDK	Software Development Kit	e.g. @google/stitch-sdk for asset fetch

Tóm tắt (VI): Bảng viết tắt trên dùng hàng ngày — FR/NFR = yêu cầu; RAG/LLM/CoT = AI sinh ngôn ngữ; PHI/Decree 13 = bảo mật; PWA/DICOM/PACS = lâm sàng & UI; hỏi Dave nếu gặp từ mới.

---

13. Quick links

Resource	Path
Project vision	PILOT_PROJECT/PROJ_LEVEL_READING/PLAN/CONTEXT_VISION_SCOPE.md
Sprint architecture	PILOT_PROJECT/workspace/sprint_1_2/Design_Material/SPRINT_1_2_ARCHITECTURE_SPEC.md
UI truth doc	PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/spec/uix_prototype_coverage.md
Agent skills	PILOT_PROJECT/AGENT_SKILL/INTRODUCTION.md
Dave's Jul 6 handoff	session_memory/6_Jul_26.md
Layout reference	session_memory/26_Jun_26/Proj_context_26_Jun_26.md