msk_admin/Lumina-MSK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #5 from DTJ-Tran/poc2

Browse Source 
update session_memory - for refer to the passwork
This commit is contained in:
David Tran
2026-07-07 22:03:18 +07:00
committed by GitHub
parent 4d89e55d86 3fbbca1eaa
commit 3435cfefa0
17 changed files with 2784 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
proj_level_reading/PLAN/SLIDE_DECK_PDF.pdf
View File

Binary file not shown.

37
session_memory/12_Jun_26.md Normal file
View File

@@ -0,0 +1,37 @@
# Session Memory
## Current task
Created Kilo skill `cicd-architect-grill`.
## Created skill
- Skill name: `cicd-architect-grill`
- Skill file: `.kilocode/skills/cicd-architect-grill/SKILL.md`
- Skill line count: 49 lines after long draft compression.
## Skill purpose
Design, redesign, migrate, debate CI/CD pipelines for one software project. No cloud/language/runtime/platform assumptions.
## Skill behavior
- Inspect repo context before questions.
- Extract FRs, NFRs, constraints, success criteria, Definition of Done.
- Use C4 modeling only as deep as needed.
- Choose CI/CD pattern from situation, not vendor defaults.
- Cross-check: build reproducibility, tests, scans, artifacts, secrets, promotion, approvals, rollback, observability, cost, ownership.
- Grill one decision at a time when requested.
- Output draft/final plans as YAML.
## Repository context
- Workspace root: `/Users/davestran/Downloads/vkist_internship`
- Kilo config: `kilo.json`
- User-facing style: caveman style active.
- Existing skills inspected under `/Users/davestran/Downloads/vkist_internship/.kilocode/skills/`.
## Important constraints
- Do not assume GCP, AWS, Azure, Kubernetes, serverless, GitHub Actions, GitLab CI, Jenkins, Terraform unless user asks.
- Do not implement infrastructure until user approves design plan + implementation path.
- Do not ask many questions when repo evidence answers.
## Current status
- New skill directory exists.
- `SKILL.md` written and inspected.
- No tests run: Kilo skill definition, not executable code.

43
session_memory/13_Jun_26.md Normal file
View File

@@ -0,0 +1,43 @@
# Session Memory
## Current task
Create session memory for 13 Jun 26.
## Work done
- Refined `API_CONTRACT_DRAFT.md` to v0.2.0 for FR-25 Synovitis Grading Workspace.
- Added public clinical routes + internal/local safety routes from API contract.
- Added async analysis job model, model registry, GradCAM, rationale, Socratic, BERT drift, RAG evidence, activations, artifact masks, ground truth, escalation, morphology, telemetry, report sign, EMR sync.
- Updated error codes, data types, OpenAPI skeleton, PlantUML sequence.
- Ran `git diff --check`; no whitespace errors.
## Architecture review
- Loaded `improve-codebase-architecture` skill.
- Read `LANGUAGE.md`; no repo `CONTEXT.md`; no `docs/adr`.
- Explore agent inspected `vkist-ultrasound/app.py`, `pdf_service.py`, `templates/js/script.js`, API docs, FR-25 use cases.
- Found 6 deepening candidates:
- Clinical Workflow State Machine Module — Strong.
- Model Registry + Runtime Adapter Module — Strong.
- Measurement + Severity Calibration Module — Strong.
- Privacy + Artifact + Audit Module — Strong.
- Finalization + Report + EMR State Module — Strong.
- Safety + Telemetry + Feedback Module — Worth exploring.
- HTML report write was attempted, but tool aborted before file landed. Report not completed.
## Repository context
- Workspace root: `/Users/davestran/Downloads/vkist_internship`
- User-facing style: caveman style active.
- Main code area: `PILOT_PROJECT/vkist-ultrasound`
- API contract target: `PILOT_PROJECT/workspace/sprint_1_2/Design_Material/API-docs/API_CONTRACT_DRAFT.md`
## Important constraints
- Do not propose interfaces before user picks architecture candidate.
- If user picks candidate, enter grilling loop.
- If naming new deepened module after concept missing from `CONTEXT.md`, update `CONTEXT.md`.
- If user rejects candidate with load-bearing reason, offer ADR only if future reviewers need it.
- Do not commit unless explicitly asked.
## Current status
- API contract file updated.
- Architecture candidates identified.
- HTML architecture report still pending due aborted write.
- No tests run for architecture review; no code changed during review.

60
session_memory/14_Jun_26.md Normal file
View File

@@ -0,0 +1,60 @@
# Session Memory
## Current task
Create/update `grill_bento_codebase` architecture skill.
## Work done
- Loaded `grill-with-docs`, `grill-bento-codebase`, `skill-creator`.
- Inspected:
- `.kilocode/skills/grill_bento_codebase/SKILL.md`
- `.kilocode/skills/grill_bento_codebase/GEMINI.md`
- `.kilocode/skills/grill_bento_codebase/BENTO_DESIGN_GUIDELINE.md`
- `.kilocode/skills/grill_bento_codebase/bento_template.html`
- `.kilocode/rules/bento_template.html`
- `.kilocode/rules/BENTO_DESIGN_GUIDELINE.md`
- Updated `grill_bento_codebase` skill assets.
- Added Bento depth constraint:
- one Bento room may contain multiple sub-components/sub-projects
- max Bento depth = 3
- depth 1 = root Bento
- depth 2 = child sub-project
- depth 3 = grandchild sub-project
- depth 4+ invalid
- Added fallback rule: detail beyond depth 3 stays inside owning Bento as local `spec/`, `spec/docs/`, `implementation/`, or `tests/`.
- Moved skill-local source refs to:
- `BENTO_DESIGN_GUIDELINE.md`
- `bento_template.html`
- Bumped guideline version to `0.5.0`.
## Skill output contract
- Context lock from FRS, NFRS, user-interaction, Software_Arch, Solution_Arch.
- Bento-BEV HTML blueprint from `bento_template.html`.
- Markdown tree-view for dev-team flatout navigation.
- Room cards.
- Interface contracts.
- Dependency map.
- Traceability matrix.
- Open decisions, one at a time.
## Validation done
- Re-read full `.kilocode/skills/grill_bento_codebase/BENTO_DESIGN_GUIDELINE.md`.
- Confirmed depth rule appears in:
- `BENTO_DESIGN_GUIDELINE.md`
- `SKILL.md`
- `GEMINI.md`
- Grep checked no stale `.kilocode/rules` refs inside `.kilocode/skills/grill_bento_codebase`.
## Repository context
- Workspace root: `/Users/davestran/Downloads/vkist_internship`
- User-facing style: caveman style active.
- Skill area: `.kilocode/skills/grill_bento_codebase`
## Important constraints
- No Bento tree depth > 3.
- No nested Bento beyond grandchild depth.
- Extra detail stays local to owning Bento room.
- No commits unless explicitly asked.
## Current status
- `SKILL.md`, `GEMINI.md`, `BENTO_DESIGN_GUIDELINE.md` updated.
- No tests run: skill docs, not executable code.

45
session_memory/18_Jun_26.md Normal file
View File

@@ -0,0 +1,45 @@
---
title: Session Memory 18 Jun 26
date: 2026-06-18
status: active
---
## Summary
Compressed 2026-06-18 session work: `cv_code` split, PlantUML Chen ER skill, session memory.
## cv_code module split
- Split legacy `legcode/app.py` into `ml/implementation/cv/code/` into three modules:
- `config.py`
- `framework.py`
- `server.py`
- Legacy file untouched until new modules pass import checks.
- `python -m py_compile` passed all files.
- `server.py` import blocked by missing `pdf_service`.
- `framework.py` path bug: `cv_root = Path(__file__).resolve().parents[2]` skips too far. Correct: `parents[1]`.
## skill-creator inspection
- Loaded `.config/kilo/.kilo/skills/skill-creator/SKILL.md`.
- Skill structure: `SKILL.md` required; optional `GEMINI.md`, `EXAMPLES.md`, `REFERENCE.md`, `scripts/`, `assets/`.
- Template description rules apply.
## er-chen-diagram skill
- Created `.kilocode/skills/er-chen-diagram/` scaffold.
- Files written: `SKILL.md`, `EXAMPLES.md`, `REFERENCE.md`.
- Skill contents:
- Mandatory `@startchen` / `@endchen`.
- Attributes only inside `{}`.
- Primary keys use `<<key>>`.
- Relationships empty blocks, then connect lines.
- Copy exact code shells verbatim.
## Session memory housekeeping
- Listed existing memory files: `12_Jun_26.md`, `13_Jun_26.md`, `14_Jun_26.md`.
- Recorded activity in this file.
## Relational DB Design
- Created relational DB design spec per plan: ER/schema PlantUML and Chen notation in RELATIONAL_DB_SCHEMA_SPEC.md.

159
session_memory/26_Jun_26/CODING-AGENT-INSTRUCTION-PHASE0-PHASE1.md Normal file
View File

@@ -0,0 +1,159 @@
# Coding Agent Instruction: Resolve 17 Remaining Structural Gaps in Phase 0 & Phase 1
You have already fixed the TypeScript build failures. The 17 unchecked plan items below must be addressed structurally. Each item is a checklist entry in `.kilo/plans/35-figma-designs-implementation-plan.md`. Only mark an item `[x]` in that plan file after you have implemented it AND it compiles cleanly.
## Reference Files
- Implementation Plan: `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/.kilo/plans/35-figma-designs-implementation-plan.md`
- Frontend root: `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend`
- Severity rule: Do NOT mark `[x]` unless you have implemented the item AND verified it.
## Work Order: Exact Sequence with Acceptance Tests
### 0.1 Environment Tooling
1. Configure ESLint + Prettier
- Add `.eslintrc.cjs` and `.prettierrc` (or extend recommended configs).
- Add scripts to `package.json`: `"lint": "eslint src --ext .ts,.tsx"`.
- Acceptance: `npm run lint` runs without failing on the current src tree (warnings OK, but no auto-fixable errors left hanging).
2. Set up Husky
- Install `husky` + `lint-staged`.
- Add `prepare` script: `"prepare": "husky"`.
- Add `.husky/pre-commit` to run `lint-staged`.
- Acceptance: `git add src/ && git commit` triggers Husky and blocks on lint failure.
3. Configure Vitest
- Install: `vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `jsdom`.
- Add `vitest.config.ts` with `test.environment = 'jsdom'` and `include: ['src/**/*.{test,spec}.{js,ts,jsx,tsx}']`.
- Add script: `"test": "vitest"`.
- Acceptance: `npx vitest run` executes (0 tests is OK for now; framework must be correct).
4. Set up Playwright
- Install `@playwright/test`.
- Add `playwright.config.ts` with baseURL `http://localhost:5173` and webServer using `vite preview` or same.
- Add script: `"test:e2e": "playwright test"`.
- Acceptance: `npx playwright test --list` does not error (no tests yet is OK).
5. Configure Storybook
- Install `@storybook/react-vite` and run `storybook init`.
- Add 1 story for `Button` atom and 1 story for `TopBar` organism.
- Acceptance: `npm run storybook` builds the UI and the 2 stories render.
### 0.3 Component Inventory
6. Analyze 35 Figma Files
- Inspect Figma paths under `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/Design_Material/` - section: `Figma Design Source Files`.
- Produce an inventory mapping file: `spec/figma-component-specs.md` is insufficient; append `spec/component-inventory.md` with:
- Unique screen count (should be 35).
- Reusable component list by atomic depth (atoms, molecules, organisms, templates).
- One dependency graph (Mermaid is fine).
- Acceptance: `spec/component-inventory.md` exists, has 35 distinct screens, and has a Mermaid dependency graph.
7. Build Storybook Stories for Primitives
- Add stories for `Button`, `Input`, `Icon`, `Badge`, `Label`, `Toggle`, `Tooltip`.
- Acceptance: All primitives render in Storybook.
### 0.4 API Contracts
8. Cross-Reference API Contracts
- Open `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/Design_Material/API_docs/API_CONTRACT_DRAFT.md` & the `API spec from the backend-file` in `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/backend/spec/interface-contract.md` & the data-layer definition - check the reference from context in the dirrectory (a folder) at `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/data/spec`
- Cross-check each endpoint against `src/services/*.ts`.
- Acceptance: Each service file has JSDoc lists of endpoints it covers.
9. Define TypeScript Interfaces
- Add `src/types/api.ts` with request/response interfaces for all 7 services.
- Acceptance: All 7 services import and use their types.
10. Implement HTTP + MSW Adapters
- Add `src/services/adapters/httpAdapter.ts` and `src/services/adapters/mswAdapter.ts`.
- Each service file must use the adapter via `services/index.ts` seam.
- Acceptance: `tsc --noEmit` clean; `vitest run` can mock the adapter without touching prod code.
11. Implement Auth/Logging Interceptors
- In `httpAdapter.ts`, add request interceptor that:
- Attaches `Authorization` header from a session token (mocked OK).
- Logs request method + URL.
- Normalizes errors to a `ServiceError` class.
- Acceptance: Interceptor exists and is imported only by `httpAdapter.ts` (no component imports).
### 1.2 Zustand Slices
12. Co-locate Slice Tests
- Create `src/store/sessionSlice.test.ts`, `src/store/dicomSlice.test.ts`, etc. (6 files).
- Each test imports the slice factory (`createSessionSlice`) and invokes the interface.
- Acceptance: `vitest run --coverage` shows coverage files for each slice.
13. Create Domain Selectors
- In each slice file, export type-safe selectors via `create`.
- Acceptance: `TopBar` and `BottomBar` consume slice selectors instead of inline memoization.
### 1.3 WebWorkers
14. Create `src/workers/` Files
- `cv.worker.ts`: stub with `onmessage` and `postMessage` for `preprocess` msg type.
- `llm.worker.ts`: stub with `generate` msg type.
- `guardrail.worker.ts`: stub with `safetyCheck` msg type.
- Acceptance: `tsc --noEmit` clean; workers can be imported in a hook.
15. Implement Worker Pool + Hooks
- `src/hooks/useWebWorker.ts`: generic hook accepting worker class + message schema.
- `src/hooks/useCVWorker.ts`, `useLLMWorker.ts`, `useGuardrailWorker.ts`: domain wrappers.
- Acceptance: Hooks can be instantiated without runtime errors in a test render.
16. Transferable Message Protocols
- In each worker stub, explicitly show `Transferable` usage (pass `ImageBitmap` or `ArrayBuffer` in transfer list).
- Acceptance: TypeScript types enforce transferable contracts.
17. Fallback to Main Thread
- Each hook exports `isSupported: boolean`. If `Worker` constructor not available, use a mock implementation on main thread.
- Acceptance: In jsdom test, `isSupported` is false and hook still resolves.
### 1.4 Services Deepening
18. Move `encryption.ts` Out of the Store
- Remove `import { encryptStorage } from '../utils/encryption'` from `src/store/index.ts`.
- Create `src/services/storageAdapter.ts` that exports `createSessionStorage` and `createEncryptedStorage`.
- `store/index.ts` must import `createJSONStorage(() => storageAdapter)` from `services/storageAdapter`.
- Acceptance: `grep encryptStorage src/store/index.ts` returns nothing in src/store/.
### 1.5 Route-Aware Shell
19. Implement `protected.tsx`
- Add `src/routes/protected.tsx` with a `<RequireAuth>` wrapper that redirects to `/login` when `!sessionId`.
- Wrap `/workspace` in `<RequireAuth>`.
- Acceptance: Visit `/workspace` when unauthenticated; browser redirects to `/login`.
20. `WorkspaceShell` Owns 65/35 Split
- `WorkspaceShell.tsx` must render the 65/35 layout directly: `div.flex.h-screen` with `w-[65%]` ZoneA and `w-[35%]` ZoneB.
- `routes/index.tsx` `<DiagnosticWorkspace>` must only render `<WorkspaceShell />` without re-implementing the split.
- Acceptance: `grep "flex-1" src/components/templates/WorkspaceShell.tsx` finds exactly one instance; `grep "ZoneA" src/routes/index.tsx` finds zero (or just an import).
21. Lift `initApp` Out of `App.tsx`
- Add `src/hooks/useAppInit.ts`.
- Move the `initApp` effect into this hook.
- `App.tsx` becomes: `<AppRoutes />` plus `<AppInit />` or composes it.
- Acceptance: `grep "initApp" src/App.tsx` finds nothing.
22. `React.lazy` + `Suspense` in Routes
- Use `React.lazy(() => import('../components/organisms/ZoneA'))` and same for `ZoneB`.
- Wrap `<DiagnosticWorkspace>` children in `<Suspense fallback={<div>Loading...</div>}>`.
- Acceptance: `grep React.lazy src/routes/index.tsx` finds 2+ matches.
### 1.6 Layout Responsiveness
23. Responsive Breakpoints
- `WorkspaceShell.tsx` must use `@media` or Tailwind responsive classes so that on `< md` the 65/35 stack becomes a tabbed/toggle layout (Zone A | Zone B).
- Acceptance: Resize viewport to 375px; only one Zone visible at a time.
24. 60fps Rendering Hints
- Add `will-change: transform` to animated containers.
- Add `contain: layout style paint` to the workspace root.
- Acceptance: `grep -E "will-change|contain:" src/components/templates/WorkspaceShell.tsx` finds both.
## Strict Consequences
- If you cannot complete a specific item within this prompt, do not leave it half-done. Leave the plan checkbox `[ ]` and add a comment in code explaining what is blocking you.
- All code must keep `tsc --noEmit` clean after your changes.
- Do NOT touch backend files or any file outside `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend` unless an item explicitly requires it.
## Final Verification (YOU MUST RUN THESE)
```bash
cd /Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend
npx tsc --noEmit && npm run build
npm run lint
npx vitest run
npx playwright test --list
npm run storybook -- --headless 2>&1 | tail -20
```
Produce a summary of which commands passed/failed and why.

189
session_memory/26_Jun_26/Proj_context_26_Jun_26.md Normal file
View File

@@ -0,0 +1,189 @@
# SESSION MEMORY — 26 Jun 26
## APP PURPOSE
VKIST MSK Platform — air-gapped musculoskeletal ultrasound analysis. FR-25 Synovitis Grading (knee). Vietnamese NLP. RAG citations. HITL finalization. ≤150 MB bundle. ≤1.5s inference.
## ARCHITECTURE (C4)
### Context
- **UP5** Radiologist: primary user — load scan, review grade, finalize, sign, view GradCAM, engage circuit breaker, review RAG evidence
- **UP1** Senior Expert: clinical protocol validation, MOH guideline approval, threshold sign-off
- **UP4** Support: registration, case queue
- External: PACS (DICOM), EMR/HIS (HL7/FHIR), Triton (GPU inference), ladybugDB (ontology), pgvector (MOH guidelines HNSW), GemmaE2B/MedGemma (LLM), EmbeddingGemma (RAG embeddings)
### Containers
- **PWA** React 18 + TS + Zustand + LiteRT + MediaPipe + Dexie.js. DICOM canvas, GradCAM overlay, edge guardrail (Transformers.js BERT + OpenRedaction + pii-filter) in WebWorkers.
- **NGINX + Keepalived** VIP failover ≤2s, SSL termination
- **FastAPI** edge-inference-svc: DICOM ingest, ML pipeline orchestration, Grad-CAM, report assembly, SSE streaming
- **FastAPI** rag-svc: pgvector top-k retrieval, ladybugDB ontology, LLM consult route, RAG-Referee
- **Postgres + pgvector** HNSW index for MOH guidelines
- **Redis** JWT sessions, rate-limit, consult_mode state
- **MinIO** S3: DICOM, overlays, GradCAM heatmaps, reports
- **Triton** gRPC :8001: 3-step ML pipeline + embeddings
### 3-STEP ML PIPELINE (Triton)
1. **Angle Classification** — ConvNeXt/DenseNet/ResNet/EfficientNet/Swin-V2. Classes: med-lat, post-trans, sup-trans-flex, sup-up-long
2. **Inflammation Detection** — EfficientNet-B0 binary (post-trans, sup-up-long only)
3. **Segmentation** — DeepLabV3-ResNet101 (post-trans) OR UNet3Plus-Attention/DeepLabV3 (sup-up-long). Classes: background, effusion, fat, femur, synovium, tendon
4. **Measurement** — ROI middle 1/3 of bounding box. PIXEL_TO_MM = 45/655
5. **Severity** — Combined: effusion 60% + synovium 40%. Grades 0-3: Rất nhẹ/Nhẹ/Trung bình/Nặng
### GRADCAM
- Zero extra clicks (auto on upload)
- Base64 PNG from FastAPI
- Canvas overlay, adjust opacity
### WEB WORKER TOPOLOGY
- `cv.worker.ts` — LiteRT WASM: CV inference (angle pre-classifier). Isolated WASM.
- `llm.worker.ts` — WebLLM WASM: GemmaE2B local generation. NFR-4 1.5GB heap.
- `guardrail.worker.ts` — Transformers.js WASM/WebGPU: BERT hallucination/mal-intention/scope-breach scoring.
**Isolation:** No SharedArrayBuffer/Atomics. postMessage with structured clone only.
## FRONTEND DESIGN (WS-25)
### Layout: 65/35 split (Zone A: DICOM | Zone B: Results + Chat)
```
┌─ Top Bar (patient ID, back, sign) ──────────────────────┐
├─ Zone A (65%) ────────┬─ Zone B (35%) ────────────────────┤
│ │ Phase Indicator (sticky) │
│ 5 Canvas Layers: │ Classification Card (grade,conf) │
│ 1. Background │ Explanation Panel (GradCAM thumb) │
│ 2. GradCAM │ Chat Panel (Socratic dialogue) │
│ 3. Segmentation │ Override Card (Phase 4) │
│ 4. Annotations (SVG) │ Quick Actions │
│ 5. Viewport HUD │ │
│ │ │
│ Toolbar: pan/zoom/ │ │
│ brush/eraser/caliper │ │
├───────────────────────┴───────────────────────────────────┤
└─ Bottom Bar (NFR status, EMR sync, offline indicator) ─────┘
```
### Canvas Layers (z-index)
- 0: Background DICOM (render once, never redraw on pan/zoom)
- 10: GradCAM (CSS transform, no redraw)
- 50: Segmentation overlay
- 100: SVG Annotations (brush/caliper)
- 200: Viewport HUD (text, mousemove redraw)
- 900-999: System chrome (top/bottom bar)
### Zustand Store Keys
- `sessionId`, `patientId`, `currentPhase`
- `dicomFrame: ImageBitmap | null` (GPU-friendly)
- `dicomMetadata`, `mlResults` (single atomic object)
- `clinicianGrade`, `isOverriding`, `overrideJustification`
- `maskedRegions: MaskedRegion[]` (SVG path data, not raster)
- `chatMessages` (pruned to 20, older → IndexedDB)
- `driftScore`, `refereeIntervened`
- `zoomLevel`, `panOffset` (not persisted, RAF updates)
- `activeTool: pan|zoom|brush|eraser|caliper|pin`
- `showGradCAM`, `showSegmentation`
### 6-PHASE WORKFLOW
1. **Classification** — ML grade, confidence bar
2. **Explanation** — GradCAM visible, RAG evidence, LLM rationale
3. **Negotiation** — Socratic dialogue, circuit breaker, BERT drift
4. **Reconfiguration** — Override card, pixel activation inspector
5. **Final Decision** — Summary, HITL signature
6. **EMR Sync** — HL7/FHIR push, audit hash
## KEY API CONTRACTS
### Core Endpoints
- `POST /api/v1/sessions` → create session
- `POST /api/v1/sessions/{id}/frames` → upload DICOM (multipart)
- `POST /api/v1/analysis-jobs` → trigger ML pipeline
- `GET /api/v1/analysis-jobs/{id}` → get result (angle/inflammation/segmentation/measurement/severity)
- `GET /api/v1/analysis-jobs/{id}/steps` → step-level status
- `PATCH /api/v1/sessions/{id}/review` → clinician review (approve/correct/reject)
- `POST /api/v1/reports` → generate report
- `POST /api/v1/reports/{id}/sign` → HITL digital signature
- `POST /api/v1/reports/{id}/emr-sync` → EMR push (outbox if offline)
### Safety Endpoints
- `POST /api/v1/sessions/{id}/explanations/gradcam` → GradCAM heatmap
- `POST /api/v1/sessions/{id}/safety/circuit-breaker` → trigger circuit breaker
- `POST /api/v1/sessions/{id}/chat/socratic` → Socratic dialogue (SSE streaming)
- `POST /api/v1/sessions/{id}/drift/check` → BERT semantic drift
- `POST /api/v1/sessions/{id}/rag/evidence` → RAG guideline arbitration
- `POST /api/v1/feedback` → ground-truth override telemetry
### ML Response Shape
```json
{
"result": {
"angle": { "class": "sup-up-long", "confidence": 0.9845 },
"inflammation": { "detected": true, "confidence": 0.942 },
"segmentation": { "mask_ref": "s3://...", "overlay_ref": "s3://...", "color_legend": {...} },
"measurement": { "thickness_mm": 6.87, "pixel_to_mm": 0.0687 },
"severity": { "level": 3, "label": "severe", "combined_score": 18.4 }
}
}
```
## NFR SUMMARY
| NFR | Target | Implementation |
|-----|--------|----------------|
| NFR-4 | ≤150 MB bundle | React PWA, tree-shake, split vendor chunk, Dexie.js |
| NFR-5 | ≤1.5s inference | Triton ONNX/TensorRT, client memory ≤150MB |
| NFR-7 | ≤200ms TTFT | SSE streaming, token chunking |
| NFR-8 | Fault tolerance | IndexedDB cache, SW offline mode, session recovery |
| NFR-13 | Grad-CAM zero-click | Auto on upload, no extra UI steps |
| NFR-14 | No client GPU | LiteRT WASM, CPU fallback |
| NFR-16 | Air-gapped primary | All inference + storage on-prem via K3s |
| NFR-17 | Immutable audit | PostgreSQL WAL, no UPDATE/DELETE triggers |
| NFR-18 | RAG citations | 100% LLM text cites MOH via pgvector HNSW |
| NFR-19 | HITL signature | `signer_id != NULL` constraint before FINALIZED |
## DECREE 13 / CIRCULAR 46
- Client: Decree 13 regex scrubber (OpenRedaction + pii-filter + js-data-anonymizer) before network
- Server: FastAPI `phi_scrub` middleware (Microsoft Presidio) as ground-check
- PDF: Circular 46/2018 format, bilingual VI/EN, audit hash, signer block
## SPRINT 1-2 DELIVERABLES
### Sprint 1 (Jun 15–26) — "Fast PoC Baseline"
- [ ] PWA shell: React + Zustand + PWA manifest + Service Worker + Dexie.js
- [ ] DICOM canvas: Cornerstone.js + 5-layer canvas stack
- [ ] FastAPI `/api/analyze` endpoint (sync 3-step pipeline)
- [ ] Triton 3-step model ensemble + gRPC
- [ ] NGINX + Keepalived VIP
- [ ] Grad-CAM overlay on primary viewport
- [ ] Circuit-breaker skeleton
### Sprint 2 (Jun 29–Jul 10) — "Multi-Modal & NLP Integration"
- [ ] GemmaE2B browser WebLLM + Cloud MedGemma Vertex AI
- [ ] BERT drift monitor + RAG-Referee
- [ ] Socratic dialogue (SSE streaming)
- [ ] ladybugDB ontology traversal
- [ ] Decree 13 scrubber (client + server)
- [ ] Circular 46 PDF report generator
- [ ] HITL signature gate
- [ ] Immutable audit log
- [ ] EMR/HIS HL7/FHIR push
## KEY FILES
- `/workspace/sprint_1_2/Design_Material/SPRINT_1_2_ARCHITECTURE_SPEC.md` — sprint-scoped architecture
- `/PROJ_LEVEL_READING/ARCHITECT/SOFTWARE_ARCHITECTURE_SPEC.md` — full software architecture
- `/workspace/sprint_1_2/Design_Material/API_docs/API_CONTRACT_DRAFT.md` — API contract v0.2.1
- `/workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UI_Screen_Spec/Screen_Analysis_WS-25.md` — WS-25 screen analysis
- `/workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/FR_25_UC_SPEC.md` — FR-25 use case spec
- `/workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UC_CONTEXT.md` — use case context
## PHASE SEQUENCE (ML Pipeline)
```
DICOM upload → CLAHE → Angle Classification → (if post-trans) Inflammation → Segmentation
→ (if sup-up-long) Inflammation → Segmentation → Measurement → Severity (0-3)
→ GradCAM overlay → LLM rationale (GemmaE2B/MedGemma + RAG) → Clinician review
→ HITL sign → EMR push
```
## NEXT ACTIONS
- Implement PWA shell (T1-E)
- Set up FastAPI `/api/analyze` + `/api/consult/stream` (T2-B)
- Configure Triton ensemble (T2-A)
- Build WS-25 UI components (Zone A 5-layer canvas + Zone B scrollable panel)
- Wire up edge guardrail WebWorkers (cv.worker.ts, llm.worker.ts, guardrail.worker.ts)

43
session_memory/27_jun_26/27_jun_26.md Normal file
View File

@@ -0,0 +1,43 @@
# SESSION MEMORY — 27 Jun 26
## BACKEND ARCHITECTURE & SPECIFICATION
### 1. Project Context (from Proj_context_26_Jun_26.md)
- **Purpose**: VKIST MSK Platform for air-gapped musculoskeletal ultrasound analysis (FR-25 Synovitis Grading).
- **Core Tech Stack**: FastAPI, PostgreSQL + pgvector, Redis, MinIO (S3), Triton (GPU inference), Local LLM/BERT.
- **ML Pipeline**: 3-step process: Angle Classification $\rightarrow$ Inflammation Detection $\rightarrow$ Segmentation/Measurement $\rightarrow$ Severity Grading (0-3).
- **Safety Stack**: GradCAM, Socratic Chat, BERT drift monitor, RAG-Referee.
- **Compliance**: Decree 13 (PII scrubbing), Circular 46 (PDF reports).
### 2. Backend Structural Specification (from backend-spec.md)
The backend follows a modular "Seams" architecture:
- **API Layer**: `backend/api/` contains FastAPI routers.
- **Implementation Layer**: `backend/implementation/` contains deep modules.
- **Adapters**: `backend/implementation/adapters/` handles low-level external service communication (S3, Triton, LLM, BERT).
**Core Modules:**
- **Auth**: JWT, session management.
- **Patient**: Patient CRUD, ingestion history.
- **Session**: Frame handling, S3 storage, review patching.
- **Analysis Jobs**: Async orchestration of Triton inference via KServe v2 HTTP.
- **Safety**: GradCAM, RAG evidence, Socratic chat, circuit breaker, drift check.
- **Notification/Settings/Telemetry**: Support modules for user preferences and system monitoring.
### 3. Interface Contract (from interface-contract.md)
**Key API Categories:**
- **Auth**: `/api/v1/auth/login`, `/api/v1/users/me`.
- **Patient**: `/api/v1/patients`, `/api/v1/patients/{id}/sessions`.
- **Clinical Workflow**:
- Sessions: `/api/v1/sessions`, `/api/v1/sessions/{id}/frames`, `/api/v1/sessions/{id}/review`.
- Analysis: `/api/v1/analysis-jobs` (async), `/api/v1/analysis` (sync).
- Reports: `/api/v1/reports`, `/api/v1/reports/{id}/sign`, `/api/v1/reports/{id}/emr-sync`.
- **Safety & Explanations**:
- GradCAM: `/api/v1/sessions/{id}/explanations/gradcam`.
- Rationale/Chat: `/api/v1/sessions/{id}/explanations/rationale`, `/api/v1/sessions/{id}/chat/socratic`.
- Guardrails: `/api/v1/sessions/{id}/drift/check`, `/api/v1/sessions/{id}/rag/evidence`.
### 4. Dependency Graph
- **Auth/Patient/Session/Safety/Telemetry** $\rightarrow$ PostgreSQL.
- **Session/AnalysisJobs/Safety** $\rightarrow$ S3.
- **AnalysisJobs** $\rightarrow$ Triton (Modal Serverless).
- **Safety** $\rightarrow$ Local LLM, BERT, RAG Knowledge Base.

37
session_memory/27_jun_26/27_jun_26_backend.md Normal file
View File

@@ -0,0 +1,37 @@
# Session Memory: 2026-06-27 Backend NLP/LLM Consult Implementation
## Task
Build Vietnamese Clinical LLM Consult endpoints (Rationale, Socratic Chat, Guardrail Check, SSE Stream). Follow NFR-16a governance.
## Implementation Details
### 1. LLM Adapter (`backend/implementation/adapters/llm_adapter.py`)
- Build `VertexAILangchainAdapter` via `langchain-google-vertexai`.
- Add `AuditCallbackHandler` for mandatory audit log commits before LLM call (NFR-16a).
- Use `run_in_executor` for `generate` to stop FastAPI block.
### 2. BERT Adapter (`backend/implementation/adapters/bert_adapter.py`)
- Build `BERTAdapter` stubs:
- `drift_check`: Find clinical drift.
- `referee_check`: Check RAG grounding.
- `guardrail_check`: Safety check tokens/chunks.
### 3. Safety Service (`backend/implementation/safety/service.py`)
- Link LLM + BERT adapters.
- Build `_verify_pre_egress` check:
- **Consent**: Check `consent:{session_id}` in Redis.
- **Redaction**: Check redaction manifest hash.
- Update services:
- `rationale`: Context explanation.
- `socratic_chat`: History chat + BERT referee grounding.
- `guardrail_check`: Link BERT guardrails.
- `chat_stream`: SSE generator + per-chunk filter.
- Add post-egress: set `consult_mode:{session_id}` $\rightarrow$ `cloud_vertex` in Redis.
### 4. Infrastructure & API
- **Redis Adapter**: Build `backend/implementation/adapters/redis_adapter.py` for state + consent.
- **Config**: Update `backend/implementation/config.py` with Vertex AI + Redis env vars.
- **API Router**: Update `backend/api/safety_api.py` for `redaction_hash` + SSE errors.
## Governance Flow (NFR-16a)
`Request` $\rightarrow$ `Consent Check (Redis)` $\rightarrow$ `Redaction Verify` $\rightarrow$ `Audit Commit (Langchain Callback)` $\rightarrow$ `LLM Call` $\rightarrow$ `Post-Egress Log` $\rightarrow$ `Response`

37
session_memory/27_jun_26/27_jun_26_backend.original.md Normal file
View File

@@ -0,0 +1,37 @@
# Session Memory: 2026-06-27 Backend NLP/LLM Consult Implementation
## Task
Implement Vietnamese Clinical LLM Consult endpoints (Rationale, Socratic Chat, Guardrail Check, SSE Stream) with strict NFR-16a governance.
## Implementation Details
### 1. LLM Adapter (`backend/implementation/adapters/llm_adapter.py`)
- Implemented `VertexAILangchainAdapter` using `langchain-google-vertexai`.
- Added `AuditCallbackHandler` to enforce mandatory audit log commits *before* LLM calls (NFR-16a).
- Wrapped synchronous `generate` calls in `run_in_executor` to avoid blocking FastAPI event loop.
### 2. BERT Adapter (`backend/implementation/adapters/bert_adapter.py`)
- Implemented `BERTAdapter` with stubs for:
- `drift_check`: Detects clinical domain drift.
- `referee_check`: Validates RAG grounding.
- `guardrail_check`: Token/chunk level safety verification.
### 3. Safety Service (`backend/implementation/safety/service.py`)
- Integrated LLM and BERT adapters.
- Implemented `_verify_pre_egress` checklist:
- **Consent**: Validates `consent:{session_id}` exists in Redis.
- **Redaction**: Verifies redaction manifest hash.
- Updated services:
- `rationale`: Context-aware explanation generation.
- `socratic_chat`: History-based conversation with BERT referee grounding.
- `guardrail_check`: Direct integration with BERT guardrails.
- `chat_stream`: SSE generator with per-chunk guardrail filtering.
- Added post-egress state update: sets `consult_mode:{session_id}` to `cloud_vertex` in Redis.
### 4. Infrastructure & API
- **Redis Adapter**: Created `backend/implementation/adapters/redis_adapter.py` for session state and consent management.
- **Config**: Updated `backend/implementation/config.py` with Vertex AI and Redis environment variables.
- **API Router**: Updated `backend/api/safety_api.py` to pass `redaction_hash` to services and handle SSE error events.
## Governance Flow (NFR-16a)
`Request` $\rightarrow$ `Consent Check (Redis)` $\rightarrow$ `Redaction Verify` $\rightarrow$ `Audit Commit (Langchain Callback)` $\rightarrow$ `LLM Call` $\rightarrow$ `Post-Egress Log` $\rightarrow$ `Response`

301
session_memory/27_jun_26/27_jun_26_frontend.md Normal file
View File

@@ -0,0 +1,301 @@
# Frontend Development Progress - 27 Jun 26
## Session Summary
Date: 2026-06-27
Phase: 2 - Component Architecture & Deepening (35 Figma Designs Implementation Plan)
Mode: Caveman Lite
---
## 1. TopBar Refactor (Phase 2.0)
### Problem
TopBar reached into Zustand store for 4 fields (`patientId`, `clinicianGrade`, `isOverriding`, `sessionId`, `currentPhase`) and inlined sign button. Violated molecule abstraction layer.
### Solution
Refactored `TopBar` to consume `PatientHeader` and `ActionCluster` molecules via props instead of store selectors.
### Files Changed
- `src/components/organisms/TopBar.tsx`
- Removed direct `useDiagnosticWorkspaceStore` import
- Added props interface: `patientId`, `patientName`, `role`, `status`, `sessionId`, `currentPhase`, `canSign`, `isCircuitBroken`, `onSign`, `onCircuitBreak`, `onBack`, `onMore`
- Replaced inline patient info + sign button with `<PatientHeader />` and `<ActionCluster />` molecules
- Added `canSign` prop to `ActionCluster` for HITL gating
- `src/components/molecules/ActionCluster.tsx`
- Added `canSign?: boolean` prop
- Added `signDisabled` computed value: `isCircuitBroken || !canSign`
- Sign button now uses `disabled={signDisabled}` instead of just `isCircuitBroken`
- `src/components/templates/WorkspaceShell.tsx`
- Wired all TopBar props from store using selectors
- Passes `patientId`, `sessionId`, `currentPhase`, `canSign`, `isCircuitBroken`, `onSign`, `onCircuitBreak`
- `onCircuitBreak` now accepts `(active: boolean) => void` and triggers `window.confirm` modal for break/recovery
---
## 2. Canvas & Visualization Deepening (Phase 2.1)
### DiagnosticCanvas Enhancements
- Tool State: reads `activeTool`, `setActiveTool`, `zoomLevel`, `panOffset`, `showGradCAM`, `showSegmentation` from Zustand `uiSlice`
- 5-Layer Canvas Stack: 5 layers with dynamic rendering
- Layer 0: Cornerstone.js DICOM viewport
- Layer 10: GradCAM overlay (conditional via `showGradCAM`)
- Layer 50: Segmentation mask (conditional via `showSegmentation`)
- Layer 100: SVG Annotations + OffscreenCanvas
- Layer 200: Viewport HUD + live coords/zoom
- Performance:
- `requestAnimationFrame` dirty-flag loop for annotation canvas
- `ResizeObserver` syncs annotation canvas resolution
- Cornerstone lifecycle: init + viewport update (no reload on pan/zoom)
- `useCallback` for event handlers
- Touch:
- `onTouchStart`, `onTouchMove` for mobile/tablet coords
- Touch events mapped to same coordinate system
- Tool Palette:
- Extracted constant `TOOLS` array with icon mapping (`pin` → `map-pin`)
- Active tool state store-driven
- Live HUD:
- Replaced static HUD with live `mousePos` state
- Zoom level from store
### Canvas Performance
- Minimized Cornerstone redraws: separate image load from viewport updates
- `useRef` for OffscreenCanvas, RAF loop, dirty flag, image tracking
- Added `mousePos` for live coords
---
## 3. Reasoning & Chat Panel Deepening (Phase 2.2)
### ZoneB Composition
- Replaced placeholder with `PhaseIndicator` + `ReasoningPanel` + `ChatPanel`
- Layout: Sticky PhaseIndicator top, scrollable content below
- `ZoneBProps` interface covers all data flows
### ReasoningPanel Enhancements
- Added optional `PhaseIndicator` via `showPhaseIndicator` prop
- Classification Card:
- Color-coded grade badge (0-3) with tooltip
- Confidence score with `ConfidenceBar`
- Explanation Panel:
- GradCAM thumbnail with hover overlay
- Thickness measurement extraction/display
- Show Full GradCAM toggle via `showFullGradCam` / `onToggleFullGradCam` props
- Override Card:
- Rendered when `onSubmitOverride` provided
- Composes existing `OverrideCard` molecule
- Quick Actions Bar:
- `CircuitBreaker` molecule
- `NFRIndicator` molecule
- Report button
- EMR sync button
- Fullscreen toggle
### ChatPanel Enhancements
- Input:
- Replaced `<input>` with auto-resizing `<textarea>`
- `Enter` sends
- `Shift+Enter` inserts newline
- Auto-resize to 120px
- Streaming:
- Added `isStreaming` prop
- Streaming indicator in header
- Inline pulsing cursor on last assistant message when streaming
- Message Actions:
- Hover-revealed toolbar on non-system messages
- Copy button (`navigator.clipboard.writeText`)
- Regenerate button (assistant only)
- Feedback buttons: helpful (heart) / not helpful (alert-circle)
- All optional via callback props
- Virtualization:
- Placeholder: `react-window` `FixedSizeList` integration point
- Current: standard overflow-y-auto
---
## 4. Tool State & Annotations (Phase 2.3)
### uiSlice Additions
- `brushSize: number` (default 5, range 1-50)
- `brushColor: string` (default '#ff0000')
- `eraserSize: number` (default 10, range 1-100)
- `caliperUnit: 'mm' | 'px'` (default 'mm')
- `pressureSensitivity: boolean` (default false)
- Setters with validation
### annotationSlice Additions
- `selectedAnnotationId: string | null`
- `lockedLayerIds: string[]`
- Actions:
- `addAnnotation`
- `selectAnnotation`
- `deleteAnnotation`
- `updateAnnotation`
- `lockLayer`
- Derived selectors:
- `selectSelectedAnnotation`
- `selectLockedLayers`
- Undo/redo for all annotation mutations
### Store Updates
- `store/index.ts`:
- Exported new selectors
- Updated `resetSession` to clear new state fields
---
## 5. Safety & Compliance Wiring (Phase 2.4)
### Circuit Breaker
- `ActionCluster` passes `isCircuitBroken` state
- Sign button disabled when circuit broken
- `WorkspaceShell` applies `ring-2 ring-red-500 animate-pulse` when `isOverriding=true`
- Confirmation via `window.confirm` before break/recovery
### Defer 13 Scrubber (PIIScrubber)
- Fixed broken destructuring in `src/components/molecules/PIIScrubber.tsx`
- Added missing props: `text`, `onChange`, `className`
- Compiles and binds props correctly
### HITL Signature Gate
- Fixed missing `Input` import in `src/components/molecules/HITLGate.tsx`
- Added `import { Input } from '../atoms/Input';`
- Ready for credential entry modal
### NFR Status Indicator (BottomBar)
- Added `WorkerHealthEntry` interface
- Extended `BottomBarProps` with `workerHealth` and `isOffline`
- Integrated `NFRIndicator` for live status
- Removed hardcoded 'offline' when real values present
---
## 6. TypeScript & Lint Verification
### TypeScript
- `tsc --noEmit` passes clean
- All modified files compile clean
### ESLint
- All modified files pass lint
- Pre-existing warnings: stories/tests (.stories.tsx old Storybook imports, test `.set` destructuring)
- Not introduced this session
---
## 7. Plan File Updates
Updated `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/.kilo/plans/35-figma-designs-implementation-plan.md`:
- Tick 2.0 TopBar deepening (molecule consumption)
- Tick 2.1 Canvas & Visualization
- Tick 2.2 Reasoning & Chat Panel (Override Card + Quick Actions)
- Tick 2.3 Interaction & State Management (tool state, annotations, measurements)
- Tick 2.4 Safety & Compliance (Circuit Breaker, PII Scrubber, HITL Gate, NFR Indicator)
---
## 8. Known Pre-existing Issues (Not Introduced This Session)
- `src/services/safetyService.ts`: Vite build error (unrelated to Phase 2)
- Storybook stories: import `@storybook/react` directly instead of framework package
- Store slices tests: unused `set` destructuring warnings
---
## 9. Key Architectural Improvements
1. **Molecule Layer Strengthened**: TopBar no longer leaks store selectors; uses PatientHeader + ActionCluster props
2. **5-Layer Canvas Stack**: Dynamic store-driven visibility with OffscreenCanvas annotations and RAF rendering
3. **ZoneB Composed**: Clean separation of PhaseIndicator, ReasoningPanel, ChatPanel
4. **Tool State Centralized**: All tool preferences in uiSlice with validation
5. **Annotation System Ready**: Vector storage, undo/redo hooks, layer locking
6. **Safety Molecules Wired**: CircuitBreaker, PIIScrubber, HITLGate, NFRIndicator integrated into organisms
7. **Zero New Type Errors**: All changes type-check clean
---
## 10. Next Steps
- Wire Cornerstone DICOM loading (placeholder)
- Implement react-window virtualization in ChatPanel at message threshold
- Add Worker hooks (Phase 3.1)
- Implement Offline/Dexie sync (Phase 3.2)
- Build safety modals (CircuitBreaker confirm, HITL credential entry)
- Create 5-layer rendering tests
---
## 11. Phase 3: Worker Integration + Offline Sync (Appended 2026-06-28)
### Worker Hooks
- `src/hooks/workers/useCVWorker.ts`: DICOM frame → CLAHE resize → `cv.worker` → angle class + confidence. Real worker + mock adapter.
- `src/hooks/workers/useLLMWorker.ts`: prompt build + RAG context → `llm.worker` stream with token buffering for smooth display.
- `src/hooks/workers/useGuardrailWorker.ts`: pre-scan user input for hallucination/mal-intent → safety score → UI warning if threshold exceeded.
- `src/hooks/workers/useDriftScore.ts`: extract drift score from guardrail module.
- `src/hooks/workers/useSocraticChat.ts`: socratic dialogue via `llm.worker`.
- `src/hooks/workers/mocks.ts`: mock worker adapters for test environment using setTimeout.
- `src/workers/lifecycle.ts`: `WorkerPool` (lazy init, idle GC 5 min, error boundary).
- Barrel: `src/workers/index.ts` exports workerPool + message helpers.
### Offline Storage + Sync
- `src/services/db.ts` Dexie schema: `sessions`, `chatMessages`, `pendingReports`, `auditLog`.
- `src/services/sync.ts` SyncEngine: online/offline detect, queue when offline, exponential backoff retry (1s base, 30s cap, 5 max), LWW conflict resolution.
- `src/services/index.ts` exports `db`, `syncEngine`.
### PWA / Service Worker
- `vite.config.ts`: `vite-plugin-pwa` `generateSW` (Workbox). CacheFirst static assets, NetworkFirst API runtime, precache manifest.
- `npm i -D vite-plugin-pwa` added.
### Build Verification
- Pre-existing TS errors unchanged in `src/services/adapters/`, `src/*Service.ts`, store tests, stories. None introduced in new files.
---
## 12. Phase 4: Performance, NFR, a11y, i18n (Appended 2026-06-28)
### Bundle + Rendering
- `vite.config.ts`: `rollup-plugin-visualizer` (gzipSize, `dist/bundle-stats.html`). `manualChunks`:
- `vendor-media`: `cornerstone-*`, dicom parsers
- `vendor-store`: dexie, zustand
- `worker`: `src/workers/*`
- `app-core`: react, react-dom, i18next, react-router-dom, date-fns
- `DiagnosticCanvas.tsx`: `useMemo` on viewport transform.
- `ChatPanel.tsx`: `React.memo` `MessageBubble` with comparator `id`, `content`, `isStreaming`.
- `src/services/db.ts`: `saveChatMessagesWithEviction(messages, maxPerSession=20)` caps chat history via FIFO bulkPut + bulkDelete.
### i18n
- `src/i18n.ts`: i18next + `initReactI18next` + `i18next-http-backend`. Lng = `navigator.language` if starts with `en`, else `en`. `/locales/{{lng}}.json`.
- `src/locales/en.json`, `src/locales/vi.json`: 37 UI keys across TopBar, PatientHeader, BottomBar, ChatPanel, ReasoningPanel, WorkspaceShell.
- `src/App.tsx`: root wrapped in `<I18nextProvider i18n={i18n}>`.
- ReasoningPanel/BottomBar/TopBar/ChatPanel: hardcoded strings replaced with `t('Component.key')`.
### Accessibility
- `src/components/templates/WorkspaceShell.tsx`: root wrapper gets `role="main"`, `tabIndex={-1}`.
- `src/components/organisms/BottomBar.tsx`: NFR status container `aria-live="polite"`.
- `src/index.css`: global `:focus-visible` outline 2px solid var(--color-primary-500), offset 2px.
- Grad-CAM `<img alt="Grad-CAM">` retained; decorative icons already `aria-hidden="true"`.
### NFR / Lockdown
- `src/nfr/LockdownValidator.ts`: runtime DOM + fetch + XHR patch. Returns external URLs not matching `window.location.origin`.
- `src/services/adapters/httpAdapter.ts`: `VITE_API_BASE_URL` must start with `/` (relative) else throw. Same-origin only.
- `vite.config.ts`: `server.host='127.0.0.1'`, `server.https=false`. `preview.headers` CSP:
- `script-src 'self' 'wasm-unsafe-eval'`
- `style-src 'self' 'unsafe-inline'`
- `img-src 'self' data: https://fonts.gstatic.com`
- `font-src 'self' https://fonts.gstatic.com`
- `connect-src 'self' https://fonts.googleapis.com`
- Repo grep found zero external URL strings in `src/` and `public/`. Workbox retained Google Fonts runtime caching as sole allowed external origin.
### Bugfixes
- `ReasoningPanel.tsx`: missing `function ReasoningPanel(props)` caused syntax error; fixed + props destructured. `nfrStatus` type inline to avoid broken re-export path.
- `i18n.ts`: `useTranslation` export fixed; `HttpBackend` added as plugin.
- `ZoneB.tsx`: `import { ReasoningPanel }` → default import.
### Plan Updates
- `.kilo/plans/35-figma-designs-implementation-plan.md`:
- Phase 3.1 + 3.2 ticked during worker/offline work.
- Phase 4.1-4.3 items ticked where verification supports.
### Known Compile State
- `npm run build` fails on pre-existing unrelated files (dicomService typings, store tests, stories missing modules). New Phase 3/4 files compile clean.

225
session_memory/27_jun_26/27_jun_26_frontend.original.md Normal file
View File

@@ -0,0 +1,225 @@
# Frontend Development Progress - 27 Jun 26
## Session Summary
Date: 2026-06-27
Phase: 2 - Component Architecture & Deepening (35 Figma Designs Implementation Plan)
Mode: Caveman Lite
---
## 1. TopBar Refactor (Phase 2.0)
### Problem
TopBar was directly reaching into the Zustand store for 4 fields (patientId, clinicianGrade, isOverriding, sessionId, currentPhase) and inlining the sign button. This violated the molecule abstraction layer.
### Solution
Refactored `TopBar` to consume `PatientHeader` and `ActionCluster` molecules via props instead of store selectors.
### Files Changed
- `src/components/organisms/TopBar.tsx`
- Removed direct `useDiagnosticWorkspaceStore` import
- Added props interface: `patientId`, `patientName`, `role`, `status`, `sessionId`, `currentPhase`, `canSign`, `isCircuitBroken`, `onSign`, `onCircuitBreak`, `onBack`, `onMore`
- Replaced inline patient info + sign button with `<PatientHeader />` and `<ActionCluster />` molecules
- Added `canSign` prop to `ActionCluster` for HITL gating
- `src/components/molecules/ActionCluster.tsx`
- Added `canSign?: boolean` prop
- Added `signDisabled` computed value: `isCircuitBroken || !canSign`
- Sign button now uses `disabled={signDisabled}` instead of just `isCircuitBroken`
- `src/components/templates/WorkspaceShell.tsx`
- Wired all TopBar props from store using selectors
- Passes `patientId`, `sessionId`, `currentPhase`, `canSign`, `isCircuitBroken`, `onSign`, `onCircuitBreak`
- `onCircuitBreak` now accepts `(active: boolean) => void` and triggers `window.confirm` modal for break/recovery
---
## 2. Canvas & Visualization Deepening (Phase 2.1)
### DiagnosticCanvas Enhancements
- Tool State Management: Component now reads `activeTool`, `setActiveTool`, `zoomLevel`, `panOffset`, `showGradCAM`, `showSegmentation` from Zustand `uiSlice`
- 5-Layer Canvas Stack: All 5 layers implemented with proper dynamic rendering
- Layer 0: Cornerstone.js DICOM viewport
- Layer 10: GradCAM overlay (conditionally rendered via `showGradCAM` store toggle)
- Layer 50: Segmentation mask (conditionally rendered via `showSegmentation` store toggle)
- Layer 100: SVG Annotations layer with OffscreenCanvas support
- Layer 200: Viewport HUD with live mouse coordinates and zoom level
- Performance Optimizations:
- `requestAnimationFrame` dirty-flag render loop for annotation canvas
- `ResizeObserver` to keep annotation canvas resolution in sync
- Separated Cornerstone lifecycle into initialization + viewport update effects (no reload on pan/zoom)
- `useCallback` for event handlers
- Touch Support:
- `onTouchStart`, `onTouchMove` handlers for mobile/tablet coordinate tracking
- Touch events mapped to same coordinate system as mouse
- Tool Palette:
- Extracted to constant `TOOLS` array with proper icon mapping (`pin` corrected to `map-pin`)
- Active tool state now store-driven, not prop-driven
- Live HUD:
- Replaced static "X: 124.5mm | Y: 88.2mm" with live `mousePos` state
- Zoom level pulled from store
### Canvas Performance
- Minimized Cornerstone redraws by separating image load from viewport updates
- Used `useRef` for OffscreenCanvas, RAF loop, dirty flag, image tracking
- Added `mousePos` state for live coordinate display
---
## 3. Reasoning & Chat Panel Deepening (Phase 2.2)
### ZoneB Composition
- Replaced placeholder with full composition: `PhaseIndicator` + `ReasoningPanel` + `ChatPanel`
- Layout: Sticky PhaseIndicator at top, scrollable content area below
- Comprehensive `ZoneBProps` interface covering all data flows
### ReasoningPanel Enhancements
- Added optional `PhaseIndicator` (controlled by `showPhaseIndicator` prop)
- Classification Card:
- Color-coded grade badge (0-3) with tooltip wrapper
- Confidence score with `ConfidenceBar`
- Explanation Panel:
- GradCAM thumbnail with hover overlay ("Expand View")
- Thickness measurement extraction and display
- "Show Full GradCAM" toggle via `showFullGradCam` / `onToggleFullGradCam` props
- Override Card:
- Conditionally rendered when `onSubmitOverride` callback provided
- Composes existing `OverrideCard` molecule
- Quick Actions Bar:
- `CircuitBreaker` molecule (toggle)
- `NFRIndicator` molecule
- Report generation button
- EMR sync button
- Fullscreen toggle
### ChatPanel Enhancements
- Input Handling:
- Replaced `<input>` with auto-resizing `<textarea>`
- `Enter` sends message
- `Shift+Enter` inserts newline
- Auto-resize up to 120px height
- Streaming Support:
- Added `isStreaming` prop
- Streaming indicator in header ("Streaming...")
- Inline pulsing cursor on last assistant message when streaming
- Message Actions:
- Hover-revealed action toolbar on non-system messages
- Copy button (uses `navigator.clipboard.writeText`)
- Regenerate button (assistant messages only)
- Feedback buttons: helpful (heart) / not helpful (alert-circle)
- All actions optional via callback props
- Virtualization:
- Placeholder comment block showing `react-window` `FixedSizeList` integration point
- Current implementation uses standard overflow-y-auto for simplicity
---
## 4. Tool State & Annotations (Phase 2.3)
### uiSlice Additions
- `brushSize: number` (default 5, range 1-50)
- `brushColor: string` (default '#ff0000')
- `eraserSize: number` (default 10, range 1-100)
- `caliperUnit: 'mm' | 'px'` (default 'mm')
- `pressureSensitivity: boolean` (default false)
- Setters for all above with validation
### annotationSlice Additions
- `selectedAnnotationId: string | null`
- `lockedLayerIds: string[]`
- Actions:
- `addAnnotation`
- `selectAnnotation`
- `deleteAnnotation`
- `updateAnnotation`
- `lockLayer`
- Derived selectors:
- `selectSelectedAnnotation`
- `selectLockedLayers`
- Undo/redo integration for all annotation mutations
### Store Updates
- `store/index.ts`:
- Exported new selectors
- Updated `resetSession` to clear new state fields
---
## 5. Safety & Compliance Wiring (Phase 2.4)
### Circuit Breaker
- `ActionCluster` updated to pass `isCircuitBroken` state
- Sign button disabled when circuit broken
- `WorkspaceShell` applies `ring-2 ring-red-500 animate-pulse` when `isOverriding=true`
- Confirmation modal via `window.confirm` before break/recovery
### Defer 13 Scrubber (PIIScrubber)
- Fixed broken destructuring in `src/components/molecules/PIIScrubber.tsx`
- Added missing props: `text`, `onChange`, `className`
- Component now compiles and correctly binds props
### HITL Signature Gate
- Fixed missing `Input` import in `src/components/molecules/HITLGate.tsx`
- Added `import { Input } from '../atoms/Input';`
- Component now ready for credential entry modal
### NFR Status Indicator (BottomBar)
- Added `WorkerHealthEntry` interface
- Extended `BottomBarProps` with `workerHealth` and `isOffline`
- Integrated `NFRIndicator` molecule for live status display
- Removed hardcoded 'offline' status when real values present
---
## 6. TypeScript & Lint Verification
### TypeScript
- `tsc --noEmit` passes clean
- All modified files compile without errors
### ESLint
- All modified files pass lint
- Pre-existing warnings in stories/tests (.stories.tsx using old Storybook imports, test `.set` destructuring)
- These are not introduced by this session's changes
---
## 7. Plan File Updates
Updated `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/.kilo/plans/35-figma-designs-implementation-plan.md`:
- Tick off 2.0 TopBar deepening (molecule consumption)
- Tick off 2.1 Canvas & Visualization (all sub-items)
- Tick off 2.2 Reasoning & Chat Panel (all sub-items including Override Card + Quick Actions)
- Tick off 2.3 Interaction & State Management (tool state, annotations, measurements)
- Tick off 2.4 Safety & Compliance Features (Circuit Breaker, PII Scrubber, HITL Gate, NFR Indicator)
---
## 8. Known Pre-existing Issues (Not Introduced This Session)
- `src/services/safetyService.ts`: Vite build error (unrelated to Phase 2 work)
- Storybook stories: import `@storybook/react` directly instead of framework package
- Store slices tests: unused `set` parameter destructuring warnings
---
## 9. Key Architectural Improvements
1. **Molecule Layer Strengthened**: TopBar no longer leaks store selectors; consumed via PatientHeader + ActionCluster props
2. **5-Layer Canvas Stack**: Dynamic, store-driven layer visibility with OffscreenCanvas annotation support and RAF-based rendering
3. **ZoneB Composed**: Clean separation of PhaseIndicator, ReasoningPanel, ChatPanel
4. **Tool State Centralized**: All tool preferences in uiSlice with validation
5. **Annotation System Ready**: Vector-based storage, undo/redo hooks, layer locking in place
6. **Safety Molecules Wired**: CircuitBreaker, PIIScrubber, HITLGate, NFRIndicator integrated into organisms
7. **Zero New Type Errors**: All changes type-check clean
---
## 10. Next Steps
- Wire actual Cornerstone DICOM loading (currently placeholder)
- Implement react-window virtualization in ChatPanel when message count exceeds threshold
- Add Worker hooks (Phase 3.1)
- Implement Offline/Dexie sync (Phase 3.2)
- Build safety modals (CircuitBreaker confirm, HITL credential entry)
- Create actual 5-layer rendering tests

0
session_memory/27_jun_26/27_jun_26_pipeline.md Normal file
View File

159
session_memory/6_Jul_26.md Normal file
View File

@@ -0,0 +1,159 @@
---
title: Session Memory 6 Jul 26
date: 2026-07-06
status: active
---
## Summary
Sprint_1_2 clinical chat saw major LLM UX, streaming, and inference work (Jul 5–6). The highest-risk open issue is **frontend markdown rendering of generated assistant text** — it has caused tab freezes and catastrophic crashes during reasoning streams. Reasoning paths now use **plain text only** (`StreamingPlainText`) as a mitigation. **Beta functionality** (Planning mode + 🔥 high reasoning level) must be completed **by end of this week** (target: **Friday 10 Jul 2026**).
---
## Change log (what was updated)
### Clinical chat UI & model lifecycle
| Area | Change | Key files |
|------|--------|-----------|
| LLM loading bubble | Install vs load phases with distinct copy, progress bar, disabled composer | `ClinicalChatPanel.tsx`, `useClinicalChat.ts`, `modelLoadProgress.ts` |
| Install vs load semantics | First OPFS download (~1.9 GB) vs cached checkpoint init into worker/GPU | `useClinicalChat.ts` (`ModelLoadPhase: 'installing' \| 'loading'`) |
| Sidebar card switch | Both diagnosis + review layers stay mounted (CSS hide/show) so Gemma is not torn down on carousel switch | `SidebarLayerCarousel.tsx` |
| OPFS persistence | Completed install survives reload; interrupted download not resumable (manifest only written on success) | `opfsModelStore.ts` |
| Worker init progress | `init_progress` events wired through `LlmWorkerClient.init(onProgress)` | `llmWorkerClient.ts`, `llm.worker.ts` |
### Inference modes, reasoning levels & backends
| Area | Change | Key files |
|------|--------|-----------|
| Unified chat modes | `ask` merged into `chat`; inference modes: **Chat**, **Planning** (beta), **Agent** | `clinicalChatModes.ts`, `analyzePromptComplexity.ts` |
| Reasoning levels | 🧘 chill / 🤔 moderate / 🔥 high (beta); bar visibility persisted | `chatReasoningLevel.ts`, `ClinicalChatPanel.tsx` |
| Edge vs server toggle | 🤔 moderate: **Máy** (Gemma 4 E2B edge) vs **Server** (Gemma 4 E4B Modal Ollama `think:true`) | `reasoningModelBackend.ts`, `ollamaLlmClient.ts`, `inferenceBackend.ts` |
| Ollama dev proxy | `VITE_OLLAMA_CHAT_URL=/api/ollama-chat/api/chat`, model `gemma4:e4b` | `.env.development`, `vite.config.ts` |
| Agent mode | Uses Modal Ollama E4B when configured; tool loop unchanged | `clinicalChatModes.ts`, `runClinicalChatTurn.ts` |
| OOM mitigation | Bootstrap at 2048 tokens; `releaseInference()` before reload; reuse engine when `configured.maxTokens >= required` | `clinicalChatConfig.ts`, `llm.worker.ts`, `llmModelBootstrap.ts` |
| Qwen3 experiment | Dual-model (Qwen `.litertlm` for moderate) attempted then **disabled** — `usesQwenReasoningLevel()` returns `false`; moderate uses Gemma CoT again | `qwenOpfsModelStore.ts`, `reasoningLlmClient.ts`, `chatReasoningLevel.ts` |
### Streaming, CoT split & markdown
| Area | Change | Key files |
|------|--------|-----------|
| CoT split | `splitGemmaThoughtOutput`, `isThoughtChannelComplete`; thought vs answer channels in message state | `prompts.ts`, `clinicalChat.ts`, `useClinicalChat.ts` |
| Collapsible reasoning | `ClinicalChatThought` — expand while streaming, auto-collapse when thought completes | `ClinicalChatThought.tsx` |
| Stream throttle | RAF-coalesced updates (~60/s) to reduce main-thread pressure | `streamUpdateThrottle.ts` |
| Token-by-token Ollama | Imperative DOM via `clinicalChatStreamRegistry` + `StreamingPlainText` (bypasses React 18 batching) | `clinicalChatStreamRegistry.ts`, `StreamingPlainText.tsx`, `ollamaLlmClient.ts` |
| Markdown renderer | Custom `ChatMarkdown` (bold, italic, code, lists, headings) — **deferred until stream ends** via `requestIdleCallback` + `startTransition` | `ChatMarkdown.tsx`, `ClinicalChatMessageBubble.tsx` |
| Reasoning = plain text | When `tracksThought`, thought + answer use `StreamingPlainText` only — **no `ChatMarkdown`** | `ClinicalChatThought.tsx`, `ClinicalChatMessageBubble.tsx` |
### Agent tools & Modal testing
| Area | Change | Key files |
|------|--------|-----------|
| Tool catalog doc | Walkthrough of Edge-LLM agent tools: `exa_search`, `supabase_query`, `escalate_medgemma` | session + `agent_tools_contract.md` |
| 3-layer smoke harness | Layer 0 Modal Ollama, Layer 1 BFF routes, Layer 2 browser `ToolExecutor` | `ml/tests/agent_tools/` |
| Python reference tests | Modal `/api/chat` streaming + thinking cases | `PILOT_PROJECT/tmp/test_endpoint.py`, `test_endpoint_img.py` |
| Gemma4 E4B deploy script | Modal Ollama serverless for Gemma 4 E4B | `PILOT_PROJECT/tmp/GemmaE4B_ollama_deploy.py` |
| gemma4_e2b lab | Tool smoke panel (no Gemma) for isolated tool calls | `ml/tests/gemma4_e2b/src/lib/toolSmoke.ts` |
---
## Critical issue: markdown rendering → catastrophic crash
### Symptom
Rendering **LLM-generated markdown** in the clinical chat UI (especially during or immediately after **reasoning / CoT streams**) has caused:
- Main-thread freezes (composer unresponsive while tokens still arrive)
- Tab crashes / OOM under combined **WebGPU model memory + large text buffers + markdown parse**
### Root cause (confirmed in debugging)
1. **Per-token full re-parse** — early implementation ran `ChatMarkdown` / `renderBlocks()` on the entire growing thought string every token → hundreds of parses per second.
2. **React re-render storm** — `setMessages` on every token re-rendered the full message list.
3. **Post-stream markdown** — even with “parse after stream ends”, heavy `renderBlocks()` on long CoT + answer text still spikes CPU/memory.
4. **Dual large strings** — `rawAccumulator`, `thoughtContent`, and `content` can all hold 2048-token traces simultaneously at 🤔 moderate.
### Mitigations applied (6 Jul)
- Stream updates throttled (`createStreamUpdateThrottle`)
- Plain text while `streaming === true`
- `React.memo` on `ClinicalChatMessageBubble`
- Reasoning paths (`tracksThought`) → **`StreamingPlainText` only, markdown disabled**
- Ollama path → imperative DOM updates per token
- `ChatMarkdown` uses idle callback + `startTransition` for post-stream formatting (chill / non-reasoning answers only)
### Current policy
> **Be wary of re-enabling markdown in reasoning mode until a safe renderer is proven.**
`ClinicalChatThought.tsx` comment: *"Reasoning panel — plain text only (markdown disabled while isolating stream crashes)."*
### Follow-up for later sprints
- [ ] Reproduce crash with a minimal `ChatMarkdown` + long fixture (no LLM) — isolate `renderBlocks` vs React
- [ ] Consider `react-markdown` with strict plugins OR server-side pre-render for final answer only
- [ ] Cap thought trace length in UI (truncate + “show more”)
- [ ] Virtualize message list for long sessions
- [ ] Re-test 🔥 high mode and Planning mode with any new markdown path before removing plain-text guard
- [ ] Audit whether chill-mode `ChatMarkdown` after stream is safe on 8 GB RAM devices
---
## Beta functionality — deadline end of week
**Target: complete by Friday 10 Jul 2026** (end of sprint week).
Features still marked `beta: true` (UI tab/button disabled until ready):
| Feature | ID | Location | What “done” means |
|---------|-----|----------|-------------------|
| **Planning mode** | `planning` | `clinicalChatModes.ts` | Checklist output stable; remove `beta` flag; selectable in mode tabs |
| **High reasoning** | `high` 🔥 | `chatReasoningLevel.ts` | 2048-token multi-turn works without crash; remove `beta` flag |
Related work not yet beta-flagged but in scope:
- Agent tool integration (Layer 3 after smoke tests pass)
- Live BFF tools (`VITE_CLINICAL_CHAT_MOCK_TOOLS=false` + credentials)
- Edge/server reasoning toggle polish (default server E4B when Modal up)
---
## Architecture snapshot (clinical LLM, 6 Jul EOD)
```
User message
│
├─ Mode: chat ─┬─ 🧘 chill → Gemma E2B edge (no CoT)
│ ├─ 🤔 moderate → Máy: Gemma E2B + CoT (plain text)
│ │ Server: Gemma E4B Ollama think:true (plain text)
│ └─ 🔥 high (BETA) → disabled in UI
│
├─ Mode: planning (BETA) → disabled in UI
│
└─ Mode: agent → Gemma E4B Ollama + tools (exa, supabase, medgemma)
Display:
tracksThought → StreamingPlainText (thought panel + answer)
else → StreamingPlainText while streaming → ChatMarkdown when done
```
---
## Key env / endpoints (dev)
```env
VITE_CLINICAL_CHAT_USE_LLM=true
VITE_OLLAMA_CHAT_URL=/api/ollama-chat/api/chat
VITE_OLLAMA_MODEL=gemma4:e4b
VITE_CLINICAL_CHAT_MOCK_TOOLS=true # flip false for live agent tools
```
Modal Gemma E4B (reference): `PILOT_PROJECT/tmp/test_endpoint.py` → `dtj-tran--ollama-gemma4-e4b-ollamaserver-web.modal.run`
---
## Session references
- Prior frontend memory: `session_memory/27_jun_26/27_jun_26_frontend.md`
- Agent tools smoke README: `CODEBASE/ml/tests/agent_tools/README.md`
- Today's active dev: `npm run dev` on frontend implementation

554
session_memory/7_Jun_26/ONBOARDING_INDEX.md Normal file
View File

@@ -0,0 +1,554 @@
# 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](./ONBOARDING_PHUC_ML_ENGINEER.md) |
| **Quan** — mobile UI, Figma, Stitch, PWA | [ONBOARDING_QUAN_FRONTEND.md](./ONBOARDING_QUAN_FRONTEND.md) |
> **Abbreviations:** See [§12 Glossary](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations) — 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.
```mermaid
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](./ONBOARDING_PHUC_ML_ENGINEER.md#3-what-to-read-what-to-learn) and [Quan doc](./ONBOARDING_QUAN_FRONTEND.md#3-what-to-read-what-to-learn) 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
```bash
# 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
```bash
cd PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/implementation
npm install && npm run dev # :5173
```
| Tool | Link |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Figma** (authority) | [MSK_Workspace_UIX-Design](https://www.figma.com/design/uakk3T4efS1AIckfTEFSZO/MSK_Workspace_UIX-Design?node-id=0-1) |
| **Stitch** (acceleration) | [Whiteboard 8188910238055386921](https://stitch.withgoogle.com/projects/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](https://en.wikipedia.org/wiki/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](./ONBOARDING_PHUC_ML_ENGINEER.md#12-bonus--feynman-technique-prompts) · [Quan §14](./ONBOARDING_QUAN_FRONTEND.md#14-bonus--feynman-technique-prompts)
**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` |

396
session_memory/7_Jun_26/ONBOARDING_PHUC_ML_ENGINEER.md Normal file
View File

@@ -0,0 +1,396 @@
# Onboarding — Phuc (ML Engineer / Agentic & Generative Logic)
**Start here:** [ONBOARDING_INDEX.md](./ONBOARDING_INDEX.md) — [glossary](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations) · [Feynman prompts (INDEX §9)](./ONBOARDING_INDEX.md#9-bonus--feynman-technique-with-agents)
**Date:** 7 Jul 2026
**Timebox:** ~Jul 7 – Aug 31, 2026
**Lane:** Generative LLM, agent runtime, guardrails, RAG gates — co-designed with Dave
---
## 1. Your mission
You continue the **generative & agentic layer** Dave built. Your deliverable is **merged code** that advances checkpoints **CP-2, CP-3, CP-8** — not architecture slides.
You co-own agentic design and guardrail logic with Dave: you propose, Dave approves scope, you ship one vertical slice per PR.
**You are not expected to:** rewrite the CV/Triton pipeline, own full compliance sign-off, or refactor UI components.
**Tóm tắt (VI):** Tiếp tục xây LLM/agent/guardrail; mỗi tuần có PR chạy được; thiết kế guardrail cùng Dave; không làm lại pipeline những kết quả đã có - nếu có thì phải optimize & hạn chế redundancies overhead trong thiết kế.
---
## 2. Your codebase scope
### In scope — touch freely
| Path | What |
| --------------------------------------------------------------------------- | --------------------------------------- |
| `CODEBASE/ml/implementation/nlp/agent_runtime/` | Agent loop, tools, prompts |
| `CODEBASE/ml/tests/gemma4_e2b/` | Isolated Gemma + agent lab (`:5174`) |
| `CODEBASE/ml/tests/agent_tools/` | BFF / Modal / Exa smoke tests |
| `CODEBASE/ml/spec/conformal_decoding_llm_with_domain_stritcly_constrain.md` | Research spec |
| `CODEBASE/frontend/implementation/src/lib/llm/` | Edge inference, chat routing, prompts |
| `CODEBASE/frontend/implementation/src/hooks/useClinicalChat.ts` | Chat bootstrap + streaming |
| `CODEBASE/frontend/implementation/src/workers/llm.worker.ts` | MediaPipe Gemma worker |
| `CODEBASE/frontend/implementation/src/workers/` | Create `guardrail.worker.ts` here (P-3) |
| `CODEBASE/backend/routers/cloud_*.py`, `agent_tools.py` | Cloud + tool BFF |
| `CODEBASE/backend/services/cloud_llm_gateway.py`, `agent_tools_service.py` | Gateway + tools |
| `CODEBASE/backend/implementation/safety/` | Safety service |
| `CODEBASE/backend/implementation/adapters/bert_adapter.py` | Guardrail stubs |
| `CODEBASE/knowledge/spec/` | When working P-4 / P-8 |
### Read-only — understand, don't refactor
- `CODEBASE/backend/implementation/pipeline/` — CV inference (Dave)
- `CODEBASE/infra/` — unless P-6 Modal debugging
- `CODEBASE/frontend/implementation/src/components/` — Quan's lane
- `workspace/LEGACY/` — reference only
### Architecture mental model
```
User message
→ useClinicalChat / runClinicalChatTurn
→ [chat|planning] → Edge Gemma (llm.worker) OR Ollama E4B
→ [agent] → agentLoop → tools (exa, supabase, medgemma)
→ [YOUR GAPS] guardrail check, RAG gate, cloud escalation audit
→ display (StreamingPlainText)
```
Tier 1 = browser Gemma · Tier 2 = Gemini · Tier 3 = MedGemma (NFR-16a governed)
**Tóm tắt (VI):** Phạm vi = ml/agent_runtime, lib/llm, backend safety/routers; không sửa UI hay LEGACY.
---
## 3. What to read, what to learn
### Must read (Day 1 — before first PR)
| # | Document | Path |
| --- | ---------------------- | ---------------------------------------------------------------------------- |
| 1 | Dave's latest handoff | `session_memory/6_Jul_26.md` |
| 2 | Regulatory constraints | `PILOT_PROJECT/PROJ_LEVEL_READING/PLAN/CONTEXT_VISION_SCOPE.md` §4 |
| 3 | Agent protocol | `CODEBASE/ml/implementation/nlp/README.md` |
| 4 | PHI safety | `PILOT_PROJECT/AGENT_SKILL/secrets_and_phi_safety/SKILL.md` |
| 5 | Agent tools rules | `PILOT_PROJECT/AGENT_SKILL/agent_tool_execution/SKILL.md` |
| 6 | LLM + safety NFRs | `Design_Material/SPRINT_1_2_ARCHITECTURE_SPEC.md` — LLM tiers, NFR-10/16a/18 |
### Should read (when ticket assigned)
| Ticket | Read |
| -------- | --------------------------------------------------------------------------------------------------------------- |
| P-1, P-6 | `backend/spec/agent_tools_contract.md`, `agent_runtime/.../tools/registry.ts`, `backend/routers/agent_tools.py` |
| P-2, P-3 | `bert_adapter.py`, `safety/service.py`, `FR_25_UC_DESIGN/Q1_*.md` … `Q4_*.md` |
| P-4, P-8 | `knowledge/spec/knowledge_spec.md`, `agentLoop.ts`, `runClinicalChatTurn.ts` |
| P-5 | `clinicalChatModes.ts`, `chatReasoningLevel.ts`, `6_Jul_26.md` §beta |
| P-7 | `ml/spec/conformal_decoding_llm_with_domain_stritcly_constrain.md` |
| Any | Relevant `UC-*.md` in `Design_Material/FR_25_UC_DESIGN/Use_Case/` |
**Week 1 code trace (do once):**
`useClinicalChat.ts` → `runClinicalChatTurn.ts` → `agentLoop.ts` OR `llm.worker.ts` → `cloud_llm_gateway.py`
### Learn deeper (keywords)
> Abbreviations: [Glossary INDEX §12](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations)
Study as tickets require — use papers, specs, and agent exploration:
| Keywords | Tickets |
| ------------------------------------------------------------------- | -------- |
| `prompt-constrained tool calling`, `agent orchestration loop` | P-1 |
| `RAG pre-retrieval`, `pgvector`, `semantic chunk`, `MOH corpus` | P-4, P-8 |
| `BERT guardrail`, `hallucination detection`, `scope-breach scoring` | P-2, P-3 |
| `conformal decoding`, `domain-constrained generation` | P-7 |
| `CoT streaming`, `thought/answer channel`, `WebLLM MediaPipe` | P-5 |
| `NFR-16a`, `consent audit`, `cloud egress redaction` | P-6 |
| `RAG-Referee`, `citation validation`, `3-axis contestant` | P-8 |
| `Transformers.js`, `Web Worker`, `OPFS model cache` | P-3 |
**Tóm tắt (VI):** Đọc 6 tài liệu bắt buộc ngày 1; đọc thêm theo ticket P-n; học sâu theo từ khóa khi làm.
---
## 4. Dev toolkit
| Tool | Command |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Clinical chat UI | `cd CODEBASE/frontend/implementation && npm run dev` → `:5173` |
| Gemma lab | `cd CODEBASE/ml/tests/gemma4_e2b && npm run dev` → `:5174` |
| Agent smoke (test-the-agentic-functionality) | `cd CODEBASE/ml/tests/agent_tools && npm run smoke` |
| Backend smoke (test-the-agentic-functionality) | `conda activate vkist_ultra`; `cd CODEBASE`; `PYTHONPATH=. python backend/tests/smoke_agent_tools_server.py` |
| Agentic IDE | Cursor / Kilo — load `AGENT_SKILL/agent_tool_execution` |
**Environment variables (frontend** `.env.development`**):**
```env
VITE_CLINICAL_CHAT_USE_LLM=true
VITE_CLINICAL_CHAT_MOCK_TOOLS=true # flip false for P-1 done
VITE_OLLAMA_CHAT_URL=/api/ollama-chat/api/chat
VITE_API_BASE_URL=http://localhost:8001
```
Secrets: ask Dave — `PILOT_PROJECT/secrets_template/README.md`
**Tóm tắt (VI):** Chạy :5173 chat, :5174 lab, smoke tests; đổi MOCK_TOOLS=false khi P-1 xong.
---
## 5. Day 1 playbook (then ship)
**Morning**
1. Run `:5173` → open `/workspace/:patientId` → test chat + agent modes.
2. Run `:5174` gemma4_e2b → complete one tool smoke call.
3. Trace one chat turn and one agent turn (Section 3 code trace).
**Afternoon**
4. Hands-on verify backlog P-1–P-7 (✅/❌ in your notes).
5. Sync with Dave → receive first ticket (likely **P-1** or **P-5**).
Do **not** spend Week 1 writing standalone architecture docs.
**Tóm tắt (VI):** Ngày 1: chạy app, trace code, sync Dave lấy ticket — không viết doc dài.
---
## 6. Spec vs implementation (your work surface)
| Component | Built today | Your tickets |
| ----------------------------------- | -------------- | ------------------ |
| Edge Gemma inference | ✅ | P-5 polish |
| Agent loop + `<tool_call>` protocol | ✅ (mock tools) | P-1 |
| Cloud gateway + audit hooks | ⚠️ partial | P-6 |
| Auto-retrieval in agent mode | ✅ | P-4 extend to chat |
| `bert_adapter.py` / safety service | ❌ stub | P-2 |
| `guardrail.worker.ts` | ❌ missing | P-3 |
| RAG-Referee 3-axis | ❌ spec only | P-8 |
| Planning + high reasoning beta | ⚠️ disabled | P-5 |
**Key facts:**
- Production chat = **browser Gemma 4 E2B** (MediaPipe), not server-side generation.
- Agent mode uses **prompt tags** (`<tool_call>`, `<final>`), not native function calling.
- Do **not** re-enable `ChatMarkdown` in reasoning mode — see `6_Jul_26.md` crash policy.
**Tóm tắt (VI):** Guardrail và RAG chat còn stub — đó là trọng tâm của bạn.
---
## 7. Your backlog (detail)
| ID | Gap | Spec | Starting files |
| ------- | ------------------------------ | --------------------------------- | ----------------------------------------------- |
| **P-1** | Mock agent tools | `agent_tools_contract.md` | `tools/registry.ts`, `agent_tools.py` |
| **P-2** | BERT adapter stubs | NFR-10, Q1–Q4 | `bert_adapter.py`, `safety/service.py` |
| **P-3** | No edge guardrail worker | Web Workers spec | Create `guardrail.worker.ts` |
| **P-4** | No RAG gate in chat mode | NFR-18, `knowledge_spec.md` | `runClinicalChatTurn.ts` |
| **P-5** | Beta modes disabled | `6_Jul_26.md` | `clinicalChatModes.ts`, `chatReasoningLevel.ts` |
| **P-6** | MedGemma escalation incomplete | NFR-16a | `cloud_llm_gateway.py`, `tools/registry.ts` |
| **P-7** | Conformal decoding research | `ml/spec/conformal_decoding_*.md` | `gemma4_e2b/` lab |
**Tóm tắt (VI):** P-1 đến P-7 — chờ Dave giao ID / chủ động đề xuất giải pháp kỹ thuật & thiết kế; mỗi PR một ticket.
---
## 8. SMART milestones
### M1 — First merge (Jul 7 – Jul 18)
| | |
| -------------- | --------------------------------------------- |
| **Ticket** | P-1 or P-5 (Dave assigns) |
| **Specific** | Live agent tools OR remove beta from one mode |
| **Measurable** | PR merged; live demo on `:5173` |
| **Achievable** | One backlog ID only |
| **Relevant** | CP-1 / CP-2 |
| **Time-bound** | Sprint 3 week 1 |
### M2 — Guardrail v1 (Jul 14 – Aug 1)
| | |
| -------------- | ------------------------------------------------------- |
| **Ticket** | P-2 or P-3 (co-scoped with Dave) |
| **Specific** | RFC ≤1 page + one real PASS/FAIL check on outbound text |
| **Measurable** | Test/smoke on 3 fixtures from Q1–Q4 scenarios |
| **Achievable** | Keyword gate OK for v1; full BERT optional |
| **Relevant** | CP-3, NFR-10 |
| **Time-bound** | Sprint 3 end |
### M3 — Retrieval or escalation (Jul 28 – Aug 15)
| | |
| -------------- | -------------------------------------------------- |
| **Ticket** | P-4 or P-6 |
| **Specific** | RAG gate in chat OR MedGemma escalation with audit |
| **Measurable** | Screen recording + log snippet in PR |
| **Relevant** | CP-2 / CP-8, NFR-18 |
| **Time-bound** | Sprint 4 |
### M4 — Research or hardening (Aug 1 – Aug 31)
| | |
| -------------- | ---------------------------------------------------- |
| **Ticket** | P-7 or extend P-2/P-3 |
| **Specific** | Conformal eval (3 VI cases) OR second guardrail axis |
| **Optional** | If M2–M3 complete |
| **Time-bound** | Internship end |
**Tóm tắt (VI):** 4 mốc — PR đầu tiên tuần 1; guardrail tuần 3–4; RAG/escalation tháng 8.
---
## 9. Anti-patterns
- ❌ Refactor `agent_runtime` package structure without inform to members on update logic (no change-Log)
- ❌ Swap model families (Qwen experiment is closed)
- ❌ Touch `LEGACY/` or Quan's UI components
- ❌ Enable `ChatMarkdown` during reasoning streams (markdown rendering on LLM's outcome is problem - we shall put it under the rug)
- ❌ Commit secrets or PHI — ever
**Tóm tắt (VI):** Không refactor lớn, không đổi model, không markdown khi reasoning.
---
## 10. Definition of done
- [ ] ≥3 merged PRs across P-1–P-6
- [ ] Can demo live agent tool call or guardrail check without Dave driving
- [ ] CP-2 or CP-3 marked advanced in team backlog
- [ ] Read `secrets_and_phi_safety` + `agent_tool_execution` skills
**Tóm tắt (VI):** 3 PR, demo được guardrail/agent, checkpoint CP-2 hoặc CP-3 tiến triển.
---
## 11. Agent prompt examples (optimize / change based on usecase)
**Explore generative flow:**
```
Trace runClinicalChatTurn.ts for agent mode: list each file called,
what tool protocol is used, and where mock tools are injected.
```
**Start P-1:**
```
Help me flip VITE_CLINICAL_CHAT_MOCK_TOOLS to false and fix any
BFF errors. Start from tools/registry.ts and agent_tools.py.
Follow AGENT_SKILL/agent_tool_execution/SKILL.md.
```
**Start P-2:**
```
Implement a minimal scope-breach keyword gate in bert_adapter.py
returning PASS/FAIL. Use Q1_True_Agreement.md as fixture context.
```
---
## 12. Bonus — Feynman Technique prompts
Use when a generative/agent concept feels opaque **before** you commit agent-generated code.
Master template: [INDEX §9](./ONBOARDING_INDEX.md#9-bonus--feynman-technique-with-agents).
### Hard concepts → ready-made prompts
**Agent loop & `<tool_call>` protocol (P-1):**
```
Feynman explain agentLoop.ts and the <tool_call> / <final> protocol in
@vkist/agent-runtime. Why prompt tags instead of OpenAI function calling?
Trace one turn with exa_search mocked. Quiz me after.
```
**Edge vs cloud 3-tier LLM (general):**
```
Feynman explain our 3-tier LLM: Edge Gemma → Gemini → MedGemma.
When does each tier run? What is NFR-16a in one sentence?
Use a "triage desk at a hospital" analogy. Quiz me.
```
**clinicalChatStreamRegistry + streaming (P-5 area):**
```
Feynman explain why clinicalChatStreamRegistry.ts paints tokens to the DOM
directly instead of React setState on every token. What breaks if we use
ChatMarkdown during CoT? ≤8 steps. Quiz me.
```
**RAG pre-retrieval (P-4 / P-8):**
```
Feynman explain mandatory RAG pre-generation in our system: what pgvector
retrieves, when agentLoop auto-calls supabase_query, and why chat mode
doesn't do this yet. MOH corpus in plain language. Quiz me.
```
**Guardrail vs RAG-Referee (P-2 / P-3):**
```
Feynman explain the difference between edge guardrail, bert_adapter
drift check, and RAG-Referee. Which are implemented vs stub today?
Use a "editor vs fact-checker" analogy. Quiz me.
```
**After each Feynman session:** write 3 bullets in your own words in the PR or ticket comment.
**Tóm tắt (VI):** Dùng prompt Feynman khi không hiểu agent/LLM; có sẵn prompt cho từng chủ đề khó; tự tóm tắt lại trước khi commit.

499
session_memory/7_Jun_26/ONBOARDING_QUAN_FRONTEND.md Normal file
View File

@@ -0,0 +1,499 @@
# Onboarding — Quan (Frontend / Mobile PWA)
**Start here:** [ONBOARDING_INDEX.md](./ONBOARDING_INDEX.md) — [glossary](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations) · [Feynman prompts (INDEX §9)](./ONBOARDING_INDEX.md#9-bonus--feynman-technique-with-agents)
**Date:** 7 Jul 2026
**Timebox:** ~2 months (ends ~early Aug 2026)
**Lane:** Mobile UI, Figma + Stitch design acceleration, patient PWA
---
## 1. Your mission
You continue the **UI layer** from stub routes toward Sprint 4 patient PWA checkpoints. You ship **visible screens in the browser** — not backend, not LLM internals.
Dave provides two design accelerators:
| Tool | Link | Role |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Figma** | [MSK_Workspace_UIX-Design](https://www.figma.com/design/uakk3T4efS1AIckfTEFSZO/MSK_Workspace_UIX-Design?node-id=0-1) | Design authority — 35 screens, tokens, Vietnamese copy |
| **Google Stitch** | [Whiteboard](https://stitch.withgoogle.com/projects/8188910238055386921) | Acceleration — board has **web mocks**; you design **mobile variants** |
**Your agency:** Pick Figma-first, Stitch-first, or hybrid **per screen** — one line in the PR is enough. Dave assigns tickets; **Week 1 default ticket is Q-1 on the live `/` worklist** (highest yield).
**Week 1 principle — ship fast, correct, get feedback:**
| Priority | Rule |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| **Speed** | Tools (Figma + Stitch) = **1 day max**, then code same day |
| **Yield** | Week 1 targets the **live route** `/` (`PatientWorklistPage`) mobile at 375px — not orphan stub pages |
| **Correctness** | `design-tokens.ts`, live navigation, no hardcoded colors, no pasted Stitch HTML |
| **Feedback** | Draft PR or screenshots to Dave **end of Day 1**; iterate Day 2–3 from review |
**Stitch (quick rules):**
1. Board has web mocks — use Stitch to sketch **mobile layout**, export screenshot for Cursor/Kilo
2. Agent writes React; you review every line
3. Figma wins on tokens and Vietnamese copy
**Tóm tắt (VI):** Tuần 1 = 1 ngày học tool, cùng ngày code mobile cho `/` worklist; PR/screenshot cuối ngày 1; sửa theo feedback Dave — không khảo sát tự do nhiều ngày.
---
## 2. Your codebase scope
### In scope — touch freely
```
CODEBASE/frontend/
├── spec/ ← read: uix_prototype_coverage, figma-component-specs, DESIGN
└── implementation/src/
├── pages/ ← your primary workspace
├── components/atoms/
├── components/molecules/
├── components/layout/
├── styles/design-tokens.ts ← token source of truth
├── App.tsx ← routes
└── public/assets/stitch/ ← exported Stitch references
```
### Read-only — understand, don't refactor
| File / folder | Why |
| ------------------------------------------ | -------------------------------- |
| `organisms/DiagnosticCanvas.tsx` | Dave owns DICOM canvas |
| `molecules/ClinicalChatPanel.tsx` | Read layout only — Phuc owns LLM |
| `lib/llm/`, `workers/` | Phuc's lane |
| `hooks/useClinicalChat.ts` | Know it exists |
| `data/mockData.ts`, `lib/patientStore.tsx` | How worklist gets data |
### Out of scope
`CODEBASE/backend/`, `CODEBASE/ml/`, `CODEBASE/knowledge/`, `CODEBASE/infra/`, `LEGACY/`
### Live routes today
```
/ → PatientWorklistPage.tsx ← Q-1, Q-6 priority
/workspace/:patientId → ClinicalWorkspacePage.tsx ← polish only; Q-2 overlay
+ 35 stub routes in src/pages/ ← Figma parity over time
```
**Tóm tắt (VI):** Sửa pages, atoms, molecules, tokens; không đụng canvas, chat LLM, backend.
---
## 3. What to read, what to learn
### Must read (Day 1 morning only — then code)
| # | Document | Time |
| --- | ----------------------------------------------------------------- | ---------------------------------- |
| 1 | `uix_prototype_coverage.md` | 20 min — **which routes are live** |
| 2 | `figma-component-specs.md` — Priority 1–2 + node for `/` worklist | 15 min |
| 3 | `design-tokens.ts` + skim `DESIGN.md` | 15 min |
| 4 | `AGENT_SKILL/secrets_and_phi_safety/SKILL.md` | 10 min |
Read `component-inventory.md`, `coding_convention`, and persona §3.4 **while coding**, not before Day 1 PR.
**Tóm tắt (VI):** Sáng ngày 1 chỉ đọc 4 tài liệu ngắn; chiều cùng ngày bắt đầu code.
### Should read (when ticket assigned)
| Ticket | Read |
| ---------- | ---------------------------------------------------------------------------------------- |
| Q-1, Q-6 | Figma node for screen; matching `src/pages/*.tsx` stub |
| Q-2 | `uix_prototype_coverage.md` §Safety; `SafetyEscalationOverlay.tsx` |
| Q-3, Q-4 | `CONTEXT_VISION_SCOPE.md` §3.4; `frontend_spec.md` PoC § |
| Q-5 | `figma-component-specs.md` — error boundaries item |
| Q-8 | [Stitch board](https://stitch.withgoogle.com/projects/8188910238055386921) + live routes |
| Any screen | `Design_Material/FR_25_UC_DESIGN/Use_Case/UC-*.md` |
| Layout | `session_memory/26_Jun_26/Proj_context_26_Jun_26.md` — 65/35 ASCII |
### Learn deeper (keywords)
> Abbreviations: [Glossary INDEX §12](./ONBOARDING_INDEX.md#12-glossary-of-abbreviations)
| Keywords | When |
| ---------------------------------------------------------- | ------------------- |
| `atomic design`, `atoms molecules organisms` | component-inventory |
| `React functional components`, `props`, `composition` | all Q tickets |
| `design tokens`, `CSS variables`, `responsive breakpoints` | Q-1, Q-3 |
| `mobile-first`, `375px viewport`, `touch target 44px` | Q-3, Q-6 |
| `accessibility`, `WCAG contrast`, `font scaling` | Q-4, Q-6 |
| `error boundaries` | Q-5 |
| `PWA`, `service worker` | Sprint 4 (later) |
| `Figma Dev Mode`, `Inspect` | Q-1 |
| `Stitch design-to-code`, `HTML export as reference` | Q-8 |
| `Vite`, `npm run dev` | daily |
| `Vietnamese clinical UX`, `jargon-free patient copy` | Q-6 |
**Tóm tắt (VI):** Đọc thêm theo ticket khi code; không ôm 7 tài liệu trước PR đầu.
---
## 4. Dev toolkit
| Category | Tool |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| Dev server | `npm run dev` → `http://localhost:5173` |
| Design authority | [Figma](https://www.figma.com/design/uakk3T4efS1AIckfTEFSZO/MSK_Workspace_UIX-Design?node-id=0-1) |
| Design acceleration | [Stitch whiteboard](https://stitch.withgoogle.com/projects/8188910238055386921) |
| Coding agent | Cursor / Kilo |
| Mobile test | Chrome DevTools → iPhone SE 375×667 |
| PR evidence | Before/after screenshots desktop + 375px |
```bash
cd PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend/implementation
npm install
npm run dev
```
**Optional:** Stitch SDK — `public/assets/stitch/README.md` (OAuth via Dave)
### Agent prompt template
```
Implement [screen name] for mobile (375px).
Reference: Figma node [id] from figma-component-specs.md.
Layout hint: [Stitch mobile export screenshot or description].
Use existing atoms from component-inventory.md.
Use design-tokens.ts — no hardcoded colors.
Route: [path from figma-component-specs].
Match navigation in uix_prototype_coverage.md.
```
**Tóm tắt (VI):** npm run dev + Figma + Stitch + Cursor; test 375px; PR kèm screenshot.
---
## 5. Figma + Stitch workflow
### When to use which
| Source | Best for | Caveat |
| ------------- | --------------------------------------------- | --------------------------------------- |
| **Figma** | Tokens, spacing, VI copy, auth/patient cards | Slower from scratch — use Inspect |
| **Stitch** | Rapid mobile layout; agent reference material | Web mock ≠ mobile — create mobile frame |
| **Live code** | Navigation truth | `uix_prototype_coverage.md` |
**Legacy Stitch desktop** (`public/assets/stitch/README.md`, project `17628337625105266704`) — reference only.
**Primary Stitch:** [project 8188910238055386921](https://stitch.withgoogle.com/projects/8188910238055386921)
### Workflow choices (pick one per screen — state in PR)
| ID | When | Steps |
| -------------------- | -------------------------------------------------- | --------------------------------------------- |
| **A — Figma-first** | Screen in node map; tokens matter | Inspect → atoms → `src/pages/` |
| **B — Stitch-first** | Mobile patient screen; Stitch mobile variant ready | Stitch mobile design → export → agent → React |
| **C — Hybrid** | Stitch layout close; Figma has correct copy | Stitch structure + Figma polish → code |
**Rule:** Final PR must match live navigation (`/` → `/workspace/:id`), not a disconnected mock.
**Tóm tắt (VI):** Chọn A/B/C mỗi màn hình; Figma thắng khi khác Stitch; khớp route thật.
---
## 6. Week 1 sprint — tools in 1 day, ship mobile same week
> **No multi-day exploration.** Figma/Stitch are means to an end — the end is a **merged mobile PR** on a live screen.
### Day 1 — Tools (morning) + code (afternoon)
| Block | Time | Do |
| ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup** | 30 min | `npm install && npm run dev` — open `/` on desktop + DevTools 375px |
| **Figma** | 45 min | Open [Figma](https://www.figma.com/design/uakk3T4efS1AIckfTEFSZO/MSK_Workspace_UIX-Design?node-id=0-1) → Inspect **Patient List** node `82-3155` (maps to live worklist) |
| **Stitch** | 45 min | Open [Stitch board](https://stitch.withgoogle.com/projects/8188910238055386921) → one mobile-frame sketch OR pick closest web mock → **screenshot for agent** |
| **Must-read** | 60 min | Section 3 four docs only |
| **Code** | Rest of day | **Q-1 on live `/`** — mobile layout for `PatientWorklistPage.tsx` (or `patient-list-main.tsx` if Dave assigns stub route). Cursor/Kilo + agent template (§4). **375px from the start.** |
| **EOD** | 15 min | Send Dave: draft PR **or** before/after screenshots at 375px + 1-line workflow choice (A/B/C) |
**Not acceptable as Week 1 deliverable:** gap lists, alignment essays, clicking all 35 routes, Storybook setup.
### Day 2 — Feedback loop
- Apply Dave's review on spacing, tokens, navigation, touch targets
- Push PR updates; aim for **merge-ready** by EOD if scope was ≤200 lines
### Day 3–5 — Second yield
- Merge Week 1 PR OR complete merge after small fixes
- Start **second screen** (patient card stub or Q-3 polish on same `/` route)
- Optional: update one Stitch frame to match what you shipped (Q-8 lite — no separate doc)
### Week 1 success criteria
| Check | Pass |
| ------------------------------ | ---------------------------------------------- |
| Live route `/` usable at 375px | No horizontal scroll |
| Uses `design-tokens.ts` | No raw hex in new code |
| Dave reviewed once | By end of Day 1 or 2 AM |
| Runnable demo | `npm run dev` — you walk Dave through tap flow |
**Tóm tắt (VI):** Ngày 1: tool buổi sáng, code buổi chiều, gửi Dave tối ngày 1; ngày 2 sửa feedback; ngày 3–5 merge + màn hình thứ 2.
---
## 7. What exists vs what you build
| Exists | You increment |
| ---------------------------------- | -------------------------------------------- |
| WS-25 workspace PoC (functional) | Mobile polish, not rewrite |
| 35 Figma stub routes | Q-1: 2 priority screens |
| Stitch web mocks | Q-8 lite: update frame after ship (optional) |
| `SafetyEscalationOverlay` (orphan) | Q-2: wire it |
| No error boundaries | Q-5 |
| No patient PWA | Q-6 |
### WS-25 layout (read-only context)
Clinician workspace is 65/35 split — your zone is **patient list, cards, patient dashboard**, not DICOM canvas:
```
┌─ TopBar ─────────────────────────────────────┐
├─ Zone A (65%) DICOM │ Zone B (35%) sidebar ┤ ← Dave/Phuc zone
└────────────────────────────────────────────────┘
Your zone: / worklist, /patients, patient-card-*, /home
```
See `session_memory/26_Jun_26/Proj_context_26_Jun_26.md` for full ASCII.
**Tóm tắt (VI):** Workspace clinician đã có; bạn làm patient list, card, dashboard mobile.
---
## 8. Your backlog (detail)
| ID | Gap | Priority screens / files |
| ------- | ----------------------- | --------------------------------------------------------------------------------------- |
| **Q-1** | Stub → Figma fidelity | Home, Login, Patient List, Patient Cards (see `figma-component-specs.md` §Priorities) |
| **Q-2** | Safety overlay unrouted | `SafetyEscalationOverlay.tsx`, `App.tsx` |
| **Q-3** | No 375px pass | Assigned patient screen |
| **Q-4** | Accessibility | Patient-facing view |
| **Q-5** | Error boundaries | `App.tsx` workspace route |
| **Q-6** | Patient dashboard | `patient-card-*.tsx`, FR-26 preview |
| **Q-7** | Zero-GPU UI banner | Dave provides detection hook |
| **Q-8** | Stitch sync (lite) | Update Stitch frame **after** you ship — optional in PR, not a standalone proposal gate |
**Figma priorities (from spec):**
1. Home, Login, Create Account
2. Patient List + Cards
3. Workspace shell (read-only for you)
4. Auth flows
5. AI View, Chat, Ultrasound
6. Remaining screens
**Tóm tắt (VI):** Ưu tiên Home, Patient List, Patient Card trước.
---
## 9. SMART milestones
### M1 — Week 1 ship (Jul 7 – Jul 11) ← **start here**
| | |
| -------------- | ------------------------------------------------------------------------------------------------------- |
| **Ticket** | **Q-1 on live `/` worklist** (Dave confirms file: `PatientWorklistPage.tsx` or `patient-list-main.tsx`) |
| **Specific** | Mobile implementation at 375px on a **live** route — not a disconnected stub |
| **Measurable** | Draft PR Day 1 EOD; merged or merge-ready by Day 5; before/after screenshots |
| **Achievable** | ≤200 lines; tools only Day 1 morning |
| **Relevant** | CP-5 — fastest visible yield |
| **Feedback** | Dave review ≤24h after first push |
### M2 — Second screen (Jul 14 – Jul 25)
| | |
| --------------- | ------------------------------------------------------------------- |
| **Ticket** | Q-1 #2 (patient card / home) or Q-3 deepen mobile on shipped screen |
| **Deliverable** | 2nd merged PR |
| **Relevant** | CP-5 / CP-6 |
### M3 — Mobile hardening (Jul 28 – Aug 11)
| | |
| --------------- | -------------------------------------------------------------- |
| **Ticket** | Q-3 or Q-2 |
| **Deliverable** | 375px recording; taps ≥44px; optional Q-8 Stitch frame updated |
| **Relevant** | CP-6 |
### M4 — Accessibility (Aug 4 – Aug 21) *optional*
| | |
| --------------- | ----------------------------------------- |
| **Ticket** | Q-4 |
| **Deliverable** | High contrast, large type on patient view |
| **Relevant** | CP-7 |
**Tóm tắt (VI):** M1 = tuần 1 merge mobile `/` worklist; không có M0 khảo sát riêng; M2–M4 mở rộng sau khi có feedback.
---
## 10. Per-ticket workflow
```
1. Dave assigns Q-n
2. Pick workflow A / B / C — write in PR description
3. Capture Figma + Stitch reference screenshots
4. Cursor/Kilo: use agent prompt template (Section 4)
5. Review every line of the diff — understand before commit
6. npm run dev → screenshot desktop + 375px
7. PR: Q-n, CP-n, workflow choice, design links
```
**Tóm tắt (VI):** Mỗi ticket: chọn workflow → agent hỗ trợ → review diff → screenshot → PR.
---
## 11. Boundaries
**Touch:** `src/pages/`, `src/components/` (atoms/molecules/layout), `src/styles/`, `App.tsx`, Stitch whiteboard, `public/assets/stitch/`
**Do not touch:** `src/lib/llm/`, `src/workers/`, backend, ml
**Figma/Stitch edits:** OK to update Stitch frames and Figma comments; ask Dave before changing shared Figma components.
**Tóm tắt (VI):** Chỉ frontend UI; hỏi Dave trước khi sửa component Figma dùng chung.
---
## 12. Definition of done
- [ ] Week 1: live `/` worklist mobile at 375px shipped or merge-ready
- [ ] Dave feedback incorporated within 48h of first push
- [ ] ≥2 screens merged by end of Month 1 (M1 + M2)
- [ ] Each PR: workflow A/B/C (one line) + 375px screenshot
- [ ] Never committed `secrets/` or PHI
**Tóm tắt (VI):** Tuần 1 phải có mobile `/` chạy được + feedback Dave; không cần báo cáo alignment dài.
---
## 13. Agent prompt examples (optimize / change based on usecase)
**Learn the codebase:**
```
Explain PatientWorklistPage.tsx in simple terms: what components it uses,
where data comes from, and which Figma node it maps to.
```
**Start Q-1 (Figma-first):**
```
Implement /home per Figma node 33-143 in figma-component-specs.md.
Reuse Button and Badge from component-inventory. Use design-tokens.ts only.
Current stub: src/pages/home.tsx
```
**Week 1 — ship live worklist mobile (Day 1 afternoon):**
```
Mobile pass for PatientWorklistPage at 375px.
Figma node 82-3155. Stitch screenshot attached.
Use design-tokens.ts and existing Button, Badge, PatientCard from component-inventory.
No horizontal scroll. Touch targets >= 44px.
Do not change routing — stay on /.
Show me the minimal diff.
```
**Start Q-3 (mobile pass):**
```
Make patient-list-main.tsx usable at 375px: no horizontal scroll,
touch targets at least 44px. Show me which CSS to change.
```
---
## 14. Bonus — Feynman Technique prompts
Use when React layout, routing, or design workflow feels confusing **before** you commit.
Master template: [INDEX §9](./ONBOARDING_INDEX.md#9-bonus--feynman-technique-with-agents).
### Hard concepts → ready-made prompts
**Live route vs stub route (Week 1 critical):**
```
Feynman explain the difference between our LIVE routes (/ and /workspace/:id)
and the 35 Figma STUB routes in src/pages/. Why does Week 1 target
PatientWorklistPage on / ? Use a "demo kitchen vs blueprint room" analogy.
Quiz me.
```
**PatientWorklistPage data flow:**
```
Feynman explain PatientWorklistPage.tsx: where patient list data comes from
(mockData vs patientStore), what happens when I tap "Mở phiên chẩn đoán",
and which components re-render. ≤8 steps. No jargon without definition. Quiz me.
```
**design-tokens.ts vs hardcoded CSS:**
```
Feynman explain why we use design-tokens.ts instead of #hex in components.
Show one wrong example and one right example from our codebase.
Quiz me on how to add a new spacing value correctly.
```
**375px mobile layout:**
```
Feynman explain mobile-first pass at 375px for our worklist: flex vs grid,
overflow-x, and 44px touch targets. What is the smallest change to
PatientListShell or PatientWorklistPage to stop horizontal scroll?
Teach only — no code until I answer your quiz.
```
**Figma vs Stitch vs code (your workflow A/B/C):**
```
Feynman explain when I should use Figma-first vs Stitch-first vs hybrid
for a patient screen. What is "reference only" Stitch export vs production code?
Quiz me with one scenario: patient card on mobile.
```
**React atoms vs molecules (component-inventory):**
```
Feynman explain atomic design using OUR component-inventory.md: when is
something a Button (atom) vs PatientHeader (molecule)? Give 2 examples
from patient list screen. Quiz me.
```
### Feynman before commit rule
If the agent wrote code and you **cannot** Feynman-explain the diff back to a friend in 30 seconds → don't commit yet; run one Feynman prompt on the confusing file.
**Tóm tắt (VI):** Hỏi agent giải thích đơn giản khi khó hiểu React/route/mobile; có prompt mẫu; không commit code mình chưa giải thích lại được.