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

Add README with file type guidelines and snake_case naming rule; update .gitignore typo

Browse Source
This commit is contained in:
DatTT127
2026-06-23 12:48:09 +07:00
parent 20a02efa9b
commit 1b1b170fcc
140 changed files with 229391 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
.gitignore vendored
View File

@@ -197,5 +197,13 @@ Temporary Items
*~
.*.swp
.idea/
*.csv
*.pdf
*.pptx
# enviroment file
*.env
secrets/
*ckpt/
# End of .gitignore
*.docx
*.bkp

112
README.md Normal file
View File

@@ -0,0 +1,112 @@
# Pilot Project - MSK Ultrasound Stack
## File Type Guidelines
- Only include text‑based files that can be viewed and edited directly in an IDE: Markdown (`.md`), HTML (`.html/.htm`), source code files (`.py`, `.java`, `.js`, `.ts`, `.cpp`, `.h`, etc.), configuration files (`.json`, `.yaml`, `.yml`, `.toml`, `.ini`, `.cfg`), and plain text (`.txt`).
- Do **not** commit binary or non‑text‑friendly files such as PDFs, PowerPoint presentations (`.pptx`), Word documents, Excel spreadsheets (`.csv`, `.xlsx`), ZIP archives, or compiled binaries.
- For large datasets, documents, presentations, or binary assets, store them in an external storage system (e.g., Amazon S3, Google Cloud Storage, Azure Blob) and reference them via a URL/link in the appropriate markdown or documentation file.
- Images that illustrate documentation or design (e.g., diagrams, screenshots) may be committed directly **if** they are small and aid understanding, but large image datasets must be stored externally and linked.
- Keep the repository lightweight and IDE‑friendly to ensure fast cloning, searching, and navigation.
- Use **snake_case** naming for files and directories (lowercase letters, numbers, and underscores only). Avoid spaces, hyphens, and special characters. Uppercase is acceptable for constants (e.g., `CONFIG.json`) but prefer lowercase.
## Overview
This repository contains the research, design, and implementation materials for the MSK Ultrasound Stack pilot project. It includes documentation, design artifacts, source code, and supporting files organized to facilitate collaborative development while maintaining clear separation between shared assets and individual developer secrets.
## Directory Structure
```
PILOT_PROJECT/
├── .gitignore # Git ignore rules (includes OS/editor temp files, dependencies, and `secrets/` folder)
├── Reading_docs/ # Reference and background materials
│ ├── PLAN/ # Project plans and timelines
│ ├── Requirement_Analysis/ # Stakeholder and functional requirements
│ ├── Technical_Brainstorming/ # Brainstorming notes, sketches, whitepapers
│ └── User_Analysis/ # User personas, workflows, and usability research
├── workspace/ # Primary working area for sprints and development
│ ├── sprint_1_2/ # Example sprint folder
│ │ ├── CAVEAT_TASK.md # Known limitations and caveats
│ │ ├── CONTEXT.md # Sprint context and goals
│ │ ├── DESIGN_MATERIAL/ # UI/UX mockups, wireframes, style guides
│ │ ├── docs/ # Generated or supplemental documentation
│ │ ├── PROJECT_VIS.md # Project visualization and architecture diagrams
│ │ ├── SOFTWARE_SYSTEM_DESIGN_FR_25.md # Detailed software design specification
│ │ ├── SOLUTION_ARCHITECTURE_SPEC.md # Solution architecture overview
│ │ └── visualization/ # Charts, diagrams, and visual assets
│ └── ... # Additional sprint folders as needed
├── secrets/ # **Developer‑managed secrets** (NOT tracked by git)
│ │ # Each developer should maintain their own copy of this folder
│ │ # locally (or in a secure secret manager) and add it to their personal .gitignore.
│ │ # Example contents: API keys, database passwords, TLS certs, etc.
│ │ # The repository .gitignore intentionally ignores this entire directory.
│ └── .gitkeep # Placeholder to keep the folder in repo structure
└── README.md # This file
```
## Getting Started
1. **Clone the repository**
```bash
git clone git@github.com:DTJ-Tran/pilot_msk_ultrasound_stack.git
cd pilot_msk_ultrasound_stack
```
2. **Set up your local secrets**
- Create a `secrets/` directory (if not already present) in your local clone.
- Add any required API keys, certificates, or configuration files **here**.
- Ensure `secrets/` is listed in your personal `.gitignore` (the repository‑level `.gitignore` already ignores this folder).
3. **Explore the documentation**
- Start with `Reading_docs/PLAN/` for project timeline and milestones.
- Review `workspace/sprint_1_2/CONTEXT.md` for current sprint goals.
- Check `workspace/sprint_1_2/DOCUMENTATION/` for architecture diagrams and design specs.
4. **Set up your development environment**
- Follow language‑specific setup guides found in `workspace/sprint_<n>/docs/` (if any).
- Install dependencies listed in any `requirements.txt`, `package.json`, `pom.xml`, etc., that appear in sprint folders.
## Codebase Architecture & Style Guide
### High‑Level Architecture
- **Modular Layers**: The system is organized into presentation, application/services, and data access layers (see `SOLUTION_ARCHITECTURE_SPEC.md`).
- **Interface‑Driven**: Core services communicate via well‑defined interfaces/contracts to enable easy substitution of implementations (e.g., mock services for testing).
- **Configuration‑Driven**: Environment‑specific settings (endpoints, feature flags) are externalized and should be injected via the `secrets/` folder or environment variables—not hard‑coded.
### Coding Conventions
- **Language‑Specific**: Follow the official style guide for each language used (e.g., PEP 8 for Python, Google Java Style, Airbnb JS/TS, etc.).
- **Naming**: Use descriptive, intent‑revealing names. Constants in `UPPER_SNAKE_CASE`, classes/functions in `PascalCase`/`camelCase` as appropriate.
- **Documentation**: Every public class, function, and module must include a docstring/comment describing purpose, parameters, return values, and side‑effects.
- **Error Handling**: Prefer explicit exceptions over error codes; log meaningful messages at appropriate levels (debug/info/warn/error).
- **Testing**: Write unit tests for new logic; aim for >80% coverage on critical paths. Keep tests in parallel `test/` directories adjacent to source.
- **Commits**: Write clear, conventional commit messages (type: scope? subject). Keep commits atomic and focused.
### Dependency Management
- Pin exact versions in lockfiles (`requirements.txt`, `package-lock.json`, `pom.xml`, etc.).
- Avoid committing compiled binaries or generated documentation—these should be produced locally or in CI.
## Collaboration Guidelines
- **Branch Naming**: Use `feature/<short-description>`, `bugfix/<issue-id>`, or `release/<version>`.
- **Pull Requests**:
- Provide a concise summary of changes.
- Link to any related issue or task.
- Include screenshots or diagrams when UI/UX is affected.
- Request at least one review from a teammate.
- **Code Review**: Look for correctness, adherence to style, test coverage, and documentation updates.
- **Issues & Tracking**: Use the linked GitHub Issues board (or your preferred tracker) to log bugs, features, and technical debt.
## Secrets Management (Important)
The `secrets/` directory **must not** be committed to the repository. The repository‑level `.gitignore` already contains:
```
secrets/
```
Each developer is responsible for:
- Creating their own `secrets/` folder locally.
- Storing sensitive items (API keys, passwords, certificates) there.
- Referencing these values in code via environment variables or a secure config loader that reads from `secrets/`.
- Backing up their secrets securely (e.g., using a password manager or encrypted vault).
If you need to share a secret securely with a teammate, use your organization’s approved secret‑sharing tool (e.g., 1Password Teams, HashiCorp Vault, AWS Secrets Manager) — **never** commit plaintext secrets.
## License
[Specify your license here, e.g., MIT, Apache 2.0, or internal proprietary.]
---
*Welcome to the team! If you have questions, reach out to the project lead or consult the `Reading_docs/` for background material.*

311
proj_level_reading/PLAN/CONTEXT_VISION_SCOPE.md Normal file
View File

@@ -0,0 +1,311 @@
# VISION_SCOPE.md
*VKIST Musculoskeletal Pilot Project Specification & Strategic Context The Project Vision*
---
## 1. Project Identity, Motivation & Problem Statement
### 1.1 Project Identity
* **Project Name:** VKIST MSK Pilot Workspace.
* **Pitch Matrix Date:** June 9, 2026.
* **Active Cycle:** June 2, 2026 to September 2, 2026 (Strict 3-Month Window).
* **Engineering Paradigm:** **Hybrid Architecture Execution**—Macro-Planning driven via Structured Waterfall Phases coupled with Micro-Managed tactical execution loops via Agile Scrum Sprints.
### 1.2 Core Motivations
* **The Academic Migration:** Intentionally transitioning isolated, static machine learning model checkpoints from academic research codebases into an active, functional, and referenceable medical software ecosystem. This is critical to establishing the engineering team's operational value within the local healthcare community.
* **Technological Convergence:** Infusing VKIST’s foundational Computer Vision models with modern advancements in Natural Language Processing (NLP) and robust web systems engineering architectures.
* **Mitigating Clinical Exhaustion:** Systematically solving the crippling clinical time constraints endemic to Vietnamese public referral facilities (e.g., Bach Mai, Viet Duc) where outpatient counts regularly exceed 100 individual evaluations per single daily shift.
* **Countering Dangerous Folk Interventions:** Offering a high-trust, data-backed clinical education mechanism to explicitly displace hazardous alternative practices (e.g., direct herbal leaf-wrapping or violent manual adjustment of unstable structures) that cause tissue infections or permanent anatomical failure.
---
## 2. Global System Boundary Layout
```plantuml
@startuml
skinparam handwritten false
skinparam monochrome true
skinparam packageStyle rect
skinparam shadowing false
title VKIST MSK Pilot System - High-Level Boundary Topology
package "Local Client Subsystem (Progressive Web App)" {
[PWA Frontend Core] as PWA
[TensorFlow.js Engine] as TFJS
[Local Storage / WebCrypto] as Crypto
}
package "Regional Edge Cloud Infrastructure (Vietnam Local Hub)" {
[FastAPI Processing Server] as API
[PyTorch Inference Pipe] as PyTorch
[ReportLab Generator] as PDF
}
package "External Operational Systems" {
[Clinical DICOM Source] as DICOM
}
DICOM --> API : Over 4G Network (pydicom Stream)
PWA <--> API : HTTPS REST / Multi-modal IPC
TFJS <--> PWA : Client-Side Text Segmentation
Crypto <--> PWA : Decentralized AES-256 Storage
PyTorch <--> API : DeepLabv3/UNet Context Serialization
PDF <--> API : Automated PDF Export Generation
@endum
```
---
## 3. Comprehensive End-User Persona Matrices
### 3.1 The Diagnostic Radiologist
* **Identity Context:** Highly specialized medical doctors responsible for translating high-fidelity image structures into explicit text matrices to dictate treatment tracks.
* **Demographics:** Ranges from tech-fluent, digitally native attendings to senior department directors (Ages 28–55).
* **Operational Environment:** Low-ambient-light reading environments within high-pressure public hospitals; processing massive daily DICOM streams with tight turnaround times.
* **Domain Mastery:** Exceptional structural pattern recognition across diverse modalities (X-Ray, CT, MRI).
* **Critical Technical Knowledge Deficit:** Unfamiliar with machine learning edge-case behavioral profiles, model optimization constraints, or internal weight tuning.
* **Attitude Towards AI Integration:** Receptive to deterministic systems that eliminate administrative overhead, calculate structural lines accurately, and prevent alert fatigue. Highly resistant to unproven, black-box demos that disrupt fast-paced screen setups.
* **Product Team Architectural Mandate:** Implement **invisible workflow preservation**. The system must serve as an background validation layer that shields them from diagnostic liability without introducing extraneous clicks or system lag.
### 3.2 The Rheumatologist & Orthopedic Surgeon
* **Identity Context:** The definitive treatment architects who consume diagnostic data to orchestrate downstream pharmaceutical, mechanical, or invasive surgical paths.
* **Demographics:** Clustered between ages 30 and 60. Senior members wield substantial institutional control over hospital procurement choices.
* **Operational Environment:** Divided among sterile surgical suites, chaotic inpatient rounds, and heavily overcrowded outpatient clinics.
* **Domain Mastery:** Advanced biomechanics, complex clinical diagnosis, and high-stakes legal/ethical responsibility for long-term recovery curves.
* **Critical Technical Knowledge Deficit:** Lacks granular pixel-level physics understanding regarding raw ultrasound or MRI artifacts, and possesses no visibility into the patient's behaviors outside the clinical environment.
* **Attitude Towards AI Integration:** Disinterested in shallow AI models identifying obvious fractures. Highly motivated by deep predictive algorithms (e.g., forecasting specific cartilage degeneration trajectories or hardware mechanical failure risks).
* **Product Team Architectural Mandate:** Deliver an **intelligent clinical force multiplier**. The interface must feature rapid-consumption dashboards that synthesize fragmented data silos and automate visual patient translation layers to protect precious consultation minutes.
### 3.3 The Physical Therapist / Physiotherapist
* **Identity Context:** Downstream clinical executors tasked with translating high-level medical scripts into long-term physical, mechanical, and kinetic rehabilitation programs.
* **Demographics:** Younger, highly active professionals (Ages 20–39).
* **Operational Environment:** Highly demanding outpatient therapy units with extreme caseload rates (11 to 20+ patients per daily shift), causing severe time constraints and a high prevalence of work-related musculoskeletal disorders (WMSDs).
* **Domain Mastery:** Functional kinetic rehabilitation, manual tissue therapies, and precision configuration of electro-physical modalities (TENS, NMES, Diathermy).
* **Critical Technical Knowledge Deficit:** Limited radiological image processing literacy and minimal training in advanced clinical statistics.
* **Attitude Towards AI Integration:** Cautious regarding professional devaluation, but highly responsive to objective tracking interfaces that validate client progression metrics across multiple touchpoints.
* **Product Team Architectural Mandate:** Treat them as **kinetic movement athletes**. The PWA must serve as a lightweight digital exoskeleton, leveraging zero-GPU mobile rendering profiles to completely automate manual charting, expose tissue-depth calculations, and bridge cross-domain language gaps.
### 3.4 The MSK Patient & Caregiver Proxy
* **Identity Context:** The ultimate consumers of care, balancing chronic physical discomfort with severe medical information deficits.
* **Demographics:** Elderly populations (Ages 45–80+) exhibiting low digital literacy, heavily supported by younger family caregivers (Ages 20–45) who act as their technology proxy.
* **Operational Environment:** Home-based rehabilitation contexts and busy public waiting areas; highly susceptible to engaging video-based community medical misinformation.
* **Domain Mastery:** Expert experiential awareness of their unique chronic pain boundaries; zero formal anatomical proficiency.
* **Critical Technical Knowledge Deficit:** Incapable of parsing raw medical terminology or grayscale imaging slices, and unaware of the permanent physiological risks associated with non-standard folk medicine tracks.
* **Attitude Towards AI Integration:** Highly receptive if the system transforms abstract scans into simple, intuitive 3D architectural representations that reduce clinical anxiety.
* **Product Team Architectural Mandate:** Focus on **profound empathy and strict interface accessibility**. The application must run on legacy consumer smartphones, utilizing high-contrast views, large fonts, and dual-profile family data synchronization models.
---
## 4. Key Constraints & Regulatory Boundaries
| Dimension | Constraint Parameter | Engineering Strategy |
| --- | --- | --- |
| **Statutory Data Governance** | Strict compliance with **Vietnam's Decree 13/2023/ND-CP** regarding sensitive personal health data protection. | Deploy client-side cryptographic scrubbing using the WebCrypto API. Ensure all production cloud infrastructure, file caches, and backend databases reside locally within sovereign Vietnamese data centers (e.g., Viettel IDC, VNPT). |
| **Hardware Heterogeneity** | The patient/caregiver fleet consists largely of legacy, low-cost consumer smartphones with weak WebGL/GPU rendering capabilities. | Implement a **Hybrid Dual-Engine Subsystem** inside the PWA. If browser checks flag outdated GPUs, hot-swap Three.js out for a zero-GPU CPU-bound 36-frame flat image sequence turntable switcher to generate the interactive rotation effect. |
| **Physical Context Barriers** | Physical therapists operate with hands continually covered in conductive gels, therapeutic oils, or sweat. | Design macro-scale UI target regions supporting knuckle-taps, simple touch vectors, and minimal textual input requirements during active sessions. |
| **Operational Gating** | Vietnamese clinicians fear an unmanageable, uncompensated influx of open communication requests from patients. | **Strictly exclude open-ended chat loops** (e.g., Zalo/Messenger approximations). All data interfaces must use highly structured, asynchronous, one-way or tightly gated programmatic summaries. |
---
## 5. System Execution Milestones (3-Month Cycle)
```plantuml
@startgantt
title VKIST MSK Pilot Project - Gantt Lifecycle View
theme classic
[Sprint 0: Pitch & Architecture Spike] lasts 11 days and starts 2026-06-02
[Sprint 1: The Fast PoC Baseline] lasts 12 days and starts 2026-06-15
[Sprint 2: Multi-Modal & NLP Integration] lasts 12 days and starts 2026-06-29
[Sprint 3: The Collaborative Workspace] lasts 12 days and starts 2026-07-13
[Sprint 4: The Patient-Facing PWA] lasts 12 days and starts 2026-07-27
[Sprint 5: Feedback Pipeline & Hardening] lasts 12 days and starts 2026-08-10
[Sprint 6: Beta Release & Evolution] lasts 10 days and starts 2026-08-24
[Sprint 0: Pitch & Architecture Spike] is colored after Red
[Sprint 1: The Fast PoC Baseline] is colored after Orange
[Sprint 3: The Collaborative Workspace] is colored after Green
[Sprint 6: Beta Release & Evolution] is colored after Blue
@endgantt
```
### 5.1 Sprint-by-Sprint Implementation Scope
* Sprint 0 | June 2 – June 12 | "Pitch & Architecture Spike"
* *Deliverables:* Technical architecture clearance; validation audit of the VKIST machine learning stack (DeepLabv3/UNet models). Establish deployment paths for on-device and local edge server infrastructure.
- **Sprint Goal:** Secure administrative clearance and map research code constraints before system initialization.
- **Key Epic / Backlog Items:**
- 🎯 **Milestone:** Lock pitching presentation deck and win official project pitch on **June 9**.
- 🔍 **User & Market Discovery:** Complete identification parameters for the 4 primary user groups (Radiologists, Orthopedic Surgeons, Physiotherapists, Patients).
- 📋 **Requirements Engineering:** Finalize Functional Requirements (FR) and capture initial Non-Functional Requirements (NFR) regarding localized data governance.
- 🛠️ **Technical Spike:** Audit existing VKIST ML/NLP models (ConvNeXt, MedViT, and UNet architectures) to map web-deployment pathway boundaries.
- 🏗️ **Infrastructure Baseline:** Set up the base CI/CD pipelines to support rapid incremental code compilation.
* Sprint 1 | June 15 – June 26 | "The Fast PoC Baseline"
* *Deliverables:* Rapid UI prototype generation via high-fidelity mockups. Configure initial server pipelines (FastAPI `app.py`) to process raw array matrices, saving output metrics securely to internal storage.
- **Sprint Goal:** Establish an interactive end-to-end processing pipeline to lock early stakeholder buy-in.
- **Key Epic / Backlog Items:**
- 🎨 **Product Design:** Conduct UI/UX wireframing loops and publish interactive Figma prototype mockups.
- ⚡ **API Foundation:** Instantiate the FastAPI backend server topology to handle secure local asset transfers.
- 🩺 **ML Ingestion:** Connect file ingest pathways to load raw ultrasound images and wire them directly into the underlying classification pipeline.
- 🖼️ **Early Visual Layer:** Output early inference mask previews onto a basic browser-based preview window canvas.
* Sprint 2 | June 29 – July 10 | "Multi-Modal & NLP Integration"
* *Deliverables:* Embed localized NLP translation modules. Implement client-side privacy scrubbing masks to satisfy Decree 13 anonymization requirements before transferring assets over network boundaries.
- **Sprint Goal:** Build the multi-modal interaction engine while anchoring core statutory data security guardrails.
- **Key Epic / Backlog Items:**
- 🛡️ **Sovereign Privacy Architecture:** Implement automated client-side metadata scrubbing to ensure full compliance with **Vietnam's Decree 13/2023/ND-CP**.
- 💬 **Zero-Friction NLP Conduit:** Deploy the multi-modal diagnostic chat system using language interfaces to clean up fragmented clinical abbreviations.
- ⚙️ **Local Anonymization:** Configure on-device string parsers to sanitize personal identification tokens before indexing transactions to the server log.
* Sprint 3 | July 13 – July 24 | "The Collaborative Workspace"
* *Deliverables:* Deploy the asynchronous collaborative canvas allowing clinical annotation mapping. Isolate role-based permissions (e.g., read-only diagnostic configurations for downstream therapists).
- **Sprint Goal:** Release the shared cross-department canvas to safely link distinct clinical domains without record mutation.
- **Key Epic / Backlog Items:**
- 🤝 **Multidisciplinary Sync:** Standardize multi-user workspace access protocols, granting Physical Therapists read-only clinical analytics layers.
- ✏️ **Asynchronous Collaboration:** Build layers for asynchronous clinical annotations, drawing tools, and structured safety-check verification matrices.
- 🔬 **Frontline Verification:** Run target usability test rounds with professional clinical partners to isolate interface anomalies under high shift volumes.
* Sprint 4 | July 27 – Aug 7 | "The Patient-Facing PWA"
* *Deliverables:* Package the platform as an installable Progressive Web Application. Activate the hybrid graphic rendering pipelines to handle legacy consumer smartphones smoothly.
- **Sprint Goal:** Deliver an installable, empathetic patient portal optimized for lower-spec consumer hardware architectures.
- **Key Epic / Backlog Items:**
- 👵 **Empathetic UI Refactoring:** Build a jargon-free, high-contrast dashboard panel utilizing massive text scaling properties for elderly populations.
- 📱 **PWA Compilation:** Package the frontend application instance as a Progressive Web Application supporting cross-platform mobile browser configurations.
- 📉 **Zero-GPU Fallback System:** Deploy the dual-rendering branch infrastructure, automatically swapping intensive WebGL layers for flat image-sequence turntables on legacy smartphones.
* Sprint 5 | Aug 10 – Aug 21 | "Feedback Pipeline & Hardening"
* *Deliverables:* Establish public feedback channels and system optimization metrics. Optimize image transfer compression layers and configure automated cleanup scripts to prune data directories.
- **Sprint Goal:** Optimize backend asset processing throughput and activate structured community signal logging.
- **Key Epic / Backlog Items:**
- 📊 **Feedback Instrumentation:** Embed standard data-collection portals, project presentation hubs, and simplified error reporting dialogs.
- 🚀 **Performance Optimization:** Optimize image file loading routines, introduce multi-level asset caching, and compress backend array transfers.
- 🧹 **System Pruning:** Deploy background cleanup tasks to automatically purge unmanaged temporary file storage pools.
* Sprint 6 | Aug 24 – Sept 2 | "Beta Release & Evolution"
* *Deliverables:* Push the hardened workspace deployment to the target Vietnamese MSK cohort. Evaluate incoming system feedback metrics to construct the downstream long-term product backlog.
- **Sprint Goal:** Launch the verified pilot ecosystem to the target Vietnamese user fleet and chart long-term architecture steps.
- **Key Epic / Backlog Items:**
- 🚀 **Pilot Launch:** Deploy the application bundle onto local cloud data centers and open system channels to the target Vietnamese MSK medical cohort.
- 📈 **Telemetry Aggregation:** Analyze performance signatures, user friction patterns, and real-world system adoption logs.
- 🗺️ **Product Backlog Maturation:** Evaluate initial feedback metrics to build out a robust, prioritized downstream product feature backlog.
```mermaid
gantt
title VKIST Pilot Project - 3-Month Scrum Timeline Roadmap
dateFormat YYYY-MM-DD
axisFormat %b %d
todayMarker stroke-width:2px,stroke:#ff5555,stroke-dasharray:5
section June 2026
Sprint 0 : active, sp0, 2026-06-02, 2026-06-12
User & Market Discovery :crit, active, 2026-06-02, 2026-06-12
Requirement Engineering :active, 2026-06-02, 2026-06-12
Win pitch on June 9 :milestone, 2026-06-09, 1d
Audit VKIST ML/NLP models :2026-06-02, 2026-06-12
Setup base CI/CD pipeline :2026-06-02, 2026-06-12
Sprint 1 : sp1, 2026-06-15, 2026-06-26
The 'Fast PoC' Baseline :crit, 2026-06-15, 2026-06-26
System design & Figma mockups :2026-06-15, 2026-06-26
Load Ultrasound & wire to ML :2026-06-15, 2026-06-26
Sprint 2 : sp2, 2026-06-29, 2026-07-10
Multi-Modal & NLP Integration :crit, 2026-06-29, 2026-07-10
Decree 13 Data Privacy & Scrub :2026-06-29, 2026-07-10
Integrate NLP advancements :2026-06-29, 2026-07-10
section July 2026
Sprint 3 : sp3, 2026-07-13, 2026-07-24
The Collaborative Workspace :crit, 2026-07-13, 2026-07-24
Real-time annotations & checks :2026-07-13, 2026-07-24
Usability testing with allies :2026-07-13, 2026-07-24
Sprint 4 : sp4, 2026-07-27, 2026-08-07
The Patient-Facing PWA :crit, 2026-07-27, 2026-08-07
Build simplified patient view :2026-07-27, 2026-08-07
Zero-GPU Fallback PWA layer :2026-07-27, 2026-08-07
section Aug - Sept 2026
Sprint 5 : sp5, 2026-08-10, 2026-08-21
Feedback Pipeline & Hardening :crit, 2026-08-10, 2026-08-21
Setup portal & project page :2026-08-10, 2026-08-21
Optimize asset loading speeds :2026-08-10, 2026-08-21
Sprint 6 : sp6, 2026-08-24, 2026-09-02
Beta Release & Evolution :crit, 2026-08-24, 2026-09-02
Analyze incoming feedback logs :2026-08-24, 2026-09-02
Draft future product backlog :2026-08-24, 2026-09-02
Project Cycle Complete :milestone, 2026-09-02, 1d
```
Below is the minimal timeline of the project
| Sprint | Date Range | Focus Block & Core Objectives |
| --- | --- | --- |
| **Sprint 0** | June 02 – June 12 | Pitch & Arch Spike (User/Market Discovery & Requirement Engineering) |
| **Sprint 1** | June 15 – June 26 | The Fast PoC Baseline (Fast & Proof-of-Concept System Validation) |
| **Sprint 2** | June 29 – July 10 | Multi-Modal & NLP Integration (Natural, Zero-Friction Workflows) |
| **Sprint 3** | July 13 – July 24 | The Collaborative Workspace (Multidisciplinary Coordination Layer) |
| **Sprint 4** | July 27 – Aug 07 | The Patient-Facing PWA (Ready & Mobile-Optimized Platform) |
| **Sprint 5** | Aug 10 – Aug 21 | Feedback Pipeline & Hardening (Optimizations & Community Review Loops) |
| **Sprint 6** | Aug 24 – Sept 02 | Beta Launch & Evolution (Deployment to MSK Cohort & Backlog Drafting) |
---
## 6. Project Success Criteria ("Done a Good Job")
1. **Zero Workflow Friction Impact:** Frontline medical specialists can access automated model insights and verify clinical states without adding extra configuration steps or time penalties to their existing routines.
2. **Deterministic Cross-Device Stability:** The user interface achieves smooth performance across the user fleet, successfully scaling down to CPU-bound rendering modes on legacy mobile chipsets without crashing.
3. **Flawless Statutory Compliance Verification:** Zero unencrypted patient data leaks or data non-compliance events recorded during data exchanges, fully satisfying Decree 13 protection protocols.
4. **Sustained User Cohort Retention:** Targeted physical therapists and clinicians actively utilize the structured workspace instead of bypassing the ecosystem in favor of unsecured external messaging networks.
5. **Successful Academic-to-Production Migration:** Smoothly packaging VKIST's core image segmentation and classification files into an optimized, installable, high-efficiency web production application.

BIN
proj_level_reading/PLAN/PILOT_VKIST_PITCHING.pptx Normal file
View File

Binary file not shown.

BIN
proj_level_reading/PLAN/SLIDE_DECK_PDF.pdf Normal file
View File

Binary file not shown.

21
proj_level_reading/Requirement_Analysis/FRs-Database/FR-Engineer-DB .csv Normal file
View File

@@ -0,0 +1,21 @@
ComponentName,ReqID,ReqName,IsOptional,UserProfileCode,Sys/Act,PreCondition,PostCondition,VerboseDescription,Engineer
Prescription Parser / WebML Module,ULTS-Prescription Parser / WebML Module-FR-4,PARSE clinical text on-device,No,UP6,System,[The physical therapist opens the camera scanner within the PWA and captures the text-based prescription],"[The targeted joint zone, therapy modality, and frequency are extracted locally, and any structural contraindication warnings are displayed]","ULTS-Prescription Parser / WebML Module-FR-4: As an [Physical Therapist], provide that [The physical therapist opens the camera scanner within the PWA and captures the text-based prescription], the [System] shall PARSE clinical text on-device, ensuring that [The targeted joint zone, therapy modality, and frequency are extracted locally, and any structural contraindication warnings are displayed]",Đạt Trần Tiến (Daves Tran)
3D Mapping / Visualization Engine,ULTS-3D Mapping / Visualization Engine-FR-5,MAP spatial coordinates to visual models,No,UP6,System,[Abstract text tokens are successfully parsed from the prescription.],[A dynamic visual guide—rendered via WebGL or a zero-GPU CPU-bound 2D image sequence based on device capabilities—with an SVG vector highlight over the target tissue area is displayed.],"ULTS-3D Mapping / Visualization Engine-FR-5: As an [Physical Therapist], provide that [Abstract text tokens are successfully parsed from the prescription.], the [System] shall MAP spatial coordinates to visual models, ensuring that [A dynamic visual guide—rendered via WebGL or a zero-GPU CPU-bound 2D image sequence based on device capabilities—with an SVG vector highlight over the target tissue area is displayed.]",Đạt Trần Tiến (Daves Tran)
Kinetic Overlay Module,ULTS-Kinetic Overlay Module-FR-6,RENDER muscle depth cross-sections,No,UP6,System,[The physical therapist activates the Kinetic Overlay Toggle within the canvas view],[Lightweight HTML SVG paths detailing muscle cross-sections and 1 cm to 5 cm depth color-coding are dynamically appended over the target treatment viewport],"ULTS-Kinetic Overlay Module-FR-6: As an [Physical Therapist], provide that [The physical therapist activates the Kinetic Overlay Toggle within the canvas view], the [System] shall RENDER muscle depth cross-sections, ensuring that [Lightweight HTML SVG paths detailing muscle cross-sections and 1 cm to 5 cm depth color-coding are dynamically appended over the target treatment viewport]",Đạt Trần Tiến (Daves Tran)
Progress Tracking Module,ULTS-Progress Tracking Module-FR-7,LOG kinetic progress pins,No,UP6,System,[The physical therapist taps the screen workspace layer within the distinct Kinetic Tracking Channel.],"[Localized metrics including Range of Motion, 1-10 pain indices, and tissue behavior are serialized and pushed to the physician's tracking panel without mutating the primary medical file.]","ULTS-Progress Tracking Module-FR-7: As an [Physical Therapist], provide that [The physical therapist taps the screen workspace layer within the distinct Kinetic Tracking Channel.], the [System] shall LOG kinetic progress pins, ensuring that [Localized metrics including Range of Motion, 1-10 pain indices, and tissue behavior are serialized and pushed to the physician's tracking panel without mutating the primary medical file.]",Đạt Trần Tiến (Daves Tran)
Patient Education Module,ULTS-Patient Education Module-FR-8,DEMONSTRATE joint mechanics dynamically,No,UP6,System,[The physical therapist moves the HTML Range-of-Motion slider within the Patient Demonstration Mode split layout.],"[A cached array of 2D illustrations seamlessly cycles using 0% GPU power to visually indicate joint flexion, extension, and soft-tissue impingement.]","ULTS-Patient Education Module-FR-8: As an [Physical Therapist], provide that [The physical therapist moves the HTML Range-of-Motion slider within the Patient Demonstration Mode split layout.], the [System] shall DEMONSTRATE joint mechanics dynamically, ensuring that [A cached array of 2D illustrations seamlessly cycles using 0% GPU power to visually indicate joint flexion, extension, and soft-tissue impingement.]",Đạt Trần Tiến (Daves Tran)
DICOM Viewer / Annotation Module,ULTS-DICOM Viewer / Annotation Module-FR-9,RENDER haptic-assisted edge-snapping magnifier,No,UP7,System,[The clinician activates the annotation tool and drags the crosshairs near a high-contrast bone boundary on the multi-touch viewport.],"[A high-magnification lens appears 150px vertically above the touch point, the crosshairs automatically snap to the nearest boundary, and a localized native haptic pulse is triggered.]","ULTS-DICOM Viewer / Annotation Module-FR-9: As an [Rheumatologist & Orthopedic Surgeon], provide that [The clinician activates the annotation tool and drags the crosshairs near a high-contrast bone boundary on the multi-touch viewport.], the [System] shall RENDER haptic-assisted edge-snapping magnifier, ensuring that [A high-magnification lens appears 150px vertically above the touch point, the crosshairs automatically snap to the nearest boundary, and a localized native haptic pulse is triggered.]",Đạt Trần Tiến (Daves Tran)
Asynchronous Communication Engine,ULTS-Asynchronous Communication Engine-FR-10,RECORD asynchronous voice and canvas telemetry (Session Recording & Replay),No,UP7,System,[The sending clinician records audio while navigating the viewport and drawing vectors on the case file workspace.],"[The microphone input and viewport coordinate state changes (X, Y positions, zoom, panning) are compiled into a serialized JSON timeline file for synchronized, threaded playback.]","ULTS-Asynchronous Communication Engine-FR-10: As an [Rheumatologist & Orthopedic Surgeon], provide that [The sending clinician records audio while navigating the viewport and drawing vectors on the case file workspace.], the [System] shall RECORD asynchronous voice and canvas telemetry (Session Recording & Replay), ensuring that [The microphone input and viewport coordinate state changes (X, Y positions, zoom, panning) are compiled into a serialized JSON timeline file for synchronized, threaded playback.]",Đạt Trần Tiến (Daves Tran)
User Interface / Push Notifications,ULTS-User Interface / Push Notifications-FR-11,DISPLAY progressive disclosure sheets and native alerts,No,UP7,System,[A case update occurs or the clinician interacts with the clinical data layout over the active DICOM canvas.],"[A deep-linked native OS push alert is sent, and clinical telemetry is confined within a 3-state (25%, 60%, 100%) expandable native Bottom-Sheet component.]","ULTS-User Interface / Push Notifications-FR-11: As an [Rheumatologist & Orthopedic Surgeon], provide that [A case update occurs or the clinician interacts with the clinical data layout over the active DICOM canvas.], the [System] shall DISPLAY progressive disclosure sheets and native alerts, ensuring that [A deep-linked native OS push alert is sent, and clinical telemetry is confined within a 3-state (25%, 60%, 100%) expandable native Bottom-Sheet component.]",Đạt Trần Tiến (Daves Tran)
Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện.,ULTS-Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện.-FR-20,KẾT NỐI và GỬI Báo cáo Tự kiểm tra cho Bác sĩ Điều trị,No,UP8,System,Bệnh nhân vừa hoàn thành bài tự kiểm tra mức độ viêm (REQ-PAT-03) và phát hiện có dấu hiệu bất thường (đau tăng lên).,"Hệ thống đóng gói lịch sử triệu chứng kèm biểu đồ xu hướng gần nhất, gửi an toàn qua kênh mã hóa tới bác sĩ quản lý ca bệnh để bác sĩ có thể chủ động hẹn lịch tái khám sớm.","ULTS-Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện.-FR-20: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân vừa hoàn thành bài tự kiểm tra mức độ viêm (REQ-PAT-03) và phát hiện có dấu hiệu bất thường (đau tăng lên)., the [System] shall KẾT NỐI và GỬI Báo cáo Tự kiểm tra cho Bác sĩ Điều trị, ensuring that Hệ thống đóng gói lịch sử triệu chứng kèm biểu đồ xu hướng gần nhất, gửi an toàn qua kênh mã hóa tới bác sĩ quản lý ca bệnh để bác sĩ có thể chủ động hẹn lịch tái khám sớm.",tahuykl
Nhắc nhở uống thuốc và thực hiện phác đồ điều trị tại nhà.,ULTS-Nhắc nhở uống thuốc và thực hiện phác đồ điều trị tại nhà.-FR-19,GIÁM SÁT việc bệnh nhân tuân thủ Đơn thuốc và Nhắc nhở Lịch Điều trị,No,UP8,System,Bác sĩ đã kê đơn thuốc (REQ-RAD-05) và phác đồ điều trị được đồng bộ sang tài khoản của bệnh nhân.,"Ứng dụng tự động phát thông báo nhắc nhở giờ uống thuốc, giờ tập vật lý trị liệu cho Bệnh nhân và Người chăm sóc, đồng thời cho phép tích chọn ""Đã uống"" để lưu lại lịch sử tuân thủ điều trị.","ULTS-Nhắc nhở uống thuốc và thực hiện phác đồ điều trị tại nhà.-FR-19: As an [MSK Patient & Family Caregiver], provide that Bác sĩ đã kê đơn thuốc (REQ-RAD-05) và phác đồ điều trị được đồng bộ sang tài khoản của bệnh nhân., the [System] shall GIÁM SÁT việc bệnh nhân tuân thủ Đơn thuốc và Nhắc nhở Lịch Điều trị, ensuring that Ứng dụng tự động phát thông báo nhắc nhở giờ uống thuốc, giờ tập vật lý trị liệu cho Bệnh nhân và Người chăm sóc, đồng thời cho phép tích chọn ""Đã uống"" để lưu lại lịch sử tuân thủ điều trị.",tahuykl
Đánh giá nhanh nguy cơ viêm tái phát qua bảng câu hỏi triệu chứng,ULTS-Đánh giá nhanh nguy cơ viêm tái phát qua bảng câu hỏi triệu chứng-FR-18,SÀNG LỌC và TỰ KIỂM TRA dấu hiệu Viêm tại nhà,No,UP8,System,"Bệnh nhân đang ở nhà (ngoài bệnh viện) và truy cập vào mục ""Kiểm tra sức khỏe định kỳ"" trên ứng dụng.","Hệ thống hiển thị bảng khảo sát tương tác (độ sưng, độ nóng, mức độ đau khi co duỗi); dựa trên câu trả lời, hệ thống tính điểm và đưa ra cảnh báo mức độ viêm lâm sàng hiện tại (Ổn định / Cần theo dõi / Cần đi khám ngay).","ULTS-Đánh giá nhanh nguy cơ viêm tái phát qua bảng câu hỏi triệu chứng-FR-18: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân đang ở nhà (ngoài bệnh viện) và truy cập vào mục ""Kiểm tra sức khỏe định kỳ"" trên ứng dụng., the [System] shall SÀNG LỌC và TỰ KIỂM TRA dấu hiệu Viêm tại nhà, ensuring that Hệ thống hiển thị bảng khảo sát tương tác (độ sưng, độ nóng, mức độ đau khi co duỗi); dựa trên câu trả lời, hệ thống tính điểm và đưa ra cảnh báo mức độ viêm lâm sàng hiện tại (Ổn định / Cần theo dõi / Cần đi khám ngay).",tahuykl
Theo dõi và kiểm tra biến thiên mức độ viêm khớp gối qua các thời kỳ.,ULTS-Theo dõi và kiểm tra biến thiên mức độ viêm khớp gối qua các thời kỳ.-FR-17,KIỂM TRA mức độ viêm trực quan qua Biểu đồ Xu hướng,No,UP8,System,Hệ thống có dữ liệu lịch sử từ ít nhất một lần khám (REQ-PAT-01) trở lên.,"Hệ thống hiển thị một biểu đồ đường (Line chart) trực quan hóa mức độ viêm (từ Nhẹ đến Nặng) và độ dày màng hoạt dịch qua các lần khám, giúp người bệnh biết tình trạng viêm của mình đang thuyên giảm hay tăng lên.","ULTS-Theo dõi và kiểm tra biến thiên mức độ viêm khớp gối qua các thời kỳ.-FR-17: As an [MSK Patient & Family Caregiver], provide that Hệ thống có dữ liệu lịch sử từ ít nhất một lần khám (REQ-PAT-01) trở lên., the [System] shall KIỂM TRA mức độ viêm trực quan qua Biểu đồ Xu hướng, ensuring that Hệ thống hiển thị một biểu đồ đường (Line chart) trực quan hóa mức độ viêm (từ Nhẹ đến Nặng) và độ dày màng hoạt dịch qua các lần khám, giúp người bệnh biết tình trạng viêm của mình đang thuyên giảm hay tăng lên.",tahuykl
Xem và tải về lịch sử các lần siêu âm và khám khớp gối,ULTS-Xem và tải về lịch sử các lần siêu âm và khám khớp gối-FR-16,TRA CỨU lịch sử khám bệnh và Siêu âm Toàn diện,No,UP8,System,Bệnh nhân hoặc Người chăm sóc đăng nhập thành công vào hệ thống bằng tài khoản định danh hợp lệ.,"Hệ thống hiển thị danh sách toàn bộ các mốc thời gian đã khám, cho phép người dùng bấm vào từng ngày để xem lại ảnh siêu âm, đơn thuốc, và các chỉ số đo đạc cũ.","ULTS-Xem và tải về lịch sử các lần siêu âm và khám khớp gối-FR-16: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân hoặc Người chăm sóc đăng nhập thành công vào hệ thống bằng tài khoản định danh hợp lệ., the [System] shall TRA CỨU lịch sử khám bệnh và Siêu âm Toàn diện, ensuring that Hệ thống hiển thị danh sách toàn bộ các mốc thời gian đã khám, cho phép người dùng bấm vào từng ngày để xem lại ảnh siêu âm, đơn thuốc, và các chỉ số đo đạc cũ.",tahuykl
Patient Education Module / 3D Visualization Engine,ULTS-Patient Education Module / 3D Visualization Engine-FR-12,SYNCHRONIZE hardware-adaptive musculoskeletal models,No,UP8,System,[The patient opens the 3D visualization view and the client-side feature detection script evaluates local GPU capabilities.],[Abstract 2D pathologies map to either a real-time WebGL 3D skeletal mesh (High-Spec) or a CPU-bound 36-frame 2D sprite-sheet turntable rendering at 10° increments (Low-Spec).],"ULTS-Patient Education Module / 3D Visualization Engine-FR-12: As an [MSK Patient & Family Caregiver], provide that [The patient opens the 3D visualization view and the client-side feature detection script evaluates local GPU capabilities.], the [System] shall SYNCHRONIZE hardware-adaptive musculoskeletal models, ensuring that [Abstract 2D pathologies map to either a real-time WebGL 3D skeletal mesh (High-Spec) or a CPU-bound 36-frame 2D sprite-sheet turntable rendering at 10° increments (Low-Spec).]",Đạt Trần Tiến (Daves Tran)
Patient Portal / Security Module,ULTS-Patient Portal / Security Module-FR-13,ENCRYPT and deliver sanitized patient payloads,No,UP8,System,"[The patient provides explicit, native opt-in consent and scans the unique 14-day tokenized QR code or deep link.]","[The locally AES-256 encrypted, sanitized, and flattened locomotive health summary loads into an adaptive dashboard in ≤ 2.0 seconds.]","ULTS-Patient Portal / Security Module-FR-13: As an [MSK Patient & Family Caregiver], provide that [The patient provides explicit, native opt-in consent and scans the unique 14-day tokenized QR code or deep link.], the [System] shall ENCRYPT and deliver sanitized patient payloads, ensuring that [The locally AES-256 encrypted, sanitized, and flattened locomotive health summary loads into an adaptive dashboard in ≤ 2.0 seconds.]",Đạt Trần Tiến (Daves Tran)
Đề xuất danh mục thuốc kháng viêm và giảm đau theo ca bệnh,ULTS-Đề xuất danh mục thuốc kháng viêm và giảm đau theo ca bệnh-FR-27,ĐỀ XUẤT Đơn thuốc Hỗ trợ (Clinical Decision Support),No,UP5,System,"Chẩn đoán mức độ viêm đã có và bác sĩ lựa chọn phương án ""Điều trị nội khoa bằng thuốc"" (REQ-RAD-04)","Hệ thống đưa ra danh sách các loại thuốc phù hợp (ví dụ: NSAIDs, Thuốc chống bôi trơn khớp) kèm liều lượng khuyến cáo dựa trên mức độ viêm, kiểm tra tương tác thuốc/chống chỉ định, hỗ trợ bác sĩ xuất đơn thuốc nhanh chóng","ULTS-Đề xuất danh mục thuốc kháng viêm và giảm đau theo ca bệnh-FR-27: As an [Diagnostic Radiologist], provide that Chẩn đoán mức độ viêm đã có và bác sĩ lựa chọn phương án ""Điều trị nội khoa bằng thuốc"" (REQ-RAD-04), the [System] shall ĐỀ XUẤT Đơn thuốc Hỗ trợ (Clinical Decision Support), ensuring that Hệ thống đưa ra danh sách các loại thuốc phù hợp (ví dụ: NSAIDs, Thuốc chống bôi trơn khớp) kèm liều lượng khuyến cáo dựa trên mức độ viêm, kiểm tra tương tác thuốc/chống chỉ định, hỗ trợ bác sĩ xuất đơn thuốc nhanh chóng",tahuykl
Gợi ý phương án điều trị dựa trên mức độ viêm khớp gối,ULTS-Gợi ý phương án điều trị dựa trên mức độ viêm khớp gối-FR-26,ĐỀ XUẤT Phác đồ Điều trị và Kế hoạch Can thiệp,No,UP5,System,Bác sĩ đã phê duyệt và khóa kết quả chẩn đoán mức độ viêm,"Hệ thống hiển thị các gợi ý điều trị tương ứng (ví dụ: Viêm nhẹ, tiến hành Vật lý trị liệu/Nghỉ ngơi; Viêm nặng tiến hành Chọc hút dịch khớp dưới hướng dẫn siêu âm/Tiêm corticoid nội khớp) để bác sĩ lựa chọn và đưa vào báo cáo.","ULTS-Gợi ý phương án điều trị dựa trên mức độ viêm khớp gối-FR-26: As an [Diagnostic Radiologist], provide that Bác sĩ đã phê duyệt và khóa kết quả chẩn đoán mức độ viêm, the [System] shall ĐỀ XUẤT Phác đồ Điều trị và Kế hoạch Can thiệp, ensuring that Hệ thống hiển thị các gợi ý điều trị tương ứng (ví dụ: Viêm nhẹ, tiến hành Vật lý trị liệu/Nghỉ ngơi; Viêm nặng tiến hành Chọc hút dịch khớp dưới hướng dẫn siêu âm/Tiêm corticoid nội khớp) để bác sĩ lựa chọn và đưa vào báo cáo.",tahuykl
Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading),ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)-FR-25,CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối,No,UP5,System,Hệ thống đã ghi nhận độ dày màng hoạt dịch (REQ-RAD-02) và kết quả quét Doppler dòng máu (Hypervascularity),"Hệ thống đưa ra gợi ý chẩn đoán mức độ viêm theo thang chuẩn y khoa (ví dụ: Không viêm, Viêm nhẹ - Độ 1, Viêm vừa - Độ 2, Viêm nặng - Độ 3) để bác sĩ xác nhận hoặc điều chỉnh","ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)-FR-25: As an [Diagnostic Radiologist], provide that Hệ thống đã ghi nhận độ dày màng hoạt dịch (REQ-RAD-02) và kết quả quét Doppler dòng máu (Hypervascularity), the [System] shall CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối, ensuring that Hệ thống đưa ra gợi ý chẩn đoán mức độ viêm theo thang chuẩn y khoa (ví dụ: Không viêm, Viêm nhẹ - Độ 1, Viêm vừa - Độ 2, Viêm nặng - Độ 3) để bác sĩ xác nhận hoặc điều chỉnh",tahuykl
Đo độ dày màng hoạt dịch tại ngách trên xương bánh chè,ULTS-Đo độ dày màng hoạt dịch tại ngách trên xương bánh chè-FR-24,ĐO Độ dày Màng hoạt dịch Tự động,No,UP5,System,Tính năng phân vùng (REQ-RAD-01) đã xác định được lớp màng hoạt dịch (Synovium) trên hình ảnh siêu âm,"Hệ thống tự động hiển thị thước đo (bằng milimet) tại điểm dày nhất của màng hoạt dịch, cho phép bác sĩ kéo thả điều chỉnh thủ công và lưu thông số này vào hồ sơ đo đạc của ca bệnh","ULTS-Đo độ dày màng hoạt dịch tại ngách trên xương bánh chè-FR-24: As an [Diagnostic Radiologist], provide that Tính năng phân vùng (REQ-RAD-01) đã xác định được lớp màng hoạt dịch (Synovium) trên hình ảnh siêu âm, the [System] shall ĐO Độ dày Màng hoạt dịch Tự động, ensuring that Hệ thống tự động hiển thị thước đo (bằng milimet) tại điểm dày nhất của màng hoạt dịch, cho phép bác sĩ kéo thả điều chỉnh thủ công và lưu thông số này vào hồ sơ đo đạc của ca bệnh",tahuykl
Phân vùng hình ảnh cấu trúc giải phẫu khớp gối bằng AI,ULTS-Phân vùng hình ảnh cấu trúc giải phẫu khớp gối bằng AI-FR-23,PHÂN VÙNG Tự động các Bộ phận Khớp gối (Image Segmentation),No,UP5,System,Bác sĩ đã tải lên hoặc chụp thành công hình ảnh cắt dọc/cắt ngang của khớp gối trên hệ thống,"Hệ thống tự động nhận diện, phân vùng và tô màu phân biệt các bộ phận (gân bánh chè, sụn chêm, xương đùi, xương chày, màng hoạt dịch) trên màn hình mà không làm mờ ảnh gốc.","ULTS-Phân vùng hình ảnh cấu trúc giải phẫu khớp gối bằng AI-FR-23: As an [Diagnostic Radiologist], provide that Bác sĩ đã tải lên hoặc chụp thành công hình ảnh cắt dọc/cắt ngang của khớp gối trên hệ thống, the [System] shall PHÂN VÙNG Tự động các Bộ phận Khớp gối (Image Segmentation), ensuring that Hệ thống tự động nhận diện, phân vùng và tô màu phân biệt các bộ phận (gân bánh chè, sụn chêm, xương đùi, xương chày, màng hoạt dịch) trên màn hình mà không làm mờ ảnh gốc.",tahuykl
1 ComponentName ReqID ReqName IsOptional UserProfileCode Sys/Act PreCondition PostCondition VerboseDescription Engineer
2 Prescription Parser / WebML Module ULTS-Prescription Parser / WebML Module-FR-4 PARSE clinical text on-device No UP6 System [The physical therapist opens the camera scanner within the PWA and captures the text-based prescription] [The targeted joint zone, therapy modality, and frequency are extracted locally, and any structural contraindication warnings are displayed] ULTS-Prescription Parser / WebML Module-FR-4: As an [Physical Therapist], provide that [The physical therapist opens the camera scanner within the PWA and captures the text-based prescription], the [System] shall PARSE clinical text on-device, ensuring that [The targeted joint zone, therapy modality, and frequency are extracted locally, and any structural contraindication warnings are displayed] Đạt Trần Tiến (Daves Tran)
3 3D Mapping / Visualization Engine ULTS-3D Mapping / Visualization Engine-FR-5 MAP spatial coordinates to visual models No UP6 System [Abstract text tokens are successfully parsed from the prescription.] [A dynamic visual guide—rendered via WebGL or a zero-GPU CPU-bound 2D image sequence based on device capabilities—with an SVG vector highlight over the target tissue area is displayed.] ULTS-3D Mapping / Visualization Engine-FR-5: As an [Physical Therapist], provide that [Abstract text tokens are successfully parsed from the prescription.], the [System] shall MAP spatial coordinates to visual models, ensuring that [A dynamic visual guide—rendered via WebGL or a zero-GPU CPU-bound 2D image sequence based on device capabilities—with an SVG vector highlight over the target tissue area is displayed.] Đạt Trần Tiến (Daves Tran)
4 Kinetic Overlay Module ULTS-Kinetic Overlay Module-FR-6 RENDER muscle depth cross-sections No UP6 System [The physical therapist activates the Kinetic Overlay Toggle within the canvas view] [Lightweight HTML SVG paths detailing muscle cross-sections and 1 cm to 5 cm depth color-coding are dynamically appended over the target treatment viewport] ULTS-Kinetic Overlay Module-FR-6: As an [Physical Therapist], provide that [The physical therapist activates the Kinetic Overlay Toggle within the canvas view], the [System] shall RENDER muscle depth cross-sections, ensuring that [Lightweight HTML SVG paths detailing muscle cross-sections and 1 cm to 5 cm depth color-coding are dynamically appended over the target treatment viewport] Đạt Trần Tiến (Daves Tran)
5 Progress Tracking Module ULTS-Progress Tracking Module-FR-7 LOG kinetic progress pins No UP6 System [The physical therapist taps the screen workspace layer within the distinct Kinetic Tracking Channel.] [Localized metrics including Range of Motion, 1-10 pain indices, and tissue behavior are serialized and pushed to the physician's tracking panel without mutating the primary medical file.] ULTS-Progress Tracking Module-FR-7: As an [Physical Therapist], provide that [The physical therapist taps the screen workspace layer within the distinct Kinetic Tracking Channel.], the [System] shall LOG kinetic progress pins, ensuring that [Localized metrics including Range of Motion, 1-10 pain indices, and tissue behavior are serialized and pushed to the physician's tracking panel without mutating the primary medical file.] Đạt Trần Tiến (Daves Tran)
6 Patient Education Module ULTS-Patient Education Module-FR-8 DEMONSTRATE joint mechanics dynamically No UP6 System [The physical therapist moves the HTML Range-of-Motion slider within the Patient Demonstration Mode split layout.] [A cached array of 2D illustrations seamlessly cycles using 0% GPU power to visually indicate joint flexion, extension, and soft-tissue impingement.] ULTS-Patient Education Module-FR-8: As an [Physical Therapist], provide that [The physical therapist moves the HTML Range-of-Motion slider within the Patient Demonstration Mode split layout.], the [System] shall DEMONSTRATE joint mechanics dynamically, ensuring that [A cached array of 2D illustrations seamlessly cycles using 0% GPU power to visually indicate joint flexion, extension, and soft-tissue impingement.] Đạt Trần Tiến (Daves Tran)
7 DICOM Viewer / Annotation Module ULTS-DICOM Viewer / Annotation Module-FR-9 RENDER haptic-assisted edge-snapping magnifier No UP7 System [The clinician activates the annotation tool and drags the crosshairs near a high-contrast bone boundary on the multi-touch viewport.] [A high-magnification lens appears 150px vertically above the touch point, the crosshairs automatically snap to the nearest boundary, and a localized native haptic pulse is triggered.] ULTS-DICOM Viewer / Annotation Module-FR-9: As an [Rheumatologist & Orthopedic Surgeon], provide that [The clinician activates the annotation tool and drags the crosshairs near a high-contrast bone boundary on the multi-touch viewport.], the [System] shall RENDER haptic-assisted edge-snapping magnifier, ensuring that [A high-magnification lens appears 150px vertically above the touch point, the crosshairs automatically snap to the nearest boundary, and a localized native haptic pulse is triggered.] Đạt Trần Tiến (Daves Tran)
8 Asynchronous Communication Engine ULTS-Asynchronous Communication Engine-FR-10 RECORD asynchronous voice and canvas telemetry (Session Recording & Replay) No UP7 System [The sending clinician records audio while navigating the viewport and drawing vectors on the case file workspace.] [The microphone input and viewport coordinate state changes (X, Y positions, zoom, panning) are compiled into a serialized JSON timeline file for synchronized, threaded playback.] ULTS-Asynchronous Communication Engine-FR-10: As an [Rheumatologist & Orthopedic Surgeon], provide that [The sending clinician records audio while navigating the viewport and drawing vectors on the case file workspace.], the [System] shall RECORD asynchronous voice and canvas telemetry (Session Recording & Replay), ensuring that [The microphone input and viewport coordinate state changes (X, Y positions, zoom, panning) are compiled into a serialized JSON timeline file for synchronized, threaded playback.] Đạt Trần Tiến (Daves Tran)
9 User Interface / Push Notifications ULTS-User Interface / Push Notifications-FR-11 DISPLAY progressive disclosure sheets and native alerts No UP7 System [A case update occurs or the clinician interacts with the clinical data layout over the active DICOM canvas.] [A deep-linked native OS push alert is sent, and clinical telemetry is confined within a 3-state (25%, 60%, 100%) expandable native Bottom-Sheet component.] ULTS-User Interface / Push Notifications-FR-11: As an [Rheumatologist & Orthopedic Surgeon], provide that [A case update occurs or the clinician interacts with the clinical data layout over the active DICOM canvas.], the [System] shall DISPLAY progressive disclosure sheets and native alerts, ensuring that [A deep-linked native OS push alert is sent, and clinical telemetry is confined within a 3-state (25%, 60%, 100%) expandable native Bottom-Sheet component.] Đạt Trần Tiến (Daves Tran)
10 Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện. ULTS-Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện.-FR-20 KẾT NỐI và GỬI Báo cáo Tự kiểm tra cho Bác sĩ Điều trị No UP8 System Bệnh nhân vừa hoàn thành bài tự kiểm tra mức độ viêm (REQ-PAT-03) và phát hiện có dấu hiệu bất thường (đau tăng lên). Hệ thống đóng gói lịch sử triệu chứng kèm biểu đồ xu hướng gần nhất, gửi an toàn qua kênh mã hóa tới bác sĩ quản lý ca bệnh để bác sĩ có thể chủ động hẹn lịch tái khám sớm. ULTS-Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện.-FR-20: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân vừa hoàn thành bài tự kiểm tra mức độ viêm (REQ-PAT-03) và phát hiện có dấu hiệu bất thường (đau tăng lên)., the [System] shall KẾT NỐI và GỬI Báo cáo Tự kiểm tra cho Bác sĩ Điều trị, ensuring that Hệ thống đóng gói lịch sử triệu chứng kèm biểu đồ xu hướng gần nhất, gửi an toàn qua kênh mã hóa tới bác sĩ quản lý ca bệnh để bác sĩ có thể chủ động hẹn lịch tái khám sớm. tahuykl
11 Nhắc nhở uống thuốc và thực hiện phác đồ điều trị tại nhà. ULTS-Nhắc nhở uống thuốc và thực hiện phác đồ điều trị tại nhà.-FR-19 GIÁM SÁT việc bệnh nhân tuân thủ Đơn thuốc và Nhắc nhở Lịch Điều trị No UP8 System Bác sĩ đã kê đơn thuốc (REQ-RAD-05) và phác đồ điều trị được đồng bộ sang tài khoản của bệnh nhân. Ứng dụng tự động phát thông báo nhắc nhở giờ uống thuốc, giờ tập vật lý trị liệu cho Bệnh nhân và Người chăm sóc, đồng thời cho phép tích chọn "Đã uống" để lưu lại lịch sử tuân thủ điều trị. ULTS-Nhắc nhở uống thuốc và thực hiện phác đồ điều trị tại nhà.-FR-19: As an [MSK Patient & Family Caregiver], provide that Bác sĩ đã kê đơn thuốc (REQ-RAD-05) và phác đồ điều trị được đồng bộ sang tài khoản của bệnh nhân., the [System] shall GIÁM SÁT việc bệnh nhân tuân thủ Đơn thuốc và Nhắc nhở Lịch Điều trị, ensuring that Ứng dụng tự động phát thông báo nhắc nhở giờ uống thuốc, giờ tập vật lý trị liệu cho Bệnh nhân và Người chăm sóc, đồng thời cho phép tích chọn "Đã uống" để lưu lại lịch sử tuân thủ điều trị. tahuykl
12 Đánh giá nhanh nguy cơ viêm tái phát qua bảng câu hỏi triệu chứng ULTS-Đánh giá nhanh nguy cơ viêm tái phát qua bảng câu hỏi triệu chứng-FR-18 SÀNG LỌC và TỰ KIỂM TRA dấu hiệu Viêm tại nhà No UP8 System Bệnh nhân đang ở nhà (ngoài bệnh viện) và truy cập vào mục "Kiểm tra sức khỏe định kỳ" trên ứng dụng. Hệ thống hiển thị bảng khảo sát tương tác (độ sưng, độ nóng, mức độ đau khi co duỗi); dựa trên câu trả lời, hệ thống tính điểm và đưa ra cảnh báo mức độ viêm lâm sàng hiện tại (Ổn định / Cần theo dõi / Cần đi khám ngay). ULTS-Đánh giá nhanh nguy cơ viêm tái phát qua bảng câu hỏi triệu chứng-FR-18: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân đang ở nhà (ngoài bệnh viện) và truy cập vào mục "Kiểm tra sức khỏe định kỳ" trên ứng dụng., the [System] shall SÀNG LỌC và TỰ KIỂM TRA dấu hiệu Viêm tại nhà, ensuring that Hệ thống hiển thị bảng khảo sát tương tác (độ sưng, độ nóng, mức độ đau khi co duỗi); dựa trên câu trả lời, hệ thống tính điểm và đưa ra cảnh báo mức độ viêm lâm sàng hiện tại (Ổn định / Cần theo dõi / Cần đi khám ngay). tahuykl
13 Theo dõi và kiểm tra biến thiên mức độ viêm khớp gối qua các thời kỳ. ULTS-Theo dõi và kiểm tra biến thiên mức độ viêm khớp gối qua các thời kỳ.-FR-17 KIỂM TRA mức độ viêm trực quan qua Biểu đồ Xu hướng No UP8 System Hệ thống có dữ liệu lịch sử từ ít nhất một lần khám (REQ-PAT-01) trở lên. Hệ thống hiển thị một biểu đồ đường (Line chart) trực quan hóa mức độ viêm (từ Nhẹ đến Nặng) và độ dày màng hoạt dịch qua các lần khám, giúp người bệnh biết tình trạng viêm của mình đang thuyên giảm hay tăng lên. ULTS-Theo dõi và kiểm tra biến thiên mức độ viêm khớp gối qua các thời kỳ.-FR-17: As an [MSK Patient & Family Caregiver], provide that Hệ thống có dữ liệu lịch sử từ ít nhất một lần khám (REQ-PAT-01) trở lên., the [System] shall KIỂM TRA mức độ viêm trực quan qua Biểu đồ Xu hướng, ensuring that Hệ thống hiển thị một biểu đồ đường (Line chart) trực quan hóa mức độ viêm (từ Nhẹ đến Nặng) và độ dày màng hoạt dịch qua các lần khám, giúp người bệnh biết tình trạng viêm của mình đang thuyên giảm hay tăng lên. tahuykl
14 Xem và tải về lịch sử các lần siêu âm và khám khớp gối ULTS-Xem và tải về lịch sử các lần siêu âm và khám khớp gối-FR-16 TRA CỨU lịch sử khám bệnh và Siêu âm Toàn diện No UP8 System Bệnh nhân hoặc Người chăm sóc đăng nhập thành công vào hệ thống bằng tài khoản định danh hợp lệ. Hệ thống hiển thị danh sách toàn bộ các mốc thời gian đã khám, cho phép người dùng bấm vào từng ngày để xem lại ảnh siêu âm, đơn thuốc, và các chỉ số đo đạc cũ. ULTS-Xem và tải về lịch sử các lần siêu âm và khám khớp gối-FR-16: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân hoặc Người chăm sóc đăng nhập thành công vào hệ thống bằng tài khoản định danh hợp lệ., the [System] shall TRA CỨU lịch sử khám bệnh và Siêu âm Toàn diện, ensuring that Hệ thống hiển thị danh sách toàn bộ các mốc thời gian đã khám, cho phép người dùng bấm vào từng ngày để xem lại ảnh siêu âm, đơn thuốc, và các chỉ số đo đạc cũ. tahuykl
15 Patient Education Module / 3D Visualization Engine ULTS-Patient Education Module / 3D Visualization Engine-FR-12 SYNCHRONIZE hardware-adaptive musculoskeletal models No UP8 System [The patient opens the 3D visualization view and the client-side feature detection script evaluates local GPU capabilities.] [Abstract 2D pathologies map to either a real-time WebGL 3D skeletal mesh (High-Spec) or a CPU-bound 36-frame 2D sprite-sheet turntable rendering at 10° increments (Low-Spec).] ULTS-Patient Education Module / 3D Visualization Engine-FR-12: As an [MSK Patient & Family Caregiver], provide that [The patient opens the 3D visualization view and the client-side feature detection script evaluates local GPU capabilities.], the [System] shall SYNCHRONIZE hardware-adaptive musculoskeletal models, ensuring that [Abstract 2D pathologies map to either a real-time WebGL 3D skeletal mesh (High-Spec) or a CPU-bound 36-frame 2D sprite-sheet turntable rendering at 10° increments (Low-Spec).] Đạt Trần Tiến (Daves Tran)
16 Patient Portal / Security Module ULTS-Patient Portal / Security Module-FR-13 ENCRYPT and deliver sanitized patient payloads No UP8 System [The patient provides explicit, native opt-in consent and scans the unique 14-day tokenized QR code or deep link.] [The locally AES-256 encrypted, sanitized, and flattened locomotive health summary loads into an adaptive dashboard in ≤ 2.0 seconds.] ULTS-Patient Portal / Security Module-FR-13: As an [MSK Patient & Family Caregiver], provide that [The patient provides explicit, native opt-in consent and scans the unique 14-day tokenized QR code or deep link.], the [System] shall ENCRYPT and deliver sanitized patient payloads, ensuring that [The locally AES-256 encrypted, sanitized, and flattened locomotive health summary loads into an adaptive dashboard in ≤ 2.0 seconds.] Đạt Trần Tiến (Daves Tran)
17 Đề xuất danh mục thuốc kháng viêm và giảm đau theo ca bệnh ULTS-Đề xuất danh mục thuốc kháng viêm và giảm đau theo ca bệnh-FR-27 ĐỀ XUẤT Đơn thuốc Hỗ trợ (Clinical Decision Support) No UP5 System Chẩn đoán mức độ viêm đã có và bác sĩ lựa chọn phương án "Điều trị nội khoa bằng thuốc" (REQ-RAD-04) Hệ thống đưa ra danh sách các loại thuốc phù hợp (ví dụ: NSAIDs, Thuốc chống bôi trơn khớp) kèm liều lượng khuyến cáo dựa trên mức độ viêm, kiểm tra tương tác thuốc/chống chỉ định, hỗ trợ bác sĩ xuất đơn thuốc nhanh chóng ULTS-Đề xuất danh mục thuốc kháng viêm và giảm đau theo ca bệnh-FR-27: As an [Diagnostic Radiologist], provide that Chẩn đoán mức độ viêm đã có và bác sĩ lựa chọn phương án "Điều trị nội khoa bằng thuốc" (REQ-RAD-04), the [System] shall ĐỀ XUẤT Đơn thuốc Hỗ trợ (Clinical Decision Support), ensuring that Hệ thống đưa ra danh sách các loại thuốc phù hợp (ví dụ: NSAIDs, Thuốc chống bôi trơn khớp) kèm liều lượng khuyến cáo dựa trên mức độ viêm, kiểm tra tương tác thuốc/chống chỉ định, hỗ trợ bác sĩ xuất đơn thuốc nhanh chóng tahuykl
18 Gợi ý phương án điều trị dựa trên mức độ viêm khớp gối ULTS-Gợi ý phương án điều trị dựa trên mức độ viêm khớp gối-FR-26 ĐỀ XUẤT Phác đồ Điều trị và Kế hoạch Can thiệp No UP5 System Bác sĩ đã phê duyệt và khóa kết quả chẩn đoán mức độ viêm Hệ thống hiển thị các gợi ý điều trị tương ứng (ví dụ: Viêm nhẹ, tiến hành Vật lý trị liệu/Nghỉ ngơi; Viêm nặng tiến hành Chọc hút dịch khớp dưới hướng dẫn siêu âm/Tiêm corticoid nội khớp) để bác sĩ lựa chọn và đưa vào báo cáo. ULTS-Gợi ý phương án điều trị dựa trên mức độ viêm khớp gối-FR-26: As an [Diagnostic Radiologist], provide that Bác sĩ đã phê duyệt và khóa kết quả chẩn đoán mức độ viêm, the [System] shall ĐỀ XUẤT Phác đồ Điều trị và Kế hoạch Can thiệp, ensuring that Hệ thống hiển thị các gợi ý điều trị tương ứng (ví dụ: Viêm nhẹ, tiến hành Vật lý trị liệu/Nghỉ ngơi; Viêm nặng tiến hành Chọc hút dịch khớp dưới hướng dẫn siêu âm/Tiêm corticoid nội khớp) để bác sĩ lựa chọn và đưa vào báo cáo. tahuykl
19 Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading) ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)-FR-25 CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối No UP5 System Hệ thống đã ghi nhận độ dày màng hoạt dịch (REQ-RAD-02) và kết quả quét Doppler dòng máu (Hypervascularity) Hệ thống đưa ra gợi ý chẩn đoán mức độ viêm theo thang chuẩn y khoa (ví dụ: Không viêm, Viêm nhẹ - Độ 1, Viêm vừa - Độ 2, Viêm nặng - Độ 3) để bác sĩ xác nhận hoặc điều chỉnh ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)-FR-25: As an [Diagnostic Radiologist], provide that Hệ thống đã ghi nhận độ dày màng hoạt dịch (REQ-RAD-02) và kết quả quét Doppler dòng máu (Hypervascularity), the [System] shall CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối, ensuring that Hệ thống đưa ra gợi ý chẩn đoán mức độ viêm theo thang chuẩn y khoa (ví dụ: Không viêm, Viêm nhẹ - Độ 1, Viêm vừa - Độ 2, Viêm nặng - Độ 3) để bác sĩ xác nhận hoặc điều chỉnh tahuykl
20 Đo độ dày màng hoạt dịch tại ngách trên xương bánh chè ULTS-Đo độ dày màng hoạt dịch tại ngách trên xương bánh chè-FR-24 ĐO Độ dày Màng hoạt dịch Tự động No UP5 System Tính năng phân vùng (REQ-RAD-01) đã xác định được lớp màng hoạt dịch (Synovium) trên hình ảnh siêu âm Hệ thống tự động hiển thị thước đo (bằng milimet) tại điểm dày nhất của màng hoạt dịch, cho phép bác sĩ kéo thả điều chỉnh thủ công và lưu thông số này vào hồ sơ đo đạc của ca bệnh ULTS-Đo độ dày màng hoạt dịch tại ngách trên xương bánh chè-FR-24: As an [Diagnostic Radiologist], provide that Tính năng phân vùng (REQ-RAD-01) đã xác định được lớp màng hoạt dịch (Synovium) trên hình ảnh siêu âm, the [System] shall ĐO Độ dày Màng hoạt dịch Tự động, ensuring that Hệ thống tự động hiển thị thước đo (bằng milimet) tại điểm dày nhất của màng hoạt dịch, cho phép bác sĩ kéo thả điều chỉnh thủ công và lưu thông số này vào hồ sơ đo đạc của ca bệnh tahuykl
21 Phân vùng hình ảnh cấu trúc giải phẫu khớp gối bằng AI ULTS-Phân vùng hình ảnh cấu trúc giải phẫu khớp gối bằng AI-FR-23 PHÂN VÙNG Tự động các Bộ phận Khớp gối (Image Segmentation) No UP5 System Bác sĩ đã tải lên hoặc chụp thành công hình ảnh cắt dọc/cắt ngang của khớp gối trên hệ thống Hệ thống tự động nhận diện, phân vùng và tô màu phân biệt các bộ phận (gân bánh chè, sụn chêm, xương đùi, xương chày, màng hoạt dịch) trên màn hình mà không làm mờ ảnh gốc. ULTS-Phân vùng hình ảnh cấu trúc giải phẫu khớp gối bằng AI-FR-23: As an [Diagnostic Radiologist], provide that Bác sĩ đã tải lên hoặc chụp thành công hình ảnh cắt dọc/cắt ngang của khớp gối trên hệ thống, the [System] shall PHÂN VÙNG Tự động các Bộ phận Khớp gối (Image Segmentation), ensuring that Hệ thống tự động nhận diện, phân vùng và tô màu phân biệt các bộ phận (gân bánh chè, sụn chêm, xương đùi, xương chày, màng hoạt dịch) trên màn hình mà không làm mờ ảnh gốc. tahuykl

15
proj_level_reading/Requirement_Analysis/FRs-Database/FR_Engineer_DB_Mobile.csv Normal file
View File

@@ -0,0 +1,15 @@
ComponentName,Device,ReqID,ReqName,Priority,IsOptional,Drop,LinkUseCases,EngineerDesignUC,UserProfileCode,Sys/Act,PreCondition,PostCondition,VerboseDescription,Engineer
Progress Tracking Module,Mobile Web,ULTS-Progress Tracking Module-FR-7,RECORD Asynchronous PT Progress Metrics,,No,No,,,UP6,System,[The physical therapist taps the screen workspace layer within the distinct Kinetic Tracking Channel.],"[Localized metrics including Range of Motion, 1-10 pain indices, and tissue behavior are serialized and pushed to the physician's tracking panel without mutating the primary medical file.]","ULTS-Progress Tracking Module-FR-7: As an [Physical Therapist], provide that [The physical therapist taps the screen workspace layer within the distinct Kinetic Tracking Channel.], the [System] shall RECORD Asynchronous PT Progress Metrics, ensuring that [Localized metrics including Range of Motion, 1-10 pain indices, and tissue behavior are serialized and pushed to the physician's tracking panel without mutating the primary medical file.]",Đạt Trần Tiến (Daves Tran)
Patient Education Module,Mobile Web,ULTS-Patient Education Module-FR-8,DEMONSTRATE joint mechanics dynamically during physical therapy section,-1,No,No,,,UP6,System,[The physical therapist moves the HTML Range-of-Motion slider within the Patient Demonstration Mode split layout.],"[A cached array of 2D illustrations seamlessly cycles using 0% GPU power to visually indicate joint flexion, extension, and soft-tissue impingement.]","ULTS-Patient Education Module-FR-8: As an [Physical Therapist], provide that [The physical therapist moves the HTML Range-of-Motion slider within the Patient Demonstration Mode split layout.], the [System] shall DEMONSTRATE joint mechanics dynamically during physical therapy section, ensuring that [A cached array of 2D illustrations seamlessly cycles using 0% GPU power to visually indicate joint flexion, extension, and soft-tissue impingement.]",Đạt Trần Tiến (Daves Tran)
Patient Education / Care Logic Module,Mobile Web,ULTS-Patient Education / Care Logic Module-FR-19,NHẮC NHỞ việc bệnh nhân tuân thủ Đơn thuốc và lịch Điều trị,,No,No,,tahuykl,UP8,System,Bác sĩ đã kê đơn thuốc (REQ-RAD-05) và phác đồ điều trị được đồng bộ sang tài khoản của bệnh nhân.,"Ứng dụng tự động phát thông báo nhắc nhở giờ uống thuốc, giờ tập vật lý trị liệu cho Bệnh nhân và Người chăm sóc, đồng thời cho phép tích chọn ""Đã uống"" để lưu lại lịch sử tuân thủ điều trị.","ULTS-Patient Education / Care Logic Module-FR-19: As an [MSK Patient & Family Caregiver], provide that Bác sĩ đã kê đơn thuốc (REQ-RAD-05) và phác đồ điều trị được đồng bộ sang tài khoản của bệnh nhân., the [System] shall NHẮC NHỞ việc bệnh nhân tuân thủ Đơn thuốc và lịch Điều trị, ensuring that Ứng dụng tự động phát thông báo nhắc nhở giờ uống thuốc, giờ tập vật lý trị liệu cho Bệnh nhân và Người chăm sóc, đồng thời cho phép tích chọn ""Đã uống"" để lưu lại lịch sử tuân thủ điều trị.",tahuykl
Xem và tải về lịch sử các lần siêu âm và khám khớp gối,Mobile Web,ULTS-Xem và tải về lịch sử các lần siêu âm và khám khớp gối-FR-16,TRA CỨU lịch sử khám bệnh và Siêu âm Toàn diện,,No,No,,tahuykl,UP8,System,Bệnh nhân hoặc Người chăm sóc đăng nhập thành công vào hệ thống bằng tài khoản định danh hợp lệ.,"Hệ thống hiển thị danh sách toàn bộ các mốc thời gian đã khám, cho phép người dùng bấm vào từng ngày để xem lại ảnh siêu âm, đơn thuốc, và các chỉ số đo đạc cũ.","ULTS-Xem và tải về lịch sử các lần siêu âm và khám khớp gối-FR-16: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân hoặc Người chăm sóc đăng nhập thành công vào hệ thống bằng tài khoản định danh hợp lệ., the [System] shall TRA CỨU lịch sử khám bệnh và Siêu âm Toàn diện, ensuring that Hệ thống hiển thị danh sách toàn bộ các mốc thời gian đã khám, cho phép người dùng bấm vào từng ngày để xem lại ảnh siêu âm, đơn thuốc, và các chỉ số đo đạc cũ.",tahuykl
Tạo mới nhật ký chữa bệnh khớp gối cho bệnh nhân,Mobile Web,ULTS-Tạo mới nhật ký chữa bệnh khớp gối cho bệnh nhân-FR-28,CREATE patient treatment journal,,No,No,,tahuykl,UP8,System,Bệnh nhân hoặc Người chăm sóc đã đăng nhập thành công vào tài khoản hệ thống (ứng dụng di động hoặc cổng thông tin bệnh nhân) và hồ sơ bệnh án siêu âm khớp gối hiện tại đang ở trạng thái kích hoạt.,"Hệ thống khởi tạo thành công một biểu mẫu nhật ký mới gắn liền với đợt điều trị hiện tại, thiết lập sẵn các trường thông tin cần theo dõi (như mức độ đau, độ sưng gối, các triệu chứng bất thường, trạng thái dùng thuốc) và sẵn sàng cho lượt nhập liệu đầu tiên.","ULTS-Tạo mới nhật ký chữa bệnh khớp gối cho bệnh nhân-FR-28: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân hoặc Người chăm sóc đã đăng nhập thành công vào tài khoản hệ thống (ứng dụng di động hoặc cổng thông tin bệnh nhân) và hồ sơ bệnh án siêu âm khớp gối hiện tại đang ở trạng thái kích hoạt., the [System] shall CREATE patient treatment journal, ensuring that Hệ thống khởi tạo thành công một biểu mẫu nhật ký mới gắn liền với đợt điều trị hiện tại, thiết lập sẵn các trường thông tin cần theo dõi (như mức độ đau, độ sưng gối, các triệu chứng bất thường, trạng thái dùng thuốc) và sẵn sàng cho lượt nhập liệu đầu tiên.",Đạt Trần Tiến (Daves Tran)
Cập nhật diễn biến triệu chứng và tiến trình điều trị vào nhật ký,Mobile Web,ULTS-Cập nhật diễn biến triệu chứng và tiến trình điều trị vào nhật ký-FR-29,UPDATE patient treatment journal,,No,No,,tahuykl,UP8,System,Nhật ký chữa bệnh đã được khởi tạo thành công và đang trong thời gian theo dõi điều trị,"Hệ thống ghi nhận và lưu trữ dòng thời gian các dữ liệu mới do người dùng nhập (ví dụ: mức độ đau giảm từ 7 xuống 4, gối bớt sưng sau khi chườm đá, đã uống thuốc đúng giờ); đồng thời tự động cập nhật các số liệu này lên biểu đồ xu hướng tiến triển của khớp gối","ULTS-Cập nhật diễn biến triệu chứng và tiến trình điều trị vào nhật ký-FR-29: As an [MSK Patient & Family Caregiver], provide that Nhật ký chữa bệnh đã được khởi tạo thành công và đang trong thời gian theo dõi điều trị, the [System] shall UPDATE patient treatment journal, ensuring that Hệ thống ghi nhận và lưu trữ dòng thời gian các dữ liệu mới do người dùng nhập (ví dụ: mức độ đau giảm từ 7 xuống 4, gối bớt sưng sau khi chườm đá, đã uống thuốc đúng giờ); đồng thời tự động cập nhật các số liệu này lên biểu đồ xu hướng tiến triển của khớp gối",Đạt Trần Tiến (Daves Tran)
Gửi báo cáo nhật ký chữa bệnh khớp gối cho Bác sĩ Chẩn đoán Hình ảnh hoặc Bác sĩ Điều trị,Mobile Web,ULTS-Gửi báo cáo nhật ký chữa bệnh khớp gối cho Bác sĩ Chẩn đoán Hình ảnh hoặc Bác sĩ Điều trị-FR-30,SEND patient treatment journal toward Clinicians & PT,,No,No,Send Treatment Journal (https://app.notion.com/p/Send-Treatment-Journal-376f910aea75808492a9ff771d46d442?pvs=21),tahuykl,UP8,System,Nhật ký chữa bệnh đã có dữ liệu được cập nhật và hệ thống đã xác định được danh tính bác sĩ phụ trách ca bệnh của bệnh nhân,"Hệ thống đóng gói toàn bộ lịch sử dữ liệu nhật ký (dưới dạng biểu đồ và bảng tóm tắt triệu chứng), mã hóa bảo mật dữ liệu y tế và chuyển trực tiếp tới màn hình làm việc (Dashboard) của bác sĩ phụ trách, đồng thời phát thông báo xác nhận ""Gửi thành công"" cho bệnh nhân/người chăm sóc","ULTS-Gửi báo cáo nhật ký chữa bệnh khớp gối cho Bác sĩ Chẩn đoán Hình ảnh hoặc Bác sĩ Điều trị-FR-30: As an [MSK Patient & Family Caregiver], provide that Nhật ký chữa bệnh đã có dữ liệu được cập nhật và hệ thống đã xác định được danh tính bác sĩ phụ trách ca bệnh của bệnh nhân, the [System] shall SEND patient treatment journal toward Clinicians & PT, ensuring that Hệ thống đóng gói toàn bộ lịch sử dữ liệu nhật ký (dưới dạng biểu đồ và bảng tóm tắt triệu chứng), mã hóa bảo mật dữ liệu y tế và chuyển trực tiếp tới màn hình làm việc (Dashboard) của bác sĩ phụ trách, đồng thời phát thông báo xác nhận ""Gửi thành công"" cho bệnh nhân/người chăm sóc",Đạt Trần Tiến (Daves Tran)
Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện,Mobile Web,ULTS-Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện-FR-20,KẾT NỐI và GỬI Báo cáo Nhật Ký Bệnh Lý cho Bác sĩ Điều trị & Physiotherpist,-1,No,No,,,UP8,System,Bệnh nhân vừa hoàn thành bài tự kiểm tra mức độ viêm (REQ-PAT-03) và phát hiện có dấu hiệu bất thường (đau tăng lên).,"Hệ thống đóng gói lịch sử triệu chứng kèm biểu đồ xu hướng gần nhất, gửi an toàn qua kênh mã hóa tới bác sĩ quản lý ca bệnh để bác sĩ có thể chủ động hẹn lịch tái khám sớm.","ULTS-Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện-FR-20: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân vừa hoàn thành bài tự kiểm tra mức độ viêm (REQ-PAT-03) và phát hiện có dấu hiệu bất thường (đau tăng lên)., the [System] shall KẾT NỐI và GỬI Báo cáo Nhật Ký Bệnh Lý cho Bác sĩ Điều trị & Physiotherpist, ensuring that Hệ thống đóng gói lịch sử triệu chứng kèm biểu đồ xu hướng gần nhất, gửi an toàn qua kênh mã hóa tới bác sĩ quản lý ca bệnh để bác sĩ có thể chủ động hẹn lịch tái khám sớm.",tahuykl
Patient Education Module / 3D Visualization Engine,Mobile Web,ULTS-Patient Education Module / 3D Visualization Engine-FR-12,SYNCHRONIZE hardware-adaptive musculoskeletal models for visualizing MSK-condition after each visiting,-1,No,No,,,UP8,System,[The patient opens the 3D visualization view and the client-side feature detection script evaluates local GPU capabilities.],[Abstract 2D pathologies map to either a real-time WebGL 3D skeletal mesh (High-Spec) or a CPU-bound 36-frame 2D sprite-sheet turntable rendering at 10° increments (Low-Spec).],"ULTS-Patient Education Module / 3D Visualization Engine-FR-12: As an [MSK Patient & Family Caregiver], provide that [The patient opens the 3D visualization view and the client-side feature detection script evaluates local GPU capabilities.], the [System] shall SYNCHRONIZE hardware-adaptive musculoskeletal models for visualizing MSK-condition after each visiting, ensuring that [Abstract 2D pathologies map to either a real-time WebGL 3D skeletal mesh (High-Spec) or a CPU-bound 36-frame 2D sprite-sheet turntable rendering at 10° increments (Low-Spec).]",Đạt Trần Tiến (Daves Tran)
Patient Portal / Security Module,Mobile Web,ULTS-Patient Portal / Security Module-FR-13,ENCRYPT and deliver sanitized patient payloads,-1,No,No,,,UP8,System,"[The patient provides explicit, native opt-in consent and scans the unique 14-day tokenized QR code or deep link.]","[The locally AES-256 encrypted, sanitized, and flattened locomotive health summary loads into an adaptive dashboard in ≤ 2.0 seconds.]","ULTS-Patient Portal / Security Module-FR-13: As an [MSK Patient & Family Caregiver], provide that [The patient provides explicit, native opt-in consent and scans the unique 14-day tokenized QR code or deep link.], the [System] shall ENCRYPT and deliver sanitized patient payloads, ensuring that [The locally AES-256 encrypted, sanitized, and flattened locomotive health summary loads into an adaptive dashboard in ≤ 2.0 seconds.]",Đạt Trần Tiến (Daves Tran)
Patient Education Module / Personalized - Controlled Q&A,Mobile Web,ULTS-Patient Education Module / Personalized - Controlled Q&A-FR-31,INTERPRET diagnostic report profile from Clinic to Patient,,No,No,,,UP8,System,[Clinician has set the diagnostic report status to FINALIZED and a diagnosis code exists],"[A plain-language summary explaining the diagnosis (include terminology, why the patient should care and concern, the impact-to-patient analysis) is available on the patient's dashboard]","ULTS-Patient Education Module / Personalized - Controlled Q&A-FR-31: As an [MSK Patient & Family Caregiver], provide that [Clinician has set the diagnostic report status to FINALIZED and a diagnosis code exists], the [System] shall INTERPRET diagnostic report profile from Clinic to Patient, ensuring that [A plain-language summary explaining the diagnosis (include terminology, why the patient should care and concern, the impact-to-patient analysis) is available on the patient's dashboard]",Đạt Trần Tiến (Daves Tran)
Patient Education / Care Logic Module,Mobile Web,ULTS-Patient Education / Care Logic Module-FR-32,GUIDE lifestyle via personalized recovery tasks,,No,No,,,UP8,System,[Clinician has finalized the daily grade (0-3) in the medical record],"[The patient receives an updated, conversational, and actionable daily checklist]","ULTS-Patient Education / Care Logic Module-FR-32: As an [MSK Patient & Family Caregiver], provide that [Clinician has finalized the daily grade (0-3) in the medical record], the [System] shall GUIDE lifestyle via personalized recovery tasks, ensuring that [The patient receives an updated, conversational, and actionable daily checklist]",Đạt Trần Tiến (Daves Tran)
Patient Education Module / Personalized - Controlled Q&A,Mobile Web,ULTS-Patient Education Module / Personalized - Controlled Q&A-FR-33,TRIAGE patient-input queries against clinical status,,No,No,,,UP8,System,[Patient submits a health-related query via the Q&A interface while a clinical record exists],"[The query is tagged as Verified, Neutral, or Cautionary based on its relevance to the specific medical record]","ULTS-Patient Education Module / Personalized - Controlled Q&A-FR-33: As an [MSK Patient & Family Caregiver], provide that [Patient submits a health-related query via the Q&A interface while a clinical record exists], the [System] shall TRIAGE patient-input queries against clinical status, ensuring that [The query is tagged as Verified, Neutral, or Cautionary based on its relevance to the specific medical record]",Đạt Trần Tiến (Daves Tran)
Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading),Mobile Web,ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)-FR-25,CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối,,Yes,No,"Load Patient Scan Session (https://app.notion.com/p/Load-Patient-Scan-Session-376f910aea75807586e9e64a7883c7b6?pvs=21), Review Suggested Synovitis Grade (0-3) (https://app.notion.com/p/Review-Suggested-Synovitis-Grade-0-3-378f910aea75802492c7d60b707b988e?pvs=21), Finalize & Sign Electronic Record (https://app.notion.com/p/Finalize-Sign-Electronic-Record-378f910aea758088b010f6f1c52c006d?pvs=21), Generate GradCAM & CoT Explanation Panel (https://app.notion.com/p/Generate-GradCAM-CoT-Explanation-Panel-378f910aea7580cdb530f06312577e6f?pvs=21), Log High-Trust Concur Block (https://app.notion.com/p/Log-High-Trust-Concur-Block-378f910aea7580baa4aace53fe624e23?pvs=21), Trigger Conversational Circuit Breaker (https://app.notion.com/p/Trigger-Conversational-Circuit-Breaker-378f910aea7580b2949be22396e2e159?pvs=21), Facilitate Socratic Reasoning Dialogue (https://app.notion.com/p/Facilitate-Socratic-Reasoning-Dialogue-378f910aea7580ee9d93d1988a1e5146?pvs=21), Monitor Context Drift via BERT Sub-Layer (https://app.notion.com/p/Monitor-Context-Drift-via-BERT-Sub-Layer-378f910aea7580c5b69bcad54c8fe21c?pvs=21), Arbitrate Evidence via RAG-Referee (https://app.notion.com/p/Arbitrate-Evidence-via-RAG-Referee-378f910aea75805b83dadeb609585473?pvs=21), Expose Pixel-Level Activation Logic (https://app.notion.com/p/Expose-Pixel-Level-Activation-Logic-378f910aea7580a49250ee97e865637c?pvs=21), Isolate Visual Noise/Artifacts (https://app.notion.com/p/Isolate-Visual-Noise-Artifacts-378f910aea7580898125d5a2d073c9db?pvs=21), Commit Validated Ground-Truth Record (https://app.notion.com/p/Commit-Validated-Ground-Truth-Record-378f910aea7580f6853bc7427402864f?pvs=21), Activate Clinical Investigation Mode (https://app.notion.com/p/Activate-Clinical-Investigation-Mode-378f910aea758059ab78df2595b9f5f6?pvs=21), Execute Structured Morphology Annotation (https://app.notion.com/p/Execute-Structured-Morphology-Annotation-378f910aea758013b687d8272c7be796?pvs=21), Serialize Session to Telemetry Queue (https://app.notion.com/p/Serialize-Session-to-Telemetry-Queue-378f910aea75808dbeeddaaa8ae1580f?pvs=21)",Đạt Trần Tiến (Daves Tran),UP5,System,Hệ thống đã ghi nhận độ dày màng hoạt dịch (REQ-RAD-02) và kết quả quét Doppler dòng máu (Hypervascularity),"Hệ thống đưa ra gợi ý chẩn đoán mức độ viêm theo thang chuẩn y khoa (ví dụ: Không viêm, Viêm nhẹ - Độ 1, Viêm vừa - Độ 2, Viêm nặng - Độ 3) để bác sĩ xác nhận hoặc điều chỉnh","ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)-FR-25: As an [Diagnostic Radiologist], provide that Hệ thống đã ghi nhận độ dày màng hoạt dịch (REQ-RAD-02) và kết quả quét Doppler dòng máu (Hypervascularity), the [System] should CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối, ensuring that Hệ thống đưa ra gợi ý chẩn đoán mức độ viêm theo thang chuẩn y khoa (ví dụ: Không viêm, Viêm nhẹ - Độ 1, Viêm vừa - Độ 2, Viêm nặng - Độ 3) để bác sĩ xác nhận hoặc điều chỉnh",tahuykl
1 ComponentName Device ReqID ReqName Priority IsOptional Drop LinkUseCases EngineerDesignUC UserProfileCode Sys/Act PreCondition PostCondition VerboseDescription Engineer
2 Progress Tracking Module Mobile Web ULTS-Progress Tracking Module-FR-7 RECORD Asynchronous PT Progress Metrics No No UP6 System [The physical therapist taps the screen workspace layer within the distinct Kinetic Tracking Channel.] [Localized metrics including Range of Motion, 1-10 pain indices, and tissue behavior are serialized and pushed to the physician's tracking panel without mutating the primary medical file.] ULTS-Progress Tracking Module-FR-7: As an [Physical Therapist], provide that [The physical therapist taps the screen workspace layer within the distinct Kinetic Tracking Channel.], the [System] shall RECORD Asynchronous PT Progress Metrics, ensuring that [Localized metrics including Range of Motion, 1-10 pain indices, and tissue behavior are serialized and pushed to the physician's tracking panel without mutating the primary medical file.] Đạt Trần Tiến (Daves Tran)
3 Patient Education Module Mobile Web ULTS-Patient Education Module-FR-8 DEMONSTRATE joint mechanics dynamically during physical therapy section -1 No No UP6 System [The physical therapist moves the HTML Range-of-Motion slider within the Patient Demonstration Mode split layout.] [A cached array of 2D illustrations seamlessly cycles using 0% GPU power to visually indicate joint flexion, extension, and soft-tissue impingement.] ULTS-Patient Education Module-FR-8: As an [Physical Therapist], provide that [The physical therapist moves the HTML Range-of-Motion slider within the Patient Demonstration Mode split layout.], the [System] shall DEMONSTRATE joint mechanics dynamically during physical therapy section, ensuring that [A cached array of 2D illustrations seamlessly cycles using 0% GPU power to visually indicate joint flexion, extension, and soft-tissue impingement.] Đạt Trần Tiến (Daves Tran)
4 Patient Education / Care Logic Module Mobile Web ULTS-Patient Education / Care Logic Module-FR-19 NHẮC NHỞ việc bệnh nhân tuân thủ Đơn thuốc và lịch Điều trị No No tahuykl UP8 System Bác sĩ đã kê đơn thuốc (REQ-RAD-05) và phác đồ điều trị được đồng bộ sang tài khoản của bệnh nhân. Ứng dụng tự động phát thông báo nhắc nhở giờ uống thuốc, giờ tập vật lý trị liệu cho Bệnh nhân và Người chăm sóc, đồng thời cho phép tích chọn "Đã uống" để lưu lại lịch sử tuân thủ điều trị. ULTS-Patient Education / Care Logic Module-FR-19: As an [MSK Patient & Family Caregiver], provide that Bác sĩ đã kê đơn thuốc (REQ-RAD-05) và phác đồ điều trị được đồng bộ sang tài khoản của bệnh nhân., the [System] shall NHẮC NHỞ việc bệnh nhân tuân thủ Đơn thuốc và lịch Điều trị, ensuring that Ứng dụng tự động phát thông báo nhắc nhở giờ uống thuốc, giờ tập vật lý trị liệu cho Bệnh nhân và Người chăm sóc, đồng thời cho phép tích chọn "Đã uống" để lưu lại lịch sử tuân thủ điều trị. tahuykl
5 Xem và tải về lịch sử các lần siêu âm và khám khớp gối Mobile Web ULTS-Xem và tải về lịch sử các lần siêu âm và khám khớp gối-FR-16 TRA CỨU lịch sử khám bệnh và Siêu âm Toàn diện No No tahuykl UP8 System Bệnh nhân hoặc Người chăm sóc đăng nhập thành công vào hệ thống bằng tài khoản định danh hợp lệ. Hệ thống hiển thị danh sách toàn bộ các mốc thời gian đã khám, cho phép người dùng bấm vào từng ngày để xem lại ảnh siêu âm, đơn thuốc, và các chỉ số đo đạc cũ. ULTS-Xem và tải về lịch sử các lần siêu âm và khám khớp gối-FR-16: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân hoặc Người chăm sóc đăng nhập thành công vào hệ thống bằng tài khoản định danh hợp lệ., the [System] shall TRA CỨU lịch sử khám bệnh và Siêu âm Toàn diện, ensuring that Hệ thống hiển thị danh sách toàn bộ các mốc thời gian đã khám, cho phép người dùng bấm vào từng ngày để xem lại ảnh siêu âm, đơn thuốc, và các chỉ số đo đạc cũ. tahuykl
6 Tạo mới nhật ký chữa bệnh khớp gối cho bệnh nhân Mobile Web ULTS-Tạo mới nhật ký chữa bệnh khớp gối cho bệnh nhân-FR-28 CREATE patient treatment journal No No tahuykl UP8 System Bệnh nhân hoặc Người chăm sóc đã đăng nhập thành công vào tài khoản hệ thống (ứng dụng di động hoặc cổng thông tin bệnh nhân) và hồ sơ bệnh án siêu âm khớp gối hiện tại đang ở trạng thái kích hoạt. Hệ thống khởi tạo thành công một biểu mẫu nhật ký mới gắn liền với đợt điều trị hiện tại, thiết lập sẵn các trường thông tin cần theo dõi (như mức độ đau, độ sưng gối, các triệu chứng bất thường, trạng thái dùng thuốc) và sẵn sàng cho lượt nhập liệu đầu tiên. ULTS-Tạo mới nhật ký chữa bệnh khớp gối cho bệnh nhân-FR-28: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân hoặc Người chăm sóc đã đăng nhập thành công vào tài khoản hệ thống (ứng dụng di động hoặc cổng thông tin bệnh nhân) và hồ sơ bệnh án siêu âm khớp gối hiện tại đang ở trạng thái kích hoạt., the [System] shall CREATE patient treatment journal, ensuring that Hệ thống khởi tạo thành công một biểu mẫu nhật ký mới gắn liền với đợt điều trị hiện tại, thiết lập sẵn các trường thông tin cần theo dõi (như mức độ đau, độ sưng gối, các triệu chứng bất thường, trạng thái dùng thuốc) và sẵn sàng cho lượt nhập liệu đầu tiên. Đạt Trần Tiến (Daves Tran)
7 Cập nhật diễn biến triệu chứng và tiến trình điều trị vào nhật ký Mobile Web ULTS-Cập nhật diễn biến triệu chứng và tiến trình điều trị vào nhật ký-FR-29 UPDATE patient treatment journal No No tahuykl UP8 System Nhật ký chữa bệnh đã được khởi tạo thành công và đang trong thời gian theo dõi điều trị Hệ thống ghi nhận và lưu trữ dòng thời gian các dữ liệu mới do người dùng nhập (ví dụ: mức độ đau giảm từ 7 xuống 4, gối bớt sưng sau khi chườm đá, đã uống thuốc đúng giờ); đồng thời tự động cập nhật các số liệu này lên biểu đồ xu hướng tiến triển của khớp gối ULTS-Cập nhật diễn biến triệu chứng và tiến trình điều trị vào nhật ký-FR-29: As an [MSK Patient & Family Caregiver], provide that Nhật ký chữa bệnh đã được khởi tạo thành công và đang trong thời gian theo dõi điều trị, the [System] shall UPDATE patient treatment journal, ensuring that Hệ thống ghi nhận và lưu trữ dòng thời gian các dữ liệu mới do người dùng nhập (ví dụ: mức độ đau giảm từ 7 xuống 4, gối bớt sưng sau khi chườm đá, đã uống thuốc đúng giờ); đồng thời tự động cập nhật các số liệu này lên biểu đồ xu hướng tiến triển của khớp gối Đạt Trần Tiến (Daves Tran)
8 Gửi báo cáo nhật ký chữa bệnh khớp gối cho Bác sĩ Chẩn đoán Hình ảnh hoặc Bác sĩ Điều trị Mobile Web ULTS-Gửi báo cáo nhật ký chữa bệnh khớp gối cho Bác sĩ Chẩn đoán Hình ảnh hoặc Bác sĩ Điều trị-FR-30 SEND patient treatment journal toward Clinicians & PT No No Send Treatment Journal (https://app.notion.com/p/Send-Treatment-Journal-376f910aea75808492a9ff771d46d442?pvs=21) tahuykl UP8 System Nhật ký chữa bệnh đã có dữ liệu được cập nhật và hệ thống đã xác định được danh tính bác sĩ phụ trách ca bệnh của bệnh nhân Hệ thống đóng gói toàn bộ lịch sử dữ liệu nhật ký (dưới dạng biểu đồ và bảng tóm tắt triệu chứng), mã hóa bảo mật dữ liệu y tế và chuyển trực tiếp tới màn hình làm việc (Dashboard) của bác sĩ phụ trách, đồng thời phát thông báo xác nhận "Gửi thành công" cho bệnh nhân/người chăm sóc ULTS-Gửi báo cáo nhật ký chữa bệnh khớp gối cho Bác sĩ Chẩn đoán Hình ảnh hoặc Bác sĩ Điều trị-FR-30: As an [MSK Patient & Family Caregiver], provide that Nhật ký chữa bệnh đã có dữ liệu được cập nhật và hệ thống đã xác định được danh tính bác sĩ phụ trách ca bệnh của bệnh nhân, the [System] shall SEND patient treatment journal toward Clinicians & PT, ensuring that Hệ thống đóng gói toàn bộ lịch sử dữ liệu nhật ký (dưới dạng biểu đồ và bảng tóm tắt triệu chứng), mã hóa bảo mật dữ liệu y tế và chuyển trực tiếp tới màn hình làm việc (Dashboard) của bác sĩ phụ trách, đồng thời phát thông báo xác nhận "Gửi thành công" cho bệnh nhân/người chăm sóc Đạt Trần Tiến (Daves Tran)
9 Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện Mobile Web ULTS-Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện-FR-20 KẾT NỐI và GỬI Báo cáo Nhật Ký Bệnh Lý cho Bác sĩ Điều trị & Physiotherpist -1 No No UP8 System Bệnh nhân vừa hoàn thành bài tự kiểm tra mức độ viêm (REQ-PAT-03) và phát hiện có dấu hiệu bất thường (đau tăng lên). Hệ thống đóng gói lịch sử triệu chứng kèm biểu đồ xu hướng gần nhất, gửi an toàn qua kênh mã hóa tới bác sĩ quản lý ca bệnh để bác sĩ có thể chủ động hẹn lịch tái khám sớm. ULTS-Gửi dữ liệu tự kiểm tra mức độ viêm tại nhà về hệ thống của bệnh viện-FR-20: As an [MSK Patient & Family Caregiver], provide that Bệnh nhân vừa hoàn thành bài tự kiểm tra mức độ viêm (REQ-PAT-03) và phát hiện có dấu hiệu bất thường (đau tăng lên)., the [System] shall KẾT NỐI và GỬI Báo cáo Nhật Ký Bệnh Lý cho Bác sĩ Điều trị & Physiotherpist, ensuring that Hệ thống đóng gói lịch sử triệu chứng kèm biểu đồ xu hướng gần nhất, gửi an toàn qua kênh mã hóa tới bác sĩ quản lý ca bệnh để bác sĩ có thể chủ động hẹn lịch tái khám sớm. tahuykl
10 Patient Education Module / 3D Visualization Engine Mobile Web ULTS-Patient Education Module / 3D Visualization Engine-FR-12 SYNCHRONIZE hardware-adaptive musculoskeletal models for visualizing MSK-condition after each visiting -1 No No UP8 System [The patient opens the 3D visualization view and the client-side feature detection script evaluates local GPU capabilities.] [Abstract 2D pathologies map to either a real-time WebGL 3D skeletal mesh (High-Spec) or a CPU-bound 36-frame 2D sprite-sheet turntable rendering at 10° increments (Low-Spec).] ULTS-Patient Education Module / 3D Visualization Engine-FR-12: As an [MSK Patient & Family Caregiver], provide that [The patient opens the 3D visualization view and the client-side feature detection script evaluates local GPU capabilities.], the [System] shall SYNCHRONIZE hardware-adaptive musculoskeletal models for visualizing MSK-condition after each visiting, ensuring that [Abstract 2D pathologies map to either a real-time WebGL 3D skeletal mesh (High-Spec) or a CPU-bound 36-frame 2D sprite-sheet turntable rendering at 10° increments (Low-Spec).] Đạt Trần Tiến (Daves Tran)
11 Patient Portal / Security Module Mobile Web ULTS-Patient Portal / Security Module-FR-13 ENCRYPT and deliver sanitized patient payloads -1 No No UP8 System [The patient provides explicit, native opt-in consent and scans the unique 14-day tokenized QR code or deep link.] [The locally AES-256 encrypted, sanitized, and flattened locomotive health summary loads into an adaptive dashboard in ≤ 2.0 seconds.] ULTS-Patient Portal / Security Module-FR-13: As an [MSK Patient & Family Caregiver], provide that [The patient provides explicit, native opt-in consent and scans the unique 14-day tokenized QR code or deep link.], the [System] shall ENCRYPT and deliver sanitized patient payloads, ensuring that [The locally AES-256 encrypted, sanitized, and flattened locomotive health summary loads into an adaptive dashboard in ≤ 2.0 seconds.] Đạt Trần Tiến (Daves Tran)
12 Patient Education Module / Personalized - Controlled Q&A Mobile Web ULTS-Patient Education Module / Personalized - Controlled Q&A-FR-31 INTERPRET diagnostic report profile from Clinic to Patient No No UP8 System [Clinician has set the diagnostic report status to FINALIZED and a diagnosis code exists] [A plain-language summary explaining the diagnosis (include terminology, why the patient should care and concern, the impact-to-patient analysis) is available on the patient's dashboard] ULTS-Patient Education Module / Personalized - Controlled Q&A-FR-31: As an [MSK Patient & Family Caregiver], provide that [Clinician has set the diagnostic report status to FINALIZED and a diagnosis code exists], the [System] shall INTERPRET diagnostic report profile from Clinic to Patient, ensuring that [A plain-language summary explaining the diagnosis (include terminology, why the patient should care and concern, the impact-to-patient analysis) is available on the patient's dashboard] Đạt Trần Tiến (Daves Tran)
13 Patient Education / Care Logic Module Mobile Web ULTS-Patient Education / Care Logic Module-FR-32 GUIDE lifestyle via personalized recovery tasks No No UP8 System [Clinician has finalized the daily grade (0-3) in the medical record] [The patient receives an updated, conversational, and actionable daily checklist] ULTS-Patient Education / Care Logic Module-FR-32: As an [MSK Patient & Family Caregiver], provide that [Clinician has finalized the daily grade (0-3) in the medical record], the [System] shall GUIDE lifestyle via personalized recovery tasks, ensuring that [The patient receives an updated, conversational, and actionable daily checklist] Đạt Trần Tiến (Daves Tran)
14 Patient Education Module / Personalized - Controlled Q&A Mobile Web ULTS-Patient Education Module / Personalized - Controlled Q&A-FR-33 TRIAGE patient-input queries against clinical status No No UP8 System [Patient submits a health-related query via the Q&A interface while a clinical record exists] [The query is tagged as Verified, Neutral, or Cautionary based on its relevance to the specific medical record] ULTS-Patient Education Module / Personalized - Controlled Q&A-FR-33: As an [MSK Patient & Family Caregiver], provide that [Patient submits a health-related query via the Q&A interface while a clinical record exists], the [System] shall TRIAGE patient-input queries against clinical status, ensuring that [The query is tagged as Verified, Neutral, or Cautionary based on its relevance to the specific medical record] Đạt Trần Tiến (Daves Tran)
15 Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading) Mobile Web ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)-FR-25 CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối Yes No Load Patient Scan Session (https://app.notion.com/p/Load-Patient-Scan-Session-376f910aea75807586e9e64a7883c7b6?pvs=21), Review Suggested Synovitis Grade (0-3) (https://app.notion.com/p/Review-Suggested-Synovitis-Grade-0-3-378f910aea75802492c7d60b707b988e?pvs=21), Finalize & Sign Electronic Record (https://app.notion.com/p/Finalize-Sign-Electronic-Record-378f910aea758088b010f6f1c52c006d?pvs=21), Generate GradCAM & CoT Explanation Panel (https://app.notion.com/p/Generate-GradCAM-CoT-Explanation-Panel-378f910aea7580cdb530f06312577e6f?pvs=21), Log High-Trust Concur Block (https://app.notion.com/p/Log-High-Trust-Concur-Block-378f910aea7580baa4aace53fe624e23?pvs=21), Trigger Conversational Circuit Breaker (https://app.notion.com/p/Trigger-Conversational-Circuit-Breaker-378f910aea7580b2949be22396e2e159?pvs=21), Facilitate Socratic Reasoning Dialogue (https://app.notion.com/p/Facilitate-Socratic-Reasoning-Dialogue-378f910aea7580ee9d93d1988a1e5146?pvs=21), Monitor Context Drift via BERT Sub-Layer (https://app.notion.com/p/Monitor-Context-Drift-via-BERT-Sub-Layer-378f910aea7580c5b69bcad54c8fe21c?pvs=21), Arbitrate Evidence via RAG-Referee (https://app.notion.com/p/Arbitrate-Evidence-via-RAG-Referee-378f910aea75805b83dadeb609585473?pvs=21), Expose Pixel-Level Activation Logic (https://app.notion.com/p/Expose-Pixel-Level-Activation-Logic-378f910aea7580a49250ee97e865637c?pvs=21), Isolate Visual Noise/Artifacts (https://app.notion.com/p/Isolate-Visual-Noise-Artifacts-378f910aea7580898125d5a2d073c9db?pvs=21), Commit Validated Ground-Truth Record (https://app.notion.com/p/Commit-Validated-Ground-Truth-Record-378f910aea7580f6853bc7427402864f?pvs=21), Activate Clinical Investigation Mode (https://app.notion.com/p/Activate-Clinical-Investigation-Mode-378f910aea758059ab78df2595b9f5f6?pvs=21), Execute Structured Morphology Annotation (https://app.notion.com/p/Execute-Structured-Morphology-Annotation-378f910aea758013b687d8272c7be796?pvs=21), Serialize Session to Telemetry Queue (https://app.notion.com/p/Serialize-Session-to-Telemetry-Queue-378f910aea75808dbeeddaaa8ae1580f?pvs=21) Đạt Trần Tiến (Daves Tran) UP5 System Hệ thống đã ghi nhận độ dày màng hoạt dịch (REQ-RAD-02) và kết quả quét Doppler dòng máu (Hypervascularity) Hệ thống đưa ra gợi ý chẩn đoán mức độ viêm theo thang chuẩn y khoa (ví dụ: Không viêm, Viêm nhẹ - Độ 1, Viêm vừa - Độ 2, Viêm nặng - Độ 3) để bác sĩ xác nhận hoặc điều chỉnh ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)-FR-25: As an [Diagnostic Radiologist], provide that Hệ thống đã ghi nhận độ dày màng hoạt dịch (REQ-RAD-02) và kết quả quét Doppler dòng máu (Hypervascularity), the [System] should CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối, ensuring that Hệ thống đưa ra gợi ý chẩn đoán mức độ viêm theo thang chuẩn y khoa (ví dụ: Không viêm, Viêm nhẹ - Độ 1, Viêm vừa - Độ 2, Viêm nặng - Độ 3) để bác sĩ xác nhận hoặc điều chỉnh tahuykl

184
proj_level_reading/Requirement_Analysis/Non-FRS-DB/Non-Functional (NFR) List Result/Non-FR Engineering Result 376f910aea7580c3ae9afed6937701fd_all.csv Normal file
View File

@@ -0,0 +1,184 @@
ReqName,ComponentName,Created time,Engineer,ID,NotViloate,Project Prefix,Rationale,ReqCategory,ReqID,TargetSpec,UserProfileCode,Validation,VerboseDescription
DICOM Collaborative Rendering Speed,PR,"June 5, 2026 10:41 AM",Đạt Trần Tiến (Daves Tran),NFR-1,The user/event response time for transforming a standard DICOM X-ray into a shared collaborative canvas with ML diagnostic overlays SHALL NOT exceed 3.0 seconds.,ULTS,prevention losing the trust and adoption of fast-paced Professional Clinicians (UP2) operating under intense multitasking and heavy ward volumes.,Efficiency (Speed & Space),ULTS-PR-NFR-1,"Optimize the interactive workspace canvas performance during the ingestion and
rendering of medical image assets.",UP2,"Deploy network throttling profiles (clamped at exactly 10 Mbps) on a test client terminal. Trigger 100 consecutive DICOM collaborative canvas initializations.
Measure end-to-end latency via automated browser performance scripts.
SUCCESS CRITERIA: 100% of test runs must clock an event duration ≤ 3000ms.","📌 As a result of prevention losing the trust and adoption of fast-paced Professional Clinicians (UP2) operating under intense multitasking and heavy ward volumes.,
⚙️ The system must satisfy: Optimize the interactive workspace canvas performance during the ingestion and
rendering of medical image assets.,
🛑 And it shall not violate: The user/event response time for transforming a standard DICOM X-ray into a shared collaborative canvas with ML diagnostic overlays SHALL NOT exceed 3.0 seconds.."
Client Memory Footprint & Constraints,PR,"June 5, 2026 11:13 AM",Đạt Trần Tiến (Daves Tran),NFR-4,The active client application memory allocation SHALL NOT exceed 150 Mbytes of RAM during an ongoing multi-user collaborative review session. Additionally the program have to run on client hardware devices with baseline configurations down to 3GB total RAM.,ULTS,"Practitioners (UP3) operate in resource-constrained provincial and commune
clinics using legacy mobile and tablet form-factors with limited system memory.",Efficiency (Speed & Space),ULTS-PR-NFR-4,Constrain the runtime store occupancy of the active browser application workspace.,UP3,"Connect a low-end test tablet to Chrome DevTools Memory Profiler. Initialize a 4-user
shared collaborative workshop session. Simulate continuous annotation changes for
30 minutes.
SUCCESS CRITERIA: Peak heap memory allocation logged in heap snapshots must stay strictly below 150MB, with 0 instances of OS-level browser crashes.","📌 As a result of Practitioners (UP3) operate in resource-constrained provincial and commune
clinics using legacy mobile and tablet form-factors with limited system memory.,
⚙️ The system must satisfy: Constrain the runtime store occupancy of the active browser application workspace.,
🛑 And it shall not violate: The active client application memory allocation SHALL NOT exceed 150 Mbytes of RAM during an ongoing multi-user collaborative review session. Additionally the program have to run on client hardware devices with baseline configurations down to 3GB total RAM.."
Core Vision Inference Latency Limit,PR,"June 5, 2026 11:16 AM",Đạt Trần Tiến (Daves Tran),NFR-5,The processing time for raw DICOM matrix parsing and diagnostic bounding-box generation SHALL NOT exceed 1.5 seconds. Additionally the computation must be calculated locally on the designated on-premise local server configuration node.,ULTS,"prevention local compute bottlenecks from pushing the overall collaborative
workspace sync execution beyond the critical user threshold.",Efficiency (Speed & Space),ULTS-PR-NFR-5,The local computer vision model must complete image processing rapidly on the edge tier.,UP2,"Inject a test batch of 500 un-analyzed musculoskeletal DICOM files into the
local image processing queue. Read backend server performance tracing timestamps.
SUCCESS CRITERIA: Arithmetic mean of inference execution time must be ≤ 1500ms,
with a maximum upper bound outlier limit of 1800ms.","📌 As a result of prevention local compute bottlenecks from pushing the overall collaborative
workspace sync execution beyond the critical user threshold.,
⚙️ The system must satisfy: The local computer vision model must complete image processing rapidly on the edge tier.,
🛑 And it shall not violate: The processing time for raw DICOM matrix parsing and diagnostic bounding-box generation SHALL NOT exceed 1.5 seconds. Additionally the computation must be calculated locally on the designated on-premise local server configuration node.."
Server-Side Edge Model Quantization,PR,"June 5, 2026 11:20 AM",Đạt Trần Tiến (Daves Tran),NFR-6,"The active memory allocation of the deployed models SHALL NOT require more than
2 GB of VRAM on the target server nodes, and the system shall have to execute on local server nodes or specialized on-premise clinical workstations.",ULTS,"prevention hardware resource exhaustion on local public hospital servers and keep
deployment costs sustainable for district clinics.",Efficiency (Speed & Space),ULTS-PR-NFR-6,Apply optimization protocols to the deployed musculoskeletal computer vision models.,UP2,"Boot up the localized AI model server container cluster. Query GPU hardware parameters via
system telemetry CLI commands (e.g., nvidia-smi) during peak load tasks.
SUCCESS CRITERIA: System-reported dedicated VRAM consumption per inference runner
must remain under 2.0 GB.","📌 As a result of prevention hardware resource exhaustion on local public hospital servers and keep
deployment costs sustainable for district clinics.,
⚙️ The system must satisfy: Apply optimization protocols to the deployed musculoskeletal computer vision models.,
🛑 And it shall not violate: The active memory allocation of the deployed models SHALL NOT require more than
2 GB of VRAM on the target server nodes, and the system shall have to execute on local server nodes or specialized on-premise clinical workstations.."
Real-Time UI Screen Refresh (Token Streaming),PR,"June 5, 2026 11:24 AM",Đạt Trần Tiến (Daves Tran),NFR-7,The initial UI screen refresh response time for text generation SHALL NOT be greater than 200 milliseconds from the moment inference begins. Also the system SHALL be able to rendered within standard browsers on legacy field-deployed budget tablets.,ULTS,"the acomodation of low-performance client screens and prevent UI freezing while
Practitioners (UP3) manage heavy, fast-moving clinical queues.",Efficiency (Speed & Space),ULTS-PR-NFR-7,Utilize a server-side processing architecture that pushes model text outputs as an asynchronous data stream.,UP3,"Trigger 50 distinct patient summary generation prompts on a legacy tablet.
Capture screen-to-render timelines using programmatic UI tracing (Time to First Token).
SUCCESS CRITERIA: The duration between user request submit and the rendering of
the first character on-screen must be ≤ 200ms in 100% of test cycles.","📌 As a result of the acomodation of low-performance client screens and prevent UI freezing while
Practitioners (UP3) manage heavy, fast-moving clinical queues.,
⚙️ The system must satisfy: Utilize a server-side processing architecture that pushes model text outputs as an asynchronous data stream.,
🛑 And it shall not violate: The initial UI screen refresh response time for text generation SHALL NOT be greater than 200 milliseconds from the moment inference begins. Also the system SHALL be able to rendered within standard browsers on legacy field-deployed budget tablets.."
Local Network Fault Tolerance (Robustness),PR,"June 5, 2026 11:27 AM",Đạt Trần Tiến (Daves Tran),NFR-8,"The objective probability of data corruption upon unexpected local connection failure
SHALL BE EXACTLY 0%, additional the system shall be able to Active / Remember the user-request during unexpected mid-session Wi-Fi disconnections or data link failures.",ULTS,"Rural district and commune-level healthcare nodes suffer from highly unstable
local network connectivity and frequent local Wi-Fi dropouts.",Dependability & Robustness,ULTS-PR-NFR-8,Integrate automated client-side data caching layers and silent background sync pipelines.,UNK,"Open an active collaborative review session on a client device. While drawing
canvas annotations, disconnect the clinic's local network router. Continue drawing 5 additions.
Restore router power after 60 seconds. Inspect the central database state.
SUCCESS CRITERIA: 0% data structural loss or canvas layer corruption. All offline edits
must synchronize seamlessly to the local server within 2.0 seconds of reconnection.","📌 As a result of Rural district and commune-level healthcare nodes suffer from highly unstable
local network connectivity and frequent local Wi-Fi dropouts.,
⚙️ The system must satisfy: Integrate automated client-side data caching layers and silent background sync pipelines.,
🛑 And it shall not violate: The objective probability of data corruption upon unexpected local connection failure
SHALL BE EXACTLY 0%, additional the system shall be able to Active / Remember the user-request during unexpected mid-session Wi-Fi disconnections or data link failures.."
Localized System Availability Matrix,PR,"June 5, 2026 11:30 AM",Đạt Trần Tiến (Daves Tran),NFR-9,"Local system availability SHALL NOT fall below a rate of 99.9% during official public
sector operating windows. Unexpected system downtime SHALL NOT exceed 45 seconds in any single day. Given the context that Mon–Fri, 07:00–16:30 (including lunch service from 11:30–13:30); selected evening windows
(17:00–20:00); continuous 24/7 coverage for emergency room department instances.",ULTS,"the condition that system must remain constantly online during standard and extended operating blocks
to prevent administrative blockages in crowded public patient queues.",Dependability & Robustness,ULTS-PR-NFR-9,"Ensure reliable, continuous local cluster operations without service interruptions.",UNK,"Review availability tracking logs generated by automated site reliability tools
(e.g., Prometheus/Grafana) continuously across a 30-day monitoring trial.
SUCCESS CRITERIA: Uptime logs must confirm ≤ 99.9% availability across all
designated operational shift blocks, with no un-escalated crashes exceeding 45 seconds.","📌 As a result of the condition that system must remain constantly online during standard and extended operating blocks
to prevent administrative blockages in crowded public patient queues.,
⚙️ The system must satisfy: Ensure reliable, continuous local cluster operations without service interruptions.,
🛑 And it shall not violate: Local system availability SHALL NOT fall below a rate of 99.9% during official public
sector operating windows. Unexpected system downtime SHALL NOT exceed 45 seconds in any single day. Given the context that Mon–Fri, 07:00–16:30 (including lunch service from 11:30–13:30); selected evening windows
(17:00–20:00); continuous 24/7 coverage for emergency room department instances.."
Automated Generative Safety Guardrails,PR,"June 5, 2026 11:33 AM",Đạt Trần Tiến (Daves Tran),NFR-10,"Less than 90% verification processing is prohibited (on these metric: Faithfulness / Groundedness Score, Policy Compliance Rate, Jailbreak/Toxicity Detection Rate, and Latency & Token Usage) ; 100% of LLM-generated patient text
explanations SHALL pass verification before rendering on the client interface.",ULTS,"the constrain that system have to safely insulate Support Staff & Patients (UP4) from unverified text outputs,
translation errors, or inappropriate medical claims.",Dependability & Robustness,ULTS-PR-NFR-10,"Intercept raw model generation streams with an automated verification layer
(e.g., NVIDIA NeMo Guardrails or Llama Guard). This constrain have to apply to all outward-facing user communications and text interfaces. ",UP4,"Inject a test suite containing 200 adversarial prompts designed to trigger unsafe medical
claims or guideline deviations. Analyze the resulting UI delivery logs.
SUCCESS CRITERIA: The system must successfully catch, block, or rewrite 100% of the
violating outputs, displaying a safe fallback notification instead.","📌 As a result of the constrain that system have to safely insulate Support Staff & Patients (UP4) from unverified text outputs,
translation errors, or inappropriate medical claims.,
⚙️ The system must satisfy: Intercept raw model generation streams with an automated verification layer
(e.g., NVIDIA NeMo Guardrails or Llama Guard). This constrain have to apply to all outward-facing user communications and text interfaces. ,
🛑 And it shall not violate: Less than 90% verification processing is prohibited (on these metric: Faithfulness / Groundedness Score, Policy Compliance Rate, Jailbreak/Toxicity Detection Rate, and Latency & Token Usage) ; 100% of LLM-generated patient text
explanations SHALL pass verification before rendering on the client interface.."
Frontline Usability & Training Curve,PR,"June 5, 2026 11:42 AM",Đạt Trần Tiến (Daves Tran),NFR-11,"The required onboarding training window to achieve independent user proficiency SHALL NOT
exceed 45 minutes. The subsequent average error rate SHALL NOT exceed 1 configuration slip per week.",ULTS,"Frontline Practitioners and Support Staff, and Patient exhibit low digital confidence and face severe
daily time constraints, making them resistant to tools that require complex setups.",Usability (Ease of Use),ULTS-PR-NFR-11,"Simplify user interaction flows for core workflows (patient registration, queue routing,
and media casting).","UP2, UP3, UP4","Run a validation test with 30 target users (Profiles 3 & 4). Provide a standard 45-minute
instructional session. Task users with processing a mock 10-patient throughput queue. Log
operational missteps over their first week of live work. Also ones have to run the evaluation on frontline staff with typical vocational/basic/ entry-level healthcare backgrounds.
SUCCESS CRITERIA: 90% or more of participants must pass the initial throughput test
independently, with a tracked post-onboarding error rate ≤ 1 configuration slip per week. - ","📌 As a result of Frontline Practitioners and Support Staff, and Patient exhibit low digital confidence and face severe
daily time constraints, making them resistant to tools that require complex setups.,
⚙️ The system must satisfy: Simplify user interaction flows for core workflows (patient registration, queue routing,
and media casting).,
🛑 And it shall not violate: The required onboarding training window to achieve independent user proficiency SHALL NOT
exceed 45 minutes. The subsequent average error rate SHALL NOT exceed 1 configuration slip per week.."
Zero-Friction Explainability Integration,ORG,"June 5, 2026 11:58 AM",Đạt Trần Tiến (Daves Tran),NFR-12,"Accessing baseline model confidence intervals or guideline justifications SHALL require
EXACTLY 0 extra user clicks or separate modal pop-up windows. - and the model’s result have to displayed inside the primary medical viewport layout used during image interpretation.",ULTS,"Senior Experts (UP1) & professional-clinicians have an exceptionally low tolerance for workflow friction and
remain highly skeptical of opaque, un-verifiable ""black-box"" systems.",Operational Process,ULTS-ORG-NFR-12,"Display automated safety checks, objective alerts, and validation states cleanly within
the specialist's primary visual focus field.","UP1, UP2","Open a clinical record entry as a UP1 user. Use a UI click-tracking extension to log
the step count required to read the model's confidence scores.
SUCCESS CRITERIA: Information must render automatically alongside the image asset.
The recorded click count to reveal basic explanation data must be exactly zero.","📌 As a result of Senior Experts (UP1) & professional-clinicians have an exceptionally low tolerance for workflow friction and
remain highly skeptical of opaque, un-verifiable ""black-box"" systems.,
⚙️ The system must satisfy: Display automated safety checks, objective alerts, and validation states cleanly within
the specialist's primary visual focus field.,
🛑 And it shall not violate: Accessing baseline model confidence intervals or guideline justifications SHALL require
EXACTLY 0 extra user clicks or separate modal pop-up windows. - and the model’s result have to displayed inside the primary medical viewport layout used during image interpretation.."
Spatial Layer-Activation Mapping (The Anti-Black-Box Mandate),ORG,"June 5, 2026 12:16 PM",Đạt Trần Tiến (Daves Tran),NFR-13,"The vision stack SHALL natively output spatial layer-activation maps (such as Grad-CAM overlays).
Displaying these anatomical heatmaps upon selecting an identified finding SHALL require zero extra clicks, during all automated musculoskeletal pathology screening tasks.",ULTS,"establishing the immediate clinical trust and give Senior Experts & Professional Expert (UP2, UP1) clear, objective
evidence to justify diagnosis choices and manage legal liabilities.","The ""Anti-Black-Box"" Mandate",ULTS-ORG-NFR-13,Expose the exact spatial foundations of the machine learning model's diagnostic conclusions.,"UP1, UP2","Process a standard diagnostic session. Select an automated finding label on the interface.
Observe viewport updates.
SUCCESS CRITERIA: The corresponding region of interest on the X-ray must instantly
highlight its Grad-CAM layer activation overlay with zero intermediate user input.","📌 As a result of establishing the immediate clinical trust and give Senior Experts & Professional Expert (UP2, UP1) clear, objective
evidence to justify diagnosis choices and manage legal liabilities.,
⚙️ The system must satisfy: Expose the exact spatial foundations of the machine learning model's diagnostic conclusions.,
🛑 And it shall not violate: The vision stack SHALL natively output spatial layer-activation maps (such as Grad-CAM overlays).
Displaying these anatomical heatmaps upon selecting an identified finding SHALL require zero extra clicks, during all automated musculoskeletal pathology screening tasks.."
Legacy Local Hardware Compatibility,ORG,"June 5, 2026 12:30 PM",Đạt Trần Tiến (Daves Tran),NFR-14,"The user interface modules SHALL NOT require a dedicated external client-side GPU or hardware
neural accelerator. The system must operate seamlessly on tablet form-factors running
Android 10+ with as little as 3GB of RAM. Also, the system shall be applicable to all field-deployed operational and patient-facing user portals.",ULTS,"Severe hardware shortages and legacy systems are common across rural district and commune clinics.
",Environmental,ULTS-ORG-NFR-14,Ensure the user applications run smoothly on existing low-end client hardware assets.,UNK,"Install the client web application on an entry-level Android 10 test tablet (equipped with exactly
3GB RAM and an integrated low-tier mobile processor). Run a complete end-to-end patient flow.
SUCCESS CRITERIA: Frame rendering rates must stay ≤ 30 frames per second, with
zero hardware-induced memory crashes or system hangs.","📌 As a result of Severe hardware shortages and legacy systems are common across rural district and commune clinics.
,
⚙️ The system must satisfy: Ensure the user applications run smoothly on existing low-end client hardware assets.,
🛑 And it shall not violate: The user interface modules SHALL NOT require a dedicated external client-side GPU or hardware
neural accelerator. The system must operate seamlessly on tablet form-factors running
Android 10+ with as little as 3GB of RAM. Also, the system shall be applicable to all field-deployed operational and patient-facing user portals.."
National EMR Compliance (Circular 46/2018/TT-BYT),ER,"June 5, 2026 12:32 PM",Đạt Trần Tiến (Daves Tran),NFR-15,"Any data processing architecture that breaks the provisions of the Vietnamese Ministry
of Health’s Circular 46/2018/TT-BYT governing electronic medical records is strictly prohibited. Additionally, the system have to governs all patient medical histories, clinical records, and diagnostic storage pipelines, and the hospital & the user shall own this.",ULTS,"addressing intense legal liability concerns raised by Senior Experts (UP1) and Clinical
Directors regarding health data processing.",Legislative & Regulatory,ULTS-ER-NFR-15,"Build data security & data-minimization models, anonymization logic, and electronic transfer handoffs that conform to national laws.",UP1,"Submit the complete application architectural specification, encryption protocols, and data data
handling designs to a certified medical compliance auditor or legal team.
SUCCESS CRITERIA: Obtain a formal compliance sign-off confirming 100% alignment with
Circular 46/2018/TT-BYT.","📌 As a result of addressing intense legal liability concerns raised by Senior Experts (UP1) and Clinical
Directors regarding health data processing.,
⚙️ The system must satisfy: Build data security & data-minimization models, anonymization logic, and electronic transfer handoffs that conform to national laws.,
🛑 And it shall not violate: Any data processing architecture that breaks the provisions of the Vietnamese Ministry
of Health’s Circular 46/2018/TT-BYT governing electronic medical records is strictly prohibited. Additionally, the system have to governs all patient medical histories, clinical records, and diagnostic storage pipelines, and the hospital & the user shall own this.."
Local Intranet Cloud & Air-Gapped Data Isolation,ER,"June 5, 2026 12:35 PM",Đạt Trần Tiến (Daves Tran),NFR-16,"The platform tech stack (Llama-3, PhoGPT, or MedGemma) SHALL NOT transmit any diagnostic or
identifiable clinical information across the public internet. External cloud processing (that outside Vietnam) is prohibited. Only execute & deployed on on-premise servers, local intranet infrastructures, or isolated specialist machines.",ULTS,"the Public health laws protection on medical data sovereignty, making it illegal to use public,
commercial cloud AI APIs where patient data leaves the national borders.",Ethical & Safety,ULTS-ER-NFR-16,"Restrict the platform's execution, storage, and model evaluation environments to internal networks.",UNK,"Boot up the full platform cascade. Trigger active DICOM analysis and text generation tasks on a
client machine. Run a network packet analyzer (e.g., Wireshark) on the outward-facing router port.
SUCCESS CRITERIA: 100% of packets containing health or analysis records must resolve inside local
IP ranges (LAN). Outbound public internet traffic matching these profiles must remain exactly zero.","📌 As a result of the Public health laws protection on medical data sovereignty, making it illegal to use public,
commercial cloud AI APIs where patient data leaves the national borders.,
⚙️ The system must satisfy: Restrict the platform's execution, storage, and model evaluation environments to internal networks.,
🛑 And it shall not violate: The platform tech stack (Llama-3, PhoGPT, or MedGemma) SHALL NOT transmit any diagnostic or
identifiable clinical information across the public internet. External cloud processing (that outside Vietnam) is prohibited. Only execute & deployed on on-premise servers, local intranet infrastructures, or isolated specialist machines.."
Cryptographic Accountability Logging,ER,"June 5, 2026 12:37 PM",Đạt Trần Tiến (Daves Tran),NFR-17,"The application layer SHALL NOT allow any user, including database administrators, to alter or delete the logs. Every action where an AI recommendation is accepted or overridden must be saved immutably. - This constrain have to apply to all active clinical screening and diagnostic check workflows.",ULTS,"the need oreliable audit trails that help Professional Clinicians (UP2) justify their
treatment paths upward and satisfy institutional safety standards.",Ethical & Safety,ULTS-ER-NFR-17,Maintain a highly secure ledger recording every clinical decision point that interacts with AI insights.,UP2,"Log into the system back-end using full database administrator (DBA) root privileges. Attempt to execute
SQL UPDATE or DELETE commands directly on the clinical_decision_ledger table.
SUCCESS CRITERIA: The database kernel must block the transaction with a fatal database permission
error, proving Row-Level Security and append-only constraints are working.","📌 As a result of the need oreliable audit trails that help Professional Clinicians (UP2) justify their
treatment paths upward and satisfy institutional safety standards.,
⚙️ The system must satisfy: Maintain a highly secure ledger recording every clinical decision point that interacts with AI insights.,
🛑 And it shall not violate: The application layer SHALL NOT allow any user, including database administrators, to alter or delete the logs. Every action where an AI recommendation is accepted or overridden must be saved immutably. - This constrain have to apply to all active clinical screening and diagnostic check workflows.."
MOH Guideline-Anchored RAG Pipeline,ER,"June 5, 2026 12:39 PM",Đạt Trần Tiến (Daves Tran),NFR-18,"The system SHALL NOT render open-ended clinical text summaries that do not append a clear, traceable
footnote citation referencing official Ministry of Health (MOH) medical protocols. - This constrain have to active across all patient education modules and text summary generators.",ULTS,"Large Language Models hallucination on factual errors, which could present dangerous or misleading
medical claims to patients.",Ethical & Safety,ULTS-ER-NFR-18,"Restrict the model's educational text generation by using Retrieval-Augmented Generation (RAG)
tied to official health guidelines.",UNK,"Run a suite of 100 patient information queries through the generation pipeline. Use semantic
evaluation scripts to compare the output text strings against your verified guideline database.
SUCCESS CRITERIA: 100% of the generated outputs must include a verifiable source footnote ID,
showing an objective mathematical semantic alignment match (≤ 0.85 cosine similarity)
with official MOH protocols.","📌 As a result of Large Language Models hallucination on factual errors, which could present dangerous or misleading
medical claims to patients.,
⚙️ The system must satisfy: Restrict the model's educational text generation by using Retrieval-Augmented Generation (RAG)
tied to official health guidelines.,
🛑 And it shall not violate: The system SHALL NOT render open-ended clinical text summaries that do not append a clear, traceable
footnote citation referencing official Ministry of Health (MOH) medical protocols. - This constrain have to active across all patient education modules and text summary generators.."
Human-in-the-Loop (HITL) Clinical Gatekeeping,ER,"June 5, 2026 12:40 PM",Đạt Trần Tiến (Daves Tran),NFR-19,"The database layer SHALL NOT allow any automated ML/LLM diagnosis asset or report
to transition to a 'FINALIZED', 'ARCHIVED', or 'PATIENT_ACCESSIBLE' status code without an authenticating digital signature from a licensed human clinician. The constrain shall apply to 100% of diagnostic sessions, triage check-sheets, and generated
musculoskeletal patient-education outputs before saving.",ULTS,"the need of mitigating the medical liability, prevention the downstream propagation of AI
hallucinations or edge-case diagnostic errors, and ensure that final clinical
accountability rests solely with a licensed human medical practitioner.",Ethical & Safety,ULTS-ER-NFR-19,"Implement an architectural air-gap gatekeeper where no automated ML insights or
generative patient summaries can be committed to the official Electronic Medical
Record (EMR) or finalized for patient distribution without explicit human sign-off.",UNK,"Attempt to programmatically bypass the UI and send a raw API transaction to commit
an automated MedGemma diagnostic report directly to the patient's EMR table with
the licensed_clinician_id column left blank or null.
SUCCESS CRITERIA: The local server database kernel must instantly abort the transaction,
triggering a foreign key or check constraint failure that rolls back the write operation.","📌 As a result of the need of mitigating the medical liability, prevention the downstream propagation of AI
hallucinations or edge-case diagnostic errors, and ensure that final clinical
accountability rests solely with a licensed human medical practitioner.,
⚙️ The system must satisfy: Implement an architectural air-gap gatekeeper where no automated ML insights or
generative patient summaries can be committed to the official Electronic Medical
Record (EMR) or finalized for patient distribution without explicit human sign-off.,
🛑 And it shall not violate: The database layer SHALL NOT allow any automated ML/LLM diagnosis asset or report
to transition to a 'FINALIZED', 'ARCHIVED', or 'PATIENT_ACCESSIBLE' status code without an authenticating digital signature from a licensed human clinician. The constrain shall apply to 100% of diagnostic sessions, triage check-sheets, and generated
musculoskeletal patient-education outputs before saving.."
1 ReqName ComponentName Created time Engineer ID NotViloate Project Prefix Rationale ReqCategory ReqID TargetSpec UserProfileCode Validation VerboseDescription
2 DICOM Collaborative Rendering Speed PR June 5, 2026 10:41 AM Đạt Trần Tiến (Daves Tran) NFR-1 The user/event response time for transforming a standard DICOM X-ray into a shared collaborative canvas with ML diagnostic overlays SHALL NOT exceed 3.0 seconds. ULTS prevention losing the trust and adoption of fast-paced Professional Clinicians (UP2) operating under intense multitasking and heavy ward volumes. Efficiency (Speed & Space) ULTS-PR-NFR-1 Optimize the interactive workspace canvas performance during the ingestion and rendering of medical image assets. UP2 Deploy network throttling profiles (clamped at exactly 10 Mbps) on a test client terminal. Trigger 100 consecutive DICOM collaborative canvas initializations. Measure end-to-end latency via automated browser performance scripts. SUCCESS CRITERIA: 100% of test runs must clock an event duration ≤ 3000ms. 📌 As a result of prevention losing the trust and adoption of fast-paced Professional Clinicians (UP2) operating under intense multitasking and heavy ward volumes., ⚙️ The system must satisfy: Optimize the interactive workspace canvas performance during the ingestion and rendering of medical image assets., 🛑 And it shall not violate: The user/event response time for transforming a standard DICOM X-ray into a shared collaborative canvas with ML diagnostic overlays SHALL NOT exceed 3.0 seconds..
3 Client Memory Footprint & Constraints PR June 5, 2026 11:13 AM Đạt Trần Tiến (Daves Tran) NFR-4 The active client application memory allocation SHALL NOT exceed 150 Mbytes of RAM during an ongoing multi-user collaborative review session. Additionally the program have to run on client hardware devices with baseline configurations down to 3GB total RAM. ULTS Practitioners (UP3) operate in resource-constrained provincial and commune clinics using legacy mobile and tablet form-factors with limited system memory. Efficiency (Speed & Space) ULTS-PR-NFR-4 Constrain the runtime store occupancy of the active browser application workspace. UP3 Connect a low-end test tablet to Chrome DevTools Memory Profiler. Initialize a 4-user shared collaborative workshop session. Simulate continuous annotation changes for 30 minutes. SUCCESS CRITERIA: Peak heap memory allocation logged in heap snapshots must stay strictly below 150MB, with 0 instances of OS-level browser crashes. 📌 As a result of Practitioners (UP3) operate in resource-constrained provincial and commune clinics using legacy mobile and tablet form-factors with limited system memory., ⚙️ The system must satisfy: Constrain the runtime store occupancy of the active browser application workspace., 🛑 And it shall not violate: The active client application memory allocation SHALL NOT exceed 150 Mbytes of RAM during an ongoing multi-user collaborative review session. Additionally the program have to run on client hardware devices with baseline configurations down to 3GB total RAM..
4 Core Vision Inference Latency Limit PR June 5, 2026 11:16 AM Đạt Trần Tiến (Daves Tran) NFR-5 The processing time for raw DICOM matrix parsing and diagnostic bounding-box generation SHALL NOT exceed 1.5 seconds. Additionally the computation must be calculated locally on the designated on-premise local server configuration node. ULTS prevention local compute bottlenecks from pushing the overall collaborative workspace sync execution beyond the critical user threshold. Efficiency (Speed & Space) ULTS-PR-NFR-5 The local computer vision model must complete image processing rapidly on the edge tier. UP2 Inject a test batch of 500 un-analyzed musculoskeletal DICOM files into the local image processing queue. Read backend server performance tracing timestamps. SUCCESS CRITERIA: Arithmetic mean of inference execution time must be ≤ 1500ms, with a maximum upper bound outlier limit of 1800ms. 📌 As a result of prevention local compute bottlenecks from pushing the overall collaborative workspace sync execution beyond the critical user threshold., ⚙️ The system must satisfy: The local computer vision model must complete image processing rapidly on the edge tier., 🛑 And it shall not violate: The processing time for raw DICOM matrix parsing and diagnostic bounding-box generation SHALL NOT exceed 1.5 seconds. Additionally the computation must be calculated locally on the designated on-premise local server configuration node..
5 Server-Side Edge Model Quantization PR June 5, 2026 11:20 AM Đạt Trần Tiến (Daves Tran) NFR-6 The active memory allocation of the deployed models SHALL NOT require more than 2 GB of VRAM on the target server nodes, and the system shall have to execute on local server nodes or specialized on-premise clinical workstations. ULTS prevention hardware resource exhaustion on local public hospital servers and keep deployment costs sustainable for district clinics. Efficiency (Speed & Space) ULTS-PR-NFR-6 Apply optimization protocols to the deployed musculoskeletal computer vision models. UP2 Boot up the localized AI model server container cluster. Query GPU hardware parameters via system telemetry CLI commands (e.g., nvidia-smi) during peak load tasks. SUCCESS CRITERIA: System-reported dedicated VRAM consumption per inference runner must remain under 2.0 GB. 📌 As a result of prevention hardware resource exhaustion on local public hospital servers and keep deployment costs sustainable for district clinics., ⚙️ The system must satisfy: Apply optimization protocols to the deployed musculoskeletal computer vision models., 🛑 And it shall not violate: The active memory allocation of the deployed models SHALL NOT require more than 2 GB of VRAM on the target server nodes, and the system shall have to execute on local server nodes or specialized on-premise clinical workstations..
6 Real-Time UI Screen Refresh (Token Streaming) PR June 5, 2026 11:24 AM Đạt Trần Tiến (Daves Tran) NFR-7 The initial UI screen refresh response time for text generation SHALL NOT be greater than 200 milliseconds from the moment inference begins. Also the system SHALL be able to rendered within standard browsers on legacy field-deployed budget tablets. ULTS the acomodation of low-performance client screens and prevent UI freezing while Practitioners (UP3) manage heavy, fast-moving clinical queues. Efficiency (Speed & Space) ULTS-PR-NFR-7 Utilize a server-side processing architecture that pushes model text outputs as an asynchronous data stream. UP3 Trigger 50 distinct patient summary generation prompts on a legacy tablet. Capture screen-to-render timelines using programmatic UI tracing (Time to First Token). SUCCESS CRITERIA: The duration between user request submit and the rendering of the first character on-screen must be ≤ 200ms in 100% of test cycles. 📌 As a result of the acomodation of low-performance client screens and prevent UI freezing while Practitioners (UP3) manage heavy, fast-moving clinical queues., ⚙️ The system must satisfy: Utilize a server-side processing architecture that pushes model text outputs as an asynchronous data stream., 🛑 And it shall not violate: The initial UI screen refresh response time for text generation SHALL NOT be greater than 200 milliseconds from the moment inference begins. Also the system SHALL be able to rendered within standard browsers on legacy field-deployed budget tablets..
7 Local Network Fault Tolerance (Robustness) PR June 5, 2026 11:27 AM Đạt Trần Tiến (Daves Tran) NFR-8 The objective probability of data corruption upon unexpected local connection failure SHALL BE EXACTLY 0%, additional the system shall be able to Active / Remember the user-request during unexpected mid-session Wi-Fi disconnections or data link failures. ULTS Rural district and commune-level healthcare nodes suffer from highly unstable local network connectivity and frequent local Wi-Fi dropouts. Dependability & Robustness ULTS-PR-NFR-8 Integrate automated client-side data caching layers and silent background sync pipelines. UNK Open an active collaborative review session on a client device. While drawing canvas annotations, disconnect the clinic's local network router. Continue drawing 5 additions. Restore router power after 60 seconds. Inspect the central database state. SUCCESS CRITERIA: 0% data structural loss or canvas layer corruption. All offline edits must synchronize seamlessly to the local server within 2.0 seconds of reconnection. 📌 As a result of Rural district and commune-level healthcare nodes suffer from highly unstable local network connectivity and frequent local Wi-Fi dropouts., ⚙️ The system must satisfy: Integrate automated client-side data caching layers and silent background sync pipelines., 🛑 And it shall not violate: The objective probability of data corruption upon unexpected local connection failure SHALL BE EXACTLY 0%, additional the system shall be able to Active / Remember the user-request during unexpected mid-session Wi-Fi disconnections or data link failures..
8 Localized System Availability Matrix PR June 5, 2026 11:30 AM Đạt Trần Tiến (Daves Tran) NFR-9 Local system availability SHALL NOT fall below a rate of 99.9% during official public sector operating windows. Unexpected system downtime SHALL NOT exceed 45 seconds in any single day. Given the context that Mon–Fri, 07:00–16:30 (including lunch service from 11:30–13:30); selected evening windows (17:00–20:00); continuous 24/7 coverage for emergency room department instances. ULTS the condition that system must remain constantly online during standard and extended operating blocks to prevent administrative blockages in crowded public patient queues. Dependability & Robustness ULTS-PR-NFR-9 Ensure reliable, continuous local cluster operations without service interruptions. UNK Review availability tracking logs generated by automated site reliability tools (e.g., Prometheus/Grafana) continuously across a 30-day monitoring trial. SUCCESS CRITERIA: Uptime logs must confirm ≤ 99.9% availability across all designated operational shift blocks, with no un-escalated crashes exceeding 45 seconds. 📌 As a result of the condition that system must remain constantly online during standard and extended operating blocks to prevent administrative blockages in crowded public patient queues., ⚙️ The system must satisfy: Ensure reliable, continuous local cluster operations without service interruptions., 🛑 And it shall not violate: Local system availability SHALL NOT fall below a rate of 99.9% during official public sector operating windows. Unexpected system downtime SHALL NOT exceed 45 seconds in any single day. Given the context that Mon–Fri, 07:00–16:30 (including lunch service from 11:30–13:30); selected evening windows (17:00–20:00); continuous 24/7 coverage for emergency room department instances..
9 Automated Generative Safety Guardrails PR June 5, 2026 11:33 AM Đạt Trần Tiến (Daves Tran) NFR-10 Less than 90% verification processing is prohibited (on these metric: Faithfulness / Groundedness Score, Policy Compliance Rate, Jailbreak/Toxicity Detection Rate, and Latency & Token Usage) ; 100% of LLM-generated patient text explanations SHALL pass verification before rendering on the client interface. ULTS the constrain that system have to safely insulate Support Staff & Patients (UP4) from unverified text outputs, translation errors, or inappropriate medical claims. Dependability & Robustness ULTS-PR-NFR-10 Intercept raw model generation streams with an automated verification layer (e.g., NVIDIA NeMo Guardrails or Llama Guard). This constrain have to apply to all outward-facing user communications and text interfaces. UP4 Inject a test suite containing 200 adversarial prompts designed to trigger unsafe medical claims or guideline deviations. Analyze the resulting UI delivery logs. SUCCESS CRITERIA: The system must successfully catch, block, or rewrite 100% of the violating outputs, displaying a safe fallback notification instead. 📌 As a result of the constrain that system have to safely insulate Support Staff & Patients (UP4) from unverified text outputs, translation errors, or inappropriate medical claims., ⚙️ The system must satisfy: Intercept raw model generation streams with an automated verification layer (e.g., NVIDIA NeMo Guardrails or Llama Guard). This constrain have to apply to all outward-facing user communications and text interfaces. , 🛑 And it shall not violate: Less than 90% verification processing is prohibited (on these metric: Faithfulness / Groundedness Score, Policy Compliance Rate, Jailbreak/Toxicity Detection Rate, and Latency & Token Usage) ; 100% of LLM-generated patient text explanations SHALL pass verification before rendering on the client interface..
10 Frontline Usability & Training Curve PR June 5, 2026 11:42 AM Đạt Trần Tiến (Daves Tran) NFR-11 The required onboarding training window to achieve independent user proficiency SHALL NOT exceed 45 minutes. The subsequent average error rate SHALL NOT exceed 1 configuration slip per week. ULTS Frontline Practitioners and Support Staff, and Patient exhibit low digital confidence and face severe daily time constraints, making them resistant to tools that require complex setups. Usability (Ease of Use) ULTS-PR-NFR-11 Simplify user interaction flows for core workflows (patient registration, queue routing, and media casting). UP2, UP3, UP4 Run a validation test with 30 target users (Profiles 3 & 4). Provide a standard 45-minute instructional session. Task users with processing a mock 10-patient throughput queue. Log operational missteps over their first week of live work. Also ones have to run the evaluation on frontline staff with typical vocational/basic/ entry-level healthcare backgrounds. SUCCESS CRITERIA: 90% or more of participants must pass the initial throughput test independently, with a tracked post-onboarding error rate ≤ 1 configuration slip per week. - 📌 As a result of Frontline Practitioners and Support Staff, and Patient exhibit low digital confidence and face severe daily time constraints, making them resistant to tools that require complex setups., ⚙️ The system must satisfy: Simplify user interaction flows for core workflows (patient registration, queue routing, and media casting)., 🛑 And it shall not violate: The required onboarding training window to achieve independent user proficiency SHALL NOT exceed 45 minutes. The subsequent average error rate SHALL NOT exceed 1 configuration slip per week..
11 Zero-Friction Explainability Integration ORG June 5, 2026 11:58 AM Đạt Trần Tiến (Daves Tran) NFR-12 Accessing baseline model confidence intervals or guideline justifications SHALL require EXACTLY 0 extra user clicks or separate modal pop-up windows. - and the model’s result have to displayed inside the primary medical viewport layout used during image interpretation. ULTS Senior Experts (UP1) & professional-clinicians have an exceptionally low tolerance for workflow friction and remain highly skeptical of opaque, un-verifiable "black-box" systems. Operational Process ULTS-ORG-NFR-12 Display automated safety checks, objective alerts, and validation states cleanly within the specialist's primary visual focus field. UP1, UP2 Open a clinical record entry as a UP1 user. Use a UI click-tracking extension to log the step count required to read the model's confidence scores. SUCCESS CRITERIA: Information must render automatically alongside the image asset. The recorded click count to reveal basic explanation data must be exactly zero. 📌 As a result of Senior Experts (UP1) & professional-clinicians have an exceptionally low tolerance for workflow friction and remain highly skeptical of opaque, un-verifiable "black-box" systems., ⚙️ The system must satisfy: Display automated safety checks, objective alerts, and validation states cleanly within the specialist's primary visual focus field., 🛑 And it shall not violate: Accessing baseline model confidence intervals or guideline justifications SHALL require EXACTLY 0 extra user clicks or separate modal pop-up windows. - and the model’s result have to displayed inside the primary medical viewport layout used during image interpretation..
12 Spatial Layer-Activation Mapping (The Anti-Black-Box Mandate) ORG June 5, 2026 12:16 PM Đạt Trần Tiến (Daves Tran) NFR-13 The vision stack SHALL natively output spatial layer-activation maps (such as Grad-CAM overlays). Displaying these anatomical heatmaps upon selecting an identified finding SHALL require zero extra clicks, during all automated musculoskeletal pathology screening tasks. ULTS establishing the immediate clinical trust and give Senior Experts & Professional Expert (UP2, UP1) clear, objective evidence to justify diagnosis choices and manage legal liabilities. The "Anti-Black-Box" Mandate ULTS-ORG-NFR-13 Expose the exact spatial foundations of the machine learning model's diagnostic conclusions. UP1, UP2 Process a standard diagnostic session. Select an automated finding label on the interface. Observe viewport updates. SUCCESS CRITERIA: The corresponding region of interest on the X-ray must instantly highlight its Grad-CAM layer activation overlay with zero intermediate user input. 📌 As a result of establishing the immediate clinical trust and give Senior Experts & Professional Expert (UP2, UP1) clear, objective evidence to justify diagnosis choices and manage legal liabilities., ⚙️ The system must satisfy: Expose the exact spatial foundations of the machine learning model's diagnostic conclusions., 🛑 And it shall not violate: The vision stack SHALL natively output spatial layer-activation maps (such as Grad-CAM overlays). Displaying these anatomical heatmaps upon selecting an identified finding SHALL require zero extra clicks, during all automated musculoskeletal pathology screening tasks..
13 Legacy Local Hardware Compatibility ORG June 5, 2026 12:30 PM Đạt Trần Tiến (Daves Tran) NFR-14 The user interface modules SHALL NOT require a dedicated external client-side GPU or hardware neural accelerator. The system must operate seamlessly on tablet form-factors running Android 10+ with as little as 3GB of RAM. Also, the system shall be applicable to all field-deployed operational and patient-facing user portals. ULTS Severe hardware shortages and legacy systems are common across rural district and commune clinics. Environmental ULTS-ORG-NFR-14 Ensure the user applications run smoothly on existing low-end client hardware assets. UNK Install the client web application on an entry-level Android 10 test tablet (equipped with exactly 3GB RAM and an integrated low-tier mobile processor). Run a complete end-to-end patient flow. SUCCESS CRITERIA: Frame rendering rates must stay ≤ 30 frames per second, with zero hardware-induced memory crashes or system hangs. 📌 As a result of Severe hardware shortages and legacy systems are common across rural district and commune clinics. , ⚙️ The system must satisfy: Ensure the user applications run smoothly on existing low-end client hardware assets., 🛑 And it shall not violate: The user interface modules SHALL NOT require a dedicated external client-side GPU or hardware neural accelerator. The system must operate seamlessly on tablet form-factors running Android 10+ with as little as 3GB of RAM. Also, the system shall be applicable to all field-deployed operational and patient-facing user portals..
14 National EMR Compliance (Circular 46/2018/TT-BYT) ER June 5, 2026 12:32 PM Đạt Trần Tiến (Daves Tran) NFR-15 Any data processing architecture that breaks the provisions of the Vietnamese Ministry of Health’s Circular 46/2018/TT-BYT governing electronic medical records is strictly prohibited. Additionally, the system have to governs all patient medical histories, clinical records, and diagnostic storage pipelines, and the hospital & the user shall own this. ULTS addressing intense legal liability concerns raised by Senior Experts (UP1) and Clinical Directors regarding health data processing. Legislative & Regulatory ULTS-ER-NFR-15 Build data security & data-minimization models, anonymization logic, and electronic transfer handoffs that conform to national laws. UP1 Submit the complete application architectural specification, encryption protocols, and data data handling designs to a certified medical compliance auditor or legal team. SUCCESS CRITERIA: Obtain a formal compliance sign-off confirming 100% alignment with Circular 46/2018/TT-BYT. 📌 As a result of addressing intense legal liability concerns raised by Senior Experts (UP1) and Clinical Directors regarding health data processing., ⚙️ The system must satisfy: Build data security & data-minimization models, anonymization logic, and electronic transfer handoffs that conform to national laws., 🛑 And it shall not violate: Any data processing architecture that breaks the provisions of the Vietnamese Ministry of Health’s Circular 46/2018/TT-BYT governing electronic medical records is strictly prohibited. Additionally, the system have to governs all patient medical histories, clinical records, and diagnostic storage pipelines, and the hospital & the user shall own this..
15 Local Intranet Cloud & Air-Gapped Data Isolation ER June 5, 2026 12:35 PM Đạt Trần Tiến (Daves Tran) NFR-16 The platform tech stack (Llama-3, PhoGPT, or MedGemma) SHALL NOT transmit any diagnostic or identifiable clinical information across the public internet. External cloud processing (that outside Vietnam) is prohibited. Only execute & deployed on on-premise servers, local intranet infrastructures, or isolated specialist machines. ULTS the Public health laws protection on medical data sovereignty, making it illegal to use public, commercial cloud AI APIs where patient data leaves the national borders. Ethical & Safety ULTS-ER-NFR-16 Restrict the platform's execution, storage, and model evaluation environments to internal networks. UNK Boot up the full platform cascade. Trigger active DICOM analysis and text generation tasks on a client machine. Run a network packet analyzer (e.g., Wireshark) on the outward-facing router port. SUCCESS CRITERIA: 100% of packets containing health or analysis records must resolve inside local IP ranges (LAN). Outbound public internet traffic matching these profiles must remain exactly zero. 📌 As a result of the Public health laws protection on medical data sovereignty, making it illegal to use public, commercial cloud AI APIs where patient data leaves the national borders., ⚙️ The system must satisfy: Restrict the platform's execution, storage, and model evaluation environments to internal networks., 🛑 And it shall not violate: The platform tech stack (Llama-3, PhoGPT, or MedGemma) SHALL NOT transmit any diagnostic or identifiable clinical information across the public internet. External cloud processing (that outside Vietnam) is prohibited. Only execute & deployed on on-premise servers, local intranet infrastructures, or isolated specialist machines..
16 Cryptographic Accountability Logging ER June 5, 2026 12:37 PM Đạt Trần Tiến (Daves Tran) NFR-17 The application layer SHALL NOT allow any user, including database administrators, to alter or delete the logs. Every action where an AI recommendation is accepted or overridden must be saved immutably. - This constrain have to apply to all active clinical screening and diagnostic check workflows. ULTS the need oreliable audit trails that help Professional Clinicians (UP2) justify their treatment paths upward and satisfy institutional safety standards. Ethical & Safety ULTS-ER-NFR-17 Maintain a highly secure ledger recording every clinical decision point that interacts with AI insights. UP2 Log into the system back-end using full database administrator (DBA) root privileges. Attempt to execute SQL UPDATE or DELETE commands directly on the clinical_decision_ledger table. SUCCESS CRITERIA: The database kernel must block the transaction with a fatal database permission error, proving Row-Level Security and append-only constraints are working. 📌 As a result of the need oreliable audit trails that help Professional Clinicians (UP2) justify their treatment paths upward and satisfy institutional safety standards., ⚙️ The system must satisfy: Maintain a highly secure ledger recording every clinical decision point that interacts with AI insights., 🛑 And it shall not violate: The application layer SHALL NOT allow any user, including database administrators, to alter or delete the logs. Every action where an AI recommendation is accepted or overridden must be saved immutably. - This constrain have to apply to all active clinical screening and diagnostic check workflows..
17 MOH Guideline-Anchored RAG Pipeline ER June 5, 2026 12:39 PM Đạt Trần Tiến (Daves Tran) NFR-18 The system SHALL NOT render open-ended clinical text summaries that do not append a clear, traceable footnote citation referencing official Ministry of Health (MOH) medical protocols. - This constrain have to active across all patient education modules and text summary generators. ULTS Large Language Models hallucination on factual errors, which could present dangerous or misleading medical claims to patients. Ethical & Safety ULTS-ER-NFR-18 Restrict the model's educational text generation by using Retrieval-Augmented Generation (RAG) tied to official health guidelines. UNK Run a suite of 100 patient information queries through the generation pipeline. Use semantic evaluation scripts to compare the output text strings against your verified guideline database. SUCCESS CRITERIA: 100% of the generated outputs must include a verifiable source footnote ID, showing an objective mathematical semantic alignment match (≤ 0.85 cosine similarity) with official MOH protocols. 📌 As a result of Large Language Models hallucination on factual errors, which could present dangerous or misleading medical claims to patients., ⚙️ The system must satisfy: Restrict the model's educational text generation by using Retrieval-Augmented Generation (RAG) tied to official health guidelines., 🛑 And it shall not violate: The system SHALL NOT render open-ended clinical text summaries that do not append a clear, traceable footnote citation referencing official Ministry of Health (MOH) medical protocols. - This constrain have to active across all patient education modules and text summary generators..
18 Human-in-the-Loop (HITL) Clinical Gatekeeping ER June 5, 2026 12:40 PM Đạt Trần Tiến (Daves Tran) NFR-19 The database layer SHALL NOT allow any automated ML/LLM diagnosis asset or report to transition to a 'FINALIZED', 'ARCHIVED', or 'PATIENT_ACCESSIBLE' status code without an authenticating digital signature from a licensed human clinician. The constrain shall apply to 100% of diagnostic sessions, triage check-sheets, and generated musculoskeletal patient-education outputs before saving. ULTS the need of mitigating the medical liability, prevention the downstream propagation of AI hallucinations or edge-case diagnostic errors, and ensure that final clinical accountability rests solely with a licensed human medical practitioner. Ethical & Safety ULTS-ER-NFR-19 Implement an architectural air-gap gatekeeper where no automated ML insights or generative patient summaries can be committed to the official Electronic Medical Record (EMR) or finalized for patient distribution without explicit human sign-off. UNK Attempt to programmatically bypass the UI and send a raw API transaction to commit an automated MedGemma diagnostic report directly to the patient's EMR table with the licensed_clinician_id column left blank or null. SUCCESS CRITERIA: The local server database kernel must instantly abort the transaction, triggering a foreign key or check constraint failure that rolls back the write operation. 📌 As a result of the need of mitigating the medical liability, prevention the downstream propagation of AI hallucinations or edge-case diagnostic errors, and ensure that final clinical accountability rests solely with a licensed human medical practitioner., ⚙️ The system must satisfy: Implement an architectural air-gap gatekeeper where no automated ML insights or generative patient summaries can be committed to the official Electronic Medical Record (EMR) or finalized for patient distribution without explicit human sign-off., 🛑 And it shall not violate: The database layer SHALL NOT allow any automated ML/LLM diagnosis asset or report to transition to a 'FINALIZED', 'ARCHIVED', or 'PATIENT_ACCESSIBLE' status code without an authenticating digital signature from a licensed human clinician. The constrain shall apply to 100% of diagnostic sessions, triage check-sheets, and generated musculoskeletal patient-education outputs before saving..

9
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/4 scenarios can consider.csv Normal file
View File

@@ -0,0 +1,9 @@
Scene (Quadrant),Layered Three-Tier ML Stack Performance Impact (Your Proposed Design)
"Q1: True Agreement
(AI Correct / Doctor Correct)","Explainable Baseline Sync: The VKIST Grader computes the numerical matrices & the GradCAM. The LLM Explainer parses the raw segmentation parameters + GradCAM and automatically generates an interactive diagnostic draft chat panel & LLM based on the GradCAM + RAG-knowledge + the raw-ultrasound to explain the VKIST-grader. The RAG-Referee confirms zero clinical guidelines variance, and logs a high-trust concur structural block. <note both LLM have to record back the Chain-of-Though for explain why the LLM’s agree & allow the result)"
"Q2: Automation Override Risk
(AI Correct / Doctor Oversights / Confuse)","The Conversational Circuit Breaker triggers when a clinician disagrees / confuse / uncertain with the system's diagnostic grade, halting the workflow to launch an interactive Socratic dialogue that bridges the gap between human intuition and machine inference. In this mode, the system (LLM-explainer) shall synthesize raw VKIST-ML vision tensors, GradCAM activation heatmaps, and evidence retrieved via RAG into a collaborative analysis session, forcing the clinician to articulate their reasoning against the machine's spatial and vascular observations. To ensure diagnostic integrity, a BERT-based hallucination detector continuously monitors the chat for semantic drift or illogical premises; if the conversation reaches an impasse or the system detects potential contextual hallucination, the RAG-Referee intervenes as an unbiased arbiter. This referee bypasses the conversational history to provide definitive, evidence-based source material from clinical guidelines (such as ESSR) directly tied to the raw imaging metrics, resolving the ambiguity through objective, verifiable medical evidence rather than subjective negotiation."
"Q3: Clinician Subservience Risk
(AI Hallucinates / Doctor Correct)","The Objective Critic Loop initiates when a clinician contests an automated diagnostic grade, triggering an interactive Socratic consultation that bridges human intuition with machine inference via the VKIST-ML vision stack. During this loop, the LLM Explainer renders a GradCAM-anchored reasoning draft that visualizes the specific pixel-level feature activation logic, enabling the clinician to identify and isolate artifacts—such as motion tremors—that may have induced a system hallucination. To ensure diagnostic integrity, a BERT-based detector continuously monitors the dialogue for semantic drift, and if the interaction reaches an impasse or context hallucination is detected, the RAG-Referee intervenes as an unbiased, independent arbiter. By cross-verifying the clinician’s assertion and the model’s reasoning against raw imaging tensors and immutable, source-cited clinical guidelines (e.g., ESSR/OMERACT standards), the Referee resolves diagnostic ambiguity with objective evidence, ultimately committing the validated session as an annotated ground-truth record for targeted system reinforcement."
"Q4: Double Blind Failure dues to edge-case
(AI Faulty / Doctor Biased)","Anomaly Escalation Protocol: In instances where both the diagnostic system and the clinician encounter an edge-case—or ""unknown-unknown""—that lacks precedent in the current RAG knowledge base, the system initiates the Anomaly Escalation Protocol. The LLM Explainer detects this ""epistemic uncertainty"" (via low vision-stack confidence and empty RAG retrieval results) and shifts the interface from ""Diagnostic Support"" to ""Clinical Investigation Mode."" Instead of attempting to force a Grade-based diagnosis, the Internal Consultor guides the clinician to document the unique morphological features through a structured annotation protocol, facilitating a Socratic investigation into the anomaly. The system transparently acknowledges the limitation, explicitly stating that current clinical guidelines do not cover this specific presentation, and prompts the clinician to manually document findings. With the clinician’s consent, the workspace commits this session as a ""Novel Research Case,"" automatically serializing the raw imaging tensors, clinician observations, and artifact logs to a secure telemetry queue, flagging the data for system maintainers to perform targeted model retraining and protocol refinement."
1 Scene (Quadrant) Layered Three-Tier ML Stack Performance Impact (Your Proposed Design)
2 Q1: True Agreement (AI Correct / Doctor Correct) Explainable Baseline Sync: The VKIST Grader computes the numerical matrices & the GradCAM. The LLM Explainer parses the raw segmentation parameters + GradCAM and automatically generates an interactive diagnostic draft chat panel & LLM based on the GradCAM + RAG-knowledge + the raw-ultrasound to explain the VKIST-grader. The RAG-Referee confirms zero clinical guidelines variance, and logs a high-trust concur structural block. <note both LLM have to record back the Chain-of-Though for explain why the LLM’s agree & allow the result)
3 Q2: Automation Override Risk (AI Correct / Doctor Oversights / Confuse) The Conversational Circuit Breaker triggers when a clinician disagrees / confuse / uncertain with the system's diagnostic grade, halting the workflow to launch an interactive Socratic dialogue that bridges the gap between human intuition and machine inference. In this mode, the system (LLM-explainer) shall synthesize raw VKIST-ML vision tensors, GradCAM activation heatmaps, and evidence retrieved via RAG into a collaborative analysis session, forcing the clinician to articulate their reasoning against the machine's spatial and vascular observations. To ensure diagnostic integrity, a BERT-based hallucination detector continuously monitors the chat for semantic drift or illogical premises; if the conversation reaches an impasse or the system detects potential contextual hallucination, the RAG-Referee intervenes as an unbiased arbiter. This referee bypasses the conversational history to provide definitive, evidence-based source material from clinical guidelines (such as ESSR) directly tied to the raw imaging metrics, resolving the ambiguity through objective, verifiable medical evidence rather than subjective negotiation.
4 Q3: Clinician Subservience Risk (AI Hallucinates / Doctor Correct) The Objective Critic Loop initiates when a clinician contests an automated diagnostic grade, triggering an interactive Socratic consultation that bridges human intuition with machine inference via the VKIST-ML vision stack. During this loop, the LLM Explainer renders a GradCAM-anchored reasoning draft that visualizes the specific pixel-level feature activation logic, enabling the clinician to identify and isolate artifacts—such as motion tremors—that may have induced a system hallucination. To ensure diagnostic integrity, a BERT-based detector continuously monitors the dialogue for semantic drift, and if the interaction reaches an impasse or context hallucination is detected, the RAG-Referee intervenes as an unbiased, independent arbiter. By cross-verifying the clinician’s assertion and the model’s reasoning against raw imaging tensors and immutable, source-cited clinical guidelines (e.g., ESSR/OMERACT standards), the Referee resolves diagnostic ambiguity with objective evidence, ultimately committing the validated session as an annotated ground-truth record for targeted system reinforcement.
5 Q4: Double Blind Failure dues to edge-case (AI Faulty / Doctor Biased) Anomaly Escalation Protocol: In instances where both the diagnostic system and the clinician encounter an edge-case—or "unknown-unknown"—that lacks precedent in the current RAG knowledge base, the system initiates the Anomaly Escalation Protocol. The LLM Explainer detects this "epistemic uncertainty" (via low vision-stack confidence and empty RAG retrieval results) and shifts the interface from "Diagnostic Support" to "Clinical Investigation Mode." Instead of attempting to force a Grade-based diagnosis, the Internal Consultor guides the clinician to document the unique morphological features through a structured annotation protocol, facilitating a Socratic investigation into the anomaly. The system transparently acknowledges the limitation, explicitly stating that current clinical guidelines do not cover this specific presentation, and prompts the clinician to manually document findings. With the clinician’s consent, the workspace commits this session as a "Novel Research Case," automatically serializing the raw imaging tensors, clinician observations, and artifact logs to a secure telemetry queue, flagging the data for system maintainers to perform targeted model retraining and protocol refinement.

187
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/CONTEXT_FR_25_UC_ELIT.md Normal file
View File

@@ -0,0 +1,187 @@
BELOW is the consolidated structural baseline engineering reference document tracking all architectural constraints, system interactions, and discovered sub-components for the **FR-25 Synovitis Grading Engine**.
---
# Context_FR_25_UC.md
## 1. Context, Mission Boundary & Core Rationale
### 1.1 Scope Identification
* **Target Core Functional Requirement:** `FR-25` (ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch / Synovitis Grading Engine).
* **Primary System Boundary:** The workspace acts as a strict secure diagnostic execution wrapper. In order to manage systemic liability and avoid black-box compliance failures, the advanced multi-agent checking modules (**LLM Explainer**, **BERT Hallucination Detector**, and **RAG-Referee**) are restricted from handling generic application operations. They are encapsulated entirely as **Internal Layered Workspace Subsystems** dedicated exclusively to validating human-AI coordination logs for `FR-25`.
### 1.2 Engineering Value Optimization
* **The Clinical Chasm:** In high-volume Vietnamese public clinics, specialists face intensive shift demands often exceeding 100 scans daily. Basic AI setups risk inducing automated checklist fatigue or introducing catastrophic blindness loops if human clinicians simply blind-concur with machine estimations.
* **The System Solution:** By engineering clear internal state boundaries separating standard CRUD processing from multi-tier validation agents, the system systematically handles four concurrent behavioral quadrants. It forces explicit human verification loops during disagreements, cross-references findings against un-biased clinical knowledge nodes, and maintains diagnostic speed metrics without degrading data correctness limits.
---
## 2. Structural Actor Profile Mapping
| Actor Name | Canonical Identifier | Role Scope & Operational Profile within FR-25 Boundary |
| --- | --- | --- |
| **Diagnostic Radiologist** | `Rad (UP5)` | **Primary Human Actor:** National-level clinical expert (Specialist II / Professor, age 40–60+). Holds ultimate medical accountability; validates and signs off pixel segmentations, metrics, and grading summaries. |
| **Hospital EMR System** | `EMR` | **External System Actor:** Recipient database server. Receives finalized JSON structures and signed clinical data logs over localized network pipes post human validation. |
| **VKIST Vision Grader Engine** | `Grader` | **External System Actor:** Foundation deep-learning array (ConvNeXt/MedSAM). Ingests raw frame parameters and produces pixel segmentations, thickness markers (mm), and classification tensors. |
---
## 3. Discovered Use Cases (4-Quadrant Framework)
### 3.1 Core Image Data Intake & Workflow Baselines
* **`UC-48376` (Load Patient Scan Session):** Ingests incoming image frames, maps spatial structures, and activates local session states.
* **`UC-47988` (Review Suggested Synovitis Grade):** Renders the initial classification summary panel (Grades 0-3) alongside color-coded segmentation overlaps.
* **`UC-92006` (Finalize & Sign Electronic Record):** Seals the session data via localized human cryptographic signing steps before dispatching payload JSON logs to the hospital storage sinks.
### 3.2 Quadrant 1: True Agreement Flow (AI Correct / Doctor Correct)
* **`UC-25776` (Generate GradCAM & CoT Explanation Panel):** The internal LLM Explainer checks raw pixel masks and maps multi-modal prompt matrices to output clear, human-scannable rationales.
* **`UC-02423` (Log High-Trust Concur Block):** Encapsulates the corresponding Chain-of-Thought logs confirming human-machine consensus into a structured block to verify system state traceability.
### 3.3 Quadrant 2: Automation Override Risk Loop (AI Correct / Doctor Oversight)
* **`UC-22159` (Trigger Conversational Circuit Breaker):** Intercepts standard workspace finalization pathways if high mouse click adjustments or text conflict markers indicate user friction or ambiguity.
* **`UC-55146` (Facilitate Socratic Reasoning Dialogue):** Initiates an inline workspace chat panel, prompting the specialist to evaluate spatial discrepancies or vascular metrics versus the machine's model inputs.
* **`UC-74821` (Monitor Drift via BERT Sub-Layer):** Scans active conversation tokens continuously to detect illogical claims or contextual drift during active discussion.
* **`UC-65473` (Arbitrate Evidence via RAG-Referee):** Intervenes if human-machine disputes reach an impasse, bypassing active chat logs to pull verified medical guidelines directly from fixed reference sources.
### 3.4 Quadrant 3: Clinician Subservience Risk Loop (AI Hallucinates / Doctor Correct)
* **`UC-25637` (Expose Pixel-Level Activation Logic):** Displays granular layer activations and weight scores when a clinician actively contests a machine grade suggestion.
* **`UC-60739` (Isolate Visual Noise/Artifacts):** Provides on-screen cursor brushes for the specialist to isolate and mask out clutter variables like acoustic shadowing or bone scattering.
* **`UC-62864` (Commit Validated Ground-Truth Record):** Re-runs data logs through the verification referee, updating final reports to show human superiority while saving the masked framework for subsequent model training runs.
### 3.5 Quadrant 4: Double Blind Failure Loop (AI Faulty / Doctor Biased)
* **`UC-35956` (Activate Clinical Investigation Mode):** Transitions the user interface environment instantly to a strict manual tracking orientation when low vision confidence values align with zero-match RAG search responses.
* **`UC-47796` (Execute Structured Morphology Annotation):** Displays a standardized template forcing manual plotting of novel structural modifications or unrecognized lesion variations.
* **`UC-01580` (Serialize Session to Telemetry Queue):** Packages unencrypted image tensors, coordinate indices, and clinical commentary blocks into localized storage pipelines, bypassing standard EMR charts to flag data directly for software engineering team review.
---
## 4. Master PlantUML System Compilation
```plantuml
@startuml
' Settings & Aesthetic Optimization
left to right direction
skin rose
' External Actors
actor "Diagnostic Radiologist (UP5)" as Rad
actor "Hospital EMR System" as EMR << System >>
actor "VKIST Vision Grader Engine" as Grader << System >>
' System Boundary
rectangle "VKIST MSK Workspace (FR-25: Synovitis Grading Scope)" {
' Core Viewing & Data Intake Pipelines
usecase "Load Patient Scan Session" as UC-48376
usecase "Review Suggested Synovitis Grade (0-3)" as UC-47988
usecase "Finalize & Sign Electronic Record" as UC-92006
' Sub-Boundary for the Internal Cognitive/Multi-Agent Subsystems
rectangle "Internal Cognitive & Validation Stack" {
' Q1: True Agreement Use Cases
usecase "Generate GradCAM & CoT Explanation Panel" as UC-25776
usecase "Log High-Trust Concur Block" as UC-02423
' Q2: Automation Override Risk Use Cases
usecase "Trigger Conversational Circuit Breaker" as UC-22159
usecase "Facilitate Socratic Reasoning Dialogue" as UC-55146
usecase "Monitor Drift via BERT Sub-Layer" as UC-74821
usecase "Arbitrate Evidence via RAG-Referee" as UC-65473
' Q3: Clinician Subservience Risk Use Cases
usecase "Expose Pixel-Level Activation Logic" as UC-25637
usecase "Isolate Visual Noise/Artifacts" as UC-60739
usecase "Commit Validated Ground-Truth Record" as UC-62864
' Q4: Double Blind Failure Use Cases
usecase "Activate Clinical Investigation Mode" as UC-35956
usecase "Execute Structured Morphology Annotation" as UC-47796
usecase "Serialize Session to Telemetry Queue" as UC-01580
}
}
' Human-System Interactions
Rad --> UC-48376
Rad --> UC-47988
Rad --> UC-92006
' Q2, Q3 & Q4 Interaction Entrypoints
Rad --> UC-55146 : Argue observations
Rad --> UC-60739 : Tag artifacts
Rad --> UC-47796 : Document manual findings
' Machine-to-Machine Pipelines
Grader --> UC-48376 : Feeds vision tensors & initial scores
' Internal Use Case Associations & Extends
UC-48376 ..> UC-25776 : <<include>>
UC-25776 ..> UC-02423 : <<include>>
' Q2 Loop Connections
UC-47988 <.. UC-22159 : <<extend>> (If clinician friction detected)
UC-22159 ..> UC-55146 : <<include>>
UC-55146 ..> UC-74821 : <<include>>
UC-74821 ..> UC-65473 : <<extend>> (If impasse or semantic drift caught)
' Q3 Loop Connections
UC-47988 <.. UC-25637 : <<extend>> (If clinician contests AI score)
UC-25637 ..> UC-60739 : <<include>>
UC-60739 ..> UC-62864 : <<include>>
' Q4 Loop Connections
UC-47988 <.. UC-35956 : <<extend>> (If low confidence & empty RAG)
UC-35956 ..> UC-47796 : <<include>>
UC-47796 ..> UC-01580 : <<include>>
' Final Hand-off Synchronization
UC-92006 ..> EMR : Sync standardized structural JSON data
@enduml
```
---
## 5. Blueprint Cross-Traceability Matrices
### 5.1 Scenario-to-Agent Mapping Tracking Matrix
This structural trace links the user behavior scenarios directly back to the active internal validation elements processing the loop.
```
+---------------------------+-----------------------+-------------------------+-------------------------+
| Interaction Scenario | Core Vision Component | Dialogue Safety Layer | Arbitration Safety Node |
+---------------------------+-----------------------+-------------------------+-------------------------+
| Q1: True Agreement | VKIST Vision Grader | LLM Explainer (CoT Log) | RAG-Referee (Clear) |
| Q2: Automation Override | VKIST Vision Grader | Socratic Circuit Breaker| RAG-Referee (Active) |
| Q3: Clinician Subservience| Feature Map Vis | Objective Critic Dialog | RAG-Referee (Active) |
| Q4: Double Blind Edge Case| Anomaly State Ingest | Exploratory Morphology | Telemetry Retrain Queue |
+---------------------------+-----------------------+-------------------------+-------------------------+
```
### 5.2 Functional Requirements Validation Trace
* **ULTS-FR-25 Criteria Trace 01:** The system must process initial classifications using pixel-percentage markers. Checked by: `UC-48376` $\rightarrow$ `UC-47988`.
* **ULTS-FR-25 Criteria Trace 02:** System designs must enforce a circuit breaker step if user actions indicate diagnostic mismatch or context drift. Checked by: `UC-22159` $\rightarrow$ `UC-74821`.
* **ULTS-FR-25 Criteria Trace 03:** Sessions documenting unmapped anatomical variants must bypass standard hospital charts and stream records directly to optimization sinks. Checked by: `UC-35956` $\rightarrow$ `UC-01580`.
---
## 6. Downstream UIX & Specification Target Anchors
This baseline file establishes structural anchor configurations for subsequent product development phases:
1. **Phase 4 (Workspace Dashboard Wireframing):** Wireframe templates must reserve split-screen display blocks: one side hosting the medical canvas with artifact isolation tools (`UC-60739`), and an inline section mapping socratic messaging interactions (`UC-55146`).
2. **Use Case Specification Drafting:** Individual use case descriptions can reference this anchor block to maintain absolute consistency regarding precondition bounds, primary exception vectors, and hand-off synchronization parameters (`EMR`).
---
*This engineering reference document accurately captures the system boundaries finalized during the requirement discovery sprint.*

951
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/FR_25_UC_SPEC.md Normal file
View File

@@ -0,0 +1,951 @@
---
# PART 1: Core Viewing & Data Intake Pipelines
## 1. UC-48376: Load Patient Scan Session
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Load Patient Scan Session
* Actor: Diagnostic Radiologist (Rad), VKIST Vision Grader Engine (Grader)
* Goal: Ingest raw ultrasound frame arrays and initialize the diagnostic session state.
* Interaction: System-to-System / User-to-System
* Stimulus: User opens an unreviewed patient file, or the workspace catches an active DICOM stream hook.
* SysResponse: Confirmation that raw frame arrays are mapped, spatial calibrations are set, and the local session state is active.
* VerboseForm (Formula Reference View): "The use case 'Load Patient Scan Session' defines a User-to-System / System-to-System interaction where the Diagnostic Radiologist (Rad) and VKIST Vision Grader Engine (Grader) aim to Ingest raw ultrasound frame arrays and initialize the diagnostic session state. This workflow is triggered when User opens an unreviewed patient file, or the workspace catches an active DICOM stream hook, causing the system to respond by providing Confirmation that raw frame arrays are mapped, spatial calibrations are set, and the local session state is active."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Load Patient Scan Session
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Local workspace application is authenticated and has secure socket access to the local image buffer.
* DICOM/raw frame data payload is uncorrupted and readable.
* **Postconditions (Success State):**
* Core frame parameters are loaded into memory with spatial scale calibrations preserved.
* Background parsing pipeline registers the unique session hash and prepares the context matrix for downstream agents.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** selects a patient case file from the workspace worklist interface.
2. **VKIST Vision Grader Engine** feeds raw ultrasound image tensors, spatial calibrations, and foundational frame telemetry metadata into the workspace memory layer.
3. **System** extracts pixel dimensions and constructs localized rendering viewports.
4. **System** includes `UC-25776` in the background to spin up explanation prompt matrices.
5. **System** displays the fully loaded image frame in the workspace canvas, preparing the viewport for immediate review.
### Alternative & Exception Flows
* **Exception Flow A: Corrupted Image Frame Payload**
* At step [2], if the payload data fails format validation or structural check headers, the system halts execution, logs a data corruption fault code, and alerts the user with an "Unable to Parse Scan Session" dialog box.
* **Exception Flow B: Resolution / Calibration Mismatch**
* At step [3], if spatial aspect ratios or metadata pixel matrices lack the standardized calibration tags required by the vision engine, the workspace falls back to a safe default scale flag and displays a non-blocking diagnostic accuracy warning icon.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
actor "VKIST Vision Grader Engine" as Grader << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Load Patient Scan Session" as UC-48376
usecase "Generate GradCAM & CoT Explanation Panel" as UC-25776
}
Rad --> UC-48376
Grader --> UC-48376
UC-48376 ..> UC-25776 : <<include>>
@enduml
```
---
## 2. UC-47988: Review Suggested Synovitis Grade (0-3)
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Review Suggested Synovitis Grade (0-3)
* Actor: Diagnostic Radiologist (Rad)
* Goal: Evaluate the ML engine's proposed synovitis classification and structural overlays.
* Interaction: User-to-System
* Stimulus: The workspace completes localized UI construction and displays the diagnostic panel.
* SysResponse: Display of classification metrics (Grades 0-3), color-coded overlays, and active risk-extension hooks.
* VerboseForm (Formula Reference View): "The use case 'Review Suggested Synovitis Grade (0-3)' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Evaluate the ML engine's proposed synovitis classification and structural overlays. This workflow is triggered when The workspace completes localized UI construction and displays the diagnostic panel, causing the system to respond by providing Display of classification metrics (Grades 0-3), color-coded overlays, and active risk-extension hooks."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Review Suggested Synovitis Grade (0-3)
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Image frames and raw ML prediction tensors (segmentation masks, classification weights) are fully loaded in memory via `UC-48376`.
* **Postconditions (Success State):**
* System records human gaze/interaction initialization flags.
* System keeps exception-based extend vectors armed (`UC-22159`, `UC-25637`, `UC-35956`).
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** presents the active ultrasound canvas with interactive, toggleable, color-coded segmentation mask overlays.
2. **System** displays the vision engine's suggested synovitis grading estimation (Grade 0, 1, 2, or 3) alongside structural pixel-percentage distribution metrics.
3. **Diagnostic Radiologist** inspects the spatial distribution of the synovial hypertrophy markers and reads the inline text panels.
4. **Diagnostic Radiologist** approves the visual data metrics without requesting alterations or triggering corrective dialogue paths.
### Alternative & Exception Flows
* **Extension Flow A: Clinician Friction / Disagreement Caught**
* At step [3], if mouse click frequencies suggest hesitation or manual adjustments cross a conflict delta threshold, the execution path triggers `UC-22159` to prevent blind override errors.
* **Extension Flow B: Expert Contests Automated Grade**
* At step [3], if the clinician explicitly changes the classification dropdown away from the ML-proposed score, the workspace extends to `UC-25637` to display the machine activation weights.
* **Extension Flow C: Anomaly / Confidence Failure Detected**
* At step [1], if the deep-learning array returned a classification confidence metric below safety bounds paired with blank knowledge base lookups, the interface branches into `UC-35956`.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC-47988
usecase "Trigger Conversational Circuit Breaker" as UC-22159
usecase "Expose Pixel-Level Activation Logic" as UC-25637
usecase "Activate Clinical Investigation Mode" as UC-35956
}
Rad --> UC-47988
UC-47988 <.. UC-22159 : <<extend>>
UC-47988 <.. UC-25637 : <<extend>>
UC-47988 <.. UC-35956 : <<extend>>
@enduml
```
---
## 3. UC-92006: Finalize & Sign Electronic Record
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Finalize & Sign Electronic Record
* Actor: Diagnostic Radiologist (Rad), Hospital EMR System (EMR)
* Goal: Authenticate, cryptographically seal, and sync verified diagnostic reports down to storage infrastructure.
* Interaction: User-to-System / System-to-System
* Stimulus: User executes the final confirmation/signature command button in the workspace utility ribbon.
* SysResponse: Generation of a signed cryptographic log block and structured JSON transmission payload delivered to the EMR endpoint.
* VerboseForm (Formula Reference View): "The use case 'Finalize & Sign Electronic Record' defines a User-to-System / System-to-System interaction where the Diagnostic Radiologist (Rad) and Hospital EMR System (EMR) aim to Authenticate, cryptographically seal, and sync verified diagnostic reports down to storage infrastructure. This workflow is triggered when User executes the final confirmation/signature command button in the workspace utility ribbon, causing the system to respond by providing Generation of a signed cryptographic log block and structured JSON transmission payload delivered to the EMR endpoint."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Finalize & Sign Electronic Record
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active scan session evaluation has been resolved, and grading metrics are verified by the human specialist.
* Local localized network channel to the hospital server framework is functional.
* **Postconditions (Success State):**
* Session record is transformed into a read-only state.
* Standardized structural JSON payload data is safely stored within the Hospital EMR System sink.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** initiates the session finalization pipeline by interacting with the cryptographic signature command trigger.
2. **System** prompts for the secure authentication credentials of the signing specialist.
3. **System** generates a unified clinical log structure, packing structural thickness measurements (mm), final validated synovitis tier scores, and accompanying multi-agent trace logs.
4. **System** calculates a secure cryptographic data hash, locking the session record into an immutable post-review profile.
5. **System** delivers the structured data package across localized network pipes to the **Hospital EMR System**.
6. **Hospital EMR System** confirms safe database commit storage updates and provides an acknowledgment packet back to the workspace.
### Alternative & Exception Flows
* **Exception Flow A: Network Pipeline Transmission Failure**
* At step [5], if network communications timeout or socket breaks occur, the workspace locks the finalized JSON package into a local encrypted offline buffer, changes the session status tag to "Pending Sync", and presents a clear connectivity warning alert.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Finalize & Sign Electronic Record" as UC-92006
}
Rad --> UC-92006
UC-92006 ..> EMR : Sync standardized structural JSON data
@enduml
```
---
# PART 2: Quadrant 1 — True Agreement Flows (AI Correct / Doctor Correct)
## 4. UC-25776: Generate GradCAM & CoT Explanation Panel
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Generate GradCAM & CoT Explanation Panel
* Actor: Diagnostic Radiologist (Rad)
* Goal: Present clear, pixel-linked visuospatial explanations and multi-modal clinical reasoning for high-trust verification.
* Interaction: User-to-System
* Stimulus: Inclusion trigger initialized during session data intake (`Load Patient Scan Session`).
* SysResponse: Renders heatmaps highlighting model focus zones alongside structured, clear reasoning steps.
* VerboseForm (Formula Reference View): "The use case 'Generate GradCAM & CoT Explanation Panel' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Present clear, pixel-linked visuospatial explanations and multi-modal clinical reasoning for high-trust verification. This workflow is triggered when Inclusion trigger initialized during session data intake (`Load Patient Scan Session`), causing the system to respond by providing Renders heatmaps highlighting model focus zones alongside structured, clear reasoning steps."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Generate GradCAM & CoT Explanation Panel
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Raw image frames and vision engine inference matrix weights have been imported via `Load Patient Scan Session`.
* **Postconditions (Success State):**
* Split-screen layout displays visual explanation elements without adding visual noise to the core image frame workspace canvas.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** evaluates the internal deep-learning model gradient parameters for the target ultrasound image slice.
2. **System** generates a visual GradCAM heatmap layer mapping feature locations that dictated model classifications (e.g., hypervascularized synovial proliferation zones).
3. **System** maps multi-modal prompt metrics through the internal LLM Explainer module to produce a concise, point-by-point clinical reasoning string.
4. **System** populates the split-screen workspace sub-section block with this explanation data to guide human inspection efficiently.
5. **System** includes `UC-02423` to serialize verification metadata.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Generate GradCAM & CoT Explanation Panel" as UC_Core
usecase "Log High-Trust Concur Block" as UC_Sub
}
Rad --> UC_Core
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 5. UC-02423: Log High-Trust Concur Block
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Log High-Trust Concur Block
* Actor: Hospital EMR System (EMR)
* Goal: Secure the human-AI alignment log trace within the final diagnostic report payload.
* Interaction: System-to-System
* Stimulus: Explanatory panel validation completes successfully without user override actions.
* SysResponse: Appends a tamper-evident audit trace block verifying explicit human-AI agreement into the session log cache.
* VerboseForm (Formula Reference View): "The use case 'Log High-Trust Concur Block' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Secure the human-AI alignment log trace within the final diagnostic report payload. This workflow is triggered when Explanatory panel validation completes successfully without user override actions, causing the system to respond by providing Appends a tamper-evident audit trace block verifying explicit human-AI agreement into the session log cache."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Log High-Trust Concur Block
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Multi-modal explanations were fully generated (`UC-25776`) and passed without human alteration marks.
* **Postconditions (Success State):**
* Explicit audit string trace tracking high-trust convergence is formatted for downstream pipeline compilation.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** detects a direct consensus condition where the human expert confirms the model data without text/grading edits.
2. **System** serializes the multi-modal text breakdown and pixel attribution coordinates into an immutable log string block.
3. **System** assigns an explicit alignment token header flag (`HIGH_TRUST_CONCURRENCE`).
4. **System** caches this specialized tracking trace within the localized session state data, making it ready to be appended during final data hand-off routines (`UC-92006`).
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Log High-Trust Concur Block" as UC-02423
}
UC-02423 ..> EMR : (Prepares payload for final sync)
@enduml
```
---
# PART 3: Quadrant 2 — Automation Override Risk Loops (AI Correct / Doctor Oversight)
## 6. UC-22159: Trigger Conversational Circuit Breaker
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Trigger Conversational Circuit Breaker
* Actor: Diagnostic Radiologist (Rad)
* Goal: Intercept premature finalization workflows if interface telemetry reveals friction, hesitation, or cognitive blind-spots.
* Interaction: User-to-System
* Stimulus: Extended extension trace caught during review steps if user behavior markers diverge from smooth consensus paths.
* SysResponse: Halts default workspace finalization routes and shifts the UI into a mandatory safety evaluation mode.
* VerboseForm (Formula Reference View): "The use case 'Trigger Conversational Circuit Breaker' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Intercept premature finalization workflows if interface telemetry reveals friction, hesitation, or cognitive blind-spots. This workflow is triggered when Extended extension trace caught during review steps if user behavior markers diverge from smooth consensus paths, causing the system to respond by providing Halts default workspace finalization routes and shifts the UI into a mandatory safety evaluation mode."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Trigger Conversational Circuit Breaker
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active session is inside the `UC-47988` workflow phase.
* UI layer telemetry captures specific friction indicators (e.g., high-frequency cursor oscillation, repeatedly typing and deleting text, or conflicting grading inputs).
* **Postconditions (Success State):**
* Direct finalization path is securely locked down.
* System-forced conversational validation interface is deployed into view.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** evaluates live workspace telemetry tracking patterns during active case validation.
2. **System** detects user behavior triggers signaling high diagnostic friction or potential automatic oversight trends.
3. **System** blocks the immediate execution availability of the standard finalization command sequence (`UC-92006`).
4. **System** transforms workspace panel focus areas to present an interactive confirmation overlay.
5. **System** executes `UC-55146` to initialize direct safety check communications.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC-47988
usecase "Trigger Conversational Circuit Breaker" as UC_Core
usecase "Facilitate Socratic Reasoning Dialogue" as UC_Sub
}
Rad --> UC-47988
UC-47988 <.. UC_Core : <<extend>> (If clinician friction detected)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 7. UC-55146: Facilitate Socratic Reasoning Dialogue
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Facilitate Socratic Reasoning Dialogue
* Actor: Diagnostic Radiologist (Rad)
* Goal: Engage the specialist in a targeted, conversational double-check loop regarding controversial structural markers.
* Interaction: User-to-System
* Stimulus: Core execution request passed down by the active circuit breaker module (`UC-22159`).
* SysResponse: Interactive conversational sub-panel displaying focused prompt choices that check specific diagnostic criteria.
* VerboseForm (Formula Reference View): "The use case 'Facilitate Socratic Reasoning Dialogue' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Engage the specialist in a targeted, conversational double-check loop regarding controversial structural markers. This workflow is triggered when Core execution request passed down by the active circuit breaker module (`UC-22159`), causing the system to respond by providing Interactive conversational sub-panel displaying focused prompt choices that check specific diagnostic criteria."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Facilitate Socratic Reasoning Dialogue
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Circuit breaker safety intercept sequence has completed successfully, freezing generic CRUD paths.
* **Postconditions (Success State):**
* User inputs conversational defense arguments or confirms specific anatomical findings.
* Live conversation data tokens are actively streamed to automated safety monitors.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** initializes a conversational chat element right next to the ultrasound display field.
2. **System** presents a non-confrontational, clinically grounded question regarding the identified discrepancies (e.g., *"Note the echo-free thickening layer in the suprapatellar recess; please confirm if this modification represents minor effusion or structural pannus tissue"*).
3. **Diagnostic Radiologist** enters text responses or selects structural tag tokens to clarify their assessment.
4. **System** includes `UC-74821` in real time to process active conversation token patterns.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Facilitate Socratic Reasoning Dialogue" as UC_Core
usecase "Monitor Drift via BERT Sub-Layer" as UC_Sub
}
Rad --> UC_Core : Argue observations
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 8. UC-74821: Monitor Drift via BERT Sub-Layer
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Monitor Drift via BERT Sub-Layer
* Actor: Diagnostic Radiologist (Rad)
* Goal: Continuously parse communication tokens to identify logical contradictions or semantic drift during clinical debates.
* Interaction: User-to-System
* Stimulus: Streamed entry of communication tokens within the active dialogue loop.
* SysResponse: Real-time semantic checking flags; extends out to the RAG referee if an impasse or severe drift is captured.
* VerboseForm (Formula Reference View): "The use case 'Monitor Drift via BERT Sub-Layer' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Continuously parse communication tokens to identify logical contradictions or semantic drift during clinical debates. This workflow is triggered when Streamed entry of communication tokens within the active dialogue loop, causing the system to respond by providing Real-time semantic checking flags; extends out to the RAG referee if an impasse or severe drift is captured."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Monitor Drift via BERT Sub-Layer
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active conversational dialogue module is processing user data strings (`UC-55146`).
* **Postconditions (Success State):**
* Log structures capture semantic alignment metrics.
* System successfully catches contradictions before data parameters flow to final storage.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** continuously intercepts conversation tokens as the human expert types input strings.
2. **System** runs token matrices through an embedded BERT checking model to calculate contextual semantic coherence scores.
3. **System** verifies that user claims line up logically with the visual indicators under review.
4. **System** approves the validated conversational step, allowing the specialist to complete the confirmation cycle smoothly.
### Alternative & Exception Flows
* **Extension Flow A: Impasse or Semantic Contradiction Detected**
* At step [3], if the specialist's input text contradicts objective structural metrics (e.g., claiming a region is "completely normal" while the visual layer registers massive synovial proliferation) or exhibits context drift, the process branches into `UC-65473` to request evidence evaluation.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Monitor Drift via BERT Sub-Layer" as UC_Core
usecase "Arbitrate Evidence via RAG-Referee" as UC_Ext
}
Rad --> UC_Core
UC_Core <.. UC_Ext : <<extend>> (If impasse or semantic drift caught)
@enduml
```
---
## 9. UC-65473: Arbitrate Evidence via RAG-Referee
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Arbitrate Evidence via RAG-Referee
* Actor: Diagnostic Radiologist (Rad)
* Goal: Query static, authoritative clinical knowledge bases to resolve human-machine disagreements with objective evidence.
* Interaction: User-to-System
* Stimulus: Triggered when communication tracking scores cross a severe semantic mismatch or impasse threshold.
* SysResponse: Inline injection of un-biased diagnostic text extracts and guidelines matching the active frame conditions.
* VerboseForm (Formula Reference View): "The use case 'Arbitrate Evidence via RAG-Referee' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Query static, authoritative clinical knowledge bases to resolve human-machine disagreements with objective evidence. This workflow is triggered when Triggered when communication tracking scores cross a severe semantic mismatch or impasse threshold, causing the system to respond by providing Inline injection of un-biased diagnostic text extracts and guidelines matching the active frame conditions."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Arbitrate Evidence via RAG-Referee
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* BERT analytics layers detect a diagnostic impasse or significant semantic drift.
* Authoritative local clinical knowledge base index (e.g., OMERACT synovitis grading reference manuals) is online and responsive.
* **Postconditions (Success State):**
* Disagreement matrix is resolved via verified medical data injection.
* Final chosen path is linked directly to a standard medical guideline anchor.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** halts active conversational dialogue inputs temporarily to execute a localized context search.
2. **System** extracts spatial measurements and text tokens to construct a specialized RAG search string.
3. **System** queries local, validated medical knowledge data banks to locate matching diagnostic criteria sections.
4. **System** displays the verified guideline text extract right inside the workspace alert view block (e.g., *"OMERACT standardizes Grade 2 as hypoechoic synovial hypertrophy demonstrating fluid-filled distension up to structural boundary bounds"*).
5. **Diagnostic Radiologist** reviews the authoritative reference framework and either adjusts their classification choice or submits a structured expert override justifying their deviation.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Arbitrate Evidence via RAG-Referee" as UC_Core
}
Rad --> UC_Core
@enduml
```
---
# PART 4: Quadrant 3 — Clinician Subservience Risk Loops (AI Hallucinates / Doctor Correct)
## 10. UC-25637: Expose Pixel-Level Activation Logic
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Expose Pixel-Level Activation Logic
* Actor: Diagnostic Radiologist (Rad)
* Goal: Reveal fine-grained layer weights and activation responses when the human specialist challenges an automated grade prediction.
* Interaction: User-to-System
* Stimulus: Clinician manually alters or rejects the ML-proposed classification score in the review pane.
* SysResponse: Interactive visual mapping showing the exact high-frequency noise regions driving model prediction errors.
* VerboseForm (Formula Reference View): "The use case 'Expose Pixel-Level Activation Logic' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Reveal fine-grained layer weights and activation responses when the human specialist challenges an automated grade prediction. This workflow is triggered when Clinician manually alters or rejects the ML-proposed classification score in the review pane, causing the system to respond by providing Interactive visual mapping showing the exact high-frequency noise regions driving model prediction errors."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Expose Pixel-Level Activation Logic
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active session is inside the `UC-47988` interface phase.
* Specialist chooses an option that breaks clean model agreement paths.
* **Postconditions (Success State):**
* Internal neural layer weight vectors are visually mapped onto the primary medical viewport.
* Core manual artifact isolation tool sets become active on the canvas layout.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** changes the system-suggested grade classification dropdown setting.
2. **System** captures the modification step and branches away from the standard review pathway to reveal underlying model mechanics.
3. **System** transforms image layers to display fine-grained activation weights, revealing exactly which pixel clusters (e.g., acoustic shadowing regions or bone interfaces) skewed the model's calculation.
4. **System** includes `UC-60739` to let the specialist manually clean up the noise zones.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC-47988
usecase "Expose Pixel-Level Activation Logic" as UC_Core
usecase "Isolate Visual Noise/Artifacts" as UC_Sub
}
Rad --> UC-47988
UC-47988 <.. UC_Core : <<extend>> (If clinician contests AI score)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 11. UC-60739: Isolate Visual Noise/Artifacts
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Isolate Visual Noise/Artifacts
* Actor: Diagnostic Radiologist (Rad)
* Goal: Provide manual brush and selection overlays to mask out acoustic shadows, bone scattering, or artifacts causing model calculation errors.
* Interaction: User-to-System
* Stimulus: Human operator activates canvas cleanup tools within the exposed model layer layout.
* SysResponse: Real-time visual updates to the pixel mask array, isolating clean anatomical structures from surrounding imaging noise.
* VerboseForm (Formula Reference View): "The use case 'Isolate Visual Noise/Artifacts' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Provide manual brush and selection overlays to mask out acoustic shadows, bone scattering, or artifacts causing model calculation errors. This workflow is triggered when Human operator activates canvas cleanup tools within the exposed model layer layout, causing the system to respond by providing Real-time visual updates to the pixel mask array, isolating clean anatomical structures from surrounding imaging noise."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Isolate Visual Noise/Artifacts
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System exposure arrays are visible across the image viewport layout (`UC-25637`).
* **Postconditions (Success State):**
* Corrected ground-truth frame masks are calculated and locked into memory.
* System updates local diagnostic metrics using the isolated anatomical data.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** activates a manual canvas tool overlay, giving the user access to high-precision brush, eraser, and selection vectors.
2. **Diagnostic Radiologist** applies brush vectors directly over areas containing acoustic artifacts or non-synovial structures that skewed the automated classification score.
3. **System** recalculates active region dimensions in real time, excluding the masked pixels from the active grading parameters.
4. **System** updates diagnostic panel displays to confirm the human-corrected measurements.
5. **System** includes `UC-62864` to lock the updated session state securely.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Isolate Visual Noise/Artifacts" as UC_Core
usecase "Commit Validated Ground-Truth Record" as UC_Sub
}
Rad --> UC_Core : Tag artifacts
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 12. UC-62864: Commit Validated Ground-Truth Record
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Commit Validated Ground-Truth Record
* Actor: Hospital EMR System (EMR)
* Goal: Secure the human-corrected ground-truth dataset variant while appending clean, expert-validated report payloads to the EMR.
* Interaction: System-to-System
* Stimulus: Completion of manual artifact masking operations and confirmation of corrected metrics.
* SysResponse: Stores the corrected medical report in the EMR and saves the isolated image mask to an optimization cache for subsequent retraining.
* VerboseForm (Formula Reference View): "The use case 'Commit Validated Ground-Truth Record' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Secure the human-corrected ground-truth dataset variant while appending clean, expert-validated report payloads to the EMR. This workflow is triggered when Completion of manual artifact masking operations and confirmation of corrected metrics, causing the system to respond by providing Stores the corrected medical report in the EMR and saves the isolated image mask to an optimization cache for subsequent retraining."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Commit Validated Ground-Truth Record
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Human-directed canvas modification steps are locked in place without remaining pixel parity errors (`UC-60739`).
* **Postconditions (Success State):**
* EMR database updates receive the human expert's diagnostic findings.
* Isolated ground-truth tensor pairs are safely cached for AI training refinement runs.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** packages the human expert's corrected diagnostic data metrics into the primary transmission bundle.
2. **System** isolates the human-brushed image mask layers alongside the initial incorrect model classification output.
3. **System** tags the data pair as a validated retraining asset (`GROUND_TRUTH_OVERRIDE`).
4. **System** saves the optimization asset to a secure local retraining storage folder, while preparing the primary medical report for delivery to the **Hospital EMR System**.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Commit Validated Ground-Truth Record" as UC_Core
}
UC_Core ..> EMR : (Prepares clean report for EMR sync)
@enduml
```
---
# PART 5: Quadrant 4 — Double Blind Failure Loops (AI Faulty / Doctor Biased)
## 13. UC-35956: Activate Clinical Investigation Mode
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Activate Clinical Investigation Mode
* Actor: Diagnostic Radiologist (Rad)
* Goal: Switch the system into a strict, template-driven manual examination mode when low vision confidence values align with a lack of reference data.
* Interaction: User-to-System
* Stimulus: The workspace detects a critical double-blind failure criteria match during the case evaluation phase.
* SysResponse: Disables automated diagnostic suggestions entirely and forces a standardized manual morphology review.
* VerboseForm (Formula Reference View): "The use case 'Activate Clinical Investigation Mode' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Switch the system into a strict, template-driven manual examination mode when low vision confidence values align with a lack of reference data. This workflow is triggered when The workspace detects a critical double-blind failure criteria match during the case evaluation phase, causing the system to respond by providing Disables automated diagnostic suggestions entirely and forces a standardized manual morphology review."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Activate Clinical Investigation Mode
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System classification loops return low-confidence indices.
* Authoritative RAG reference lookups return no matches, indicating an unmapped anatomical variant or a severe image anomaly.
* **Postconditions (Success State):**
* Automated suggestions are masked out to prevent cognitive bias.
* Mandatory manual template verification frameworks are deployed into active workspace view.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** monitors deep-learning inference score bounds during case evaluation.
2. **System** runs background reference data lookups and catches a dual failure state (Low confidence + Empty knowledge reference).
3. **System** drops the standard review interface layout to prevent automated suggestion bias or human misinterpretation loops.
4. **System** changes UI display focus markers to activate an explicit, template-driven investigation layout.
5. **System** includes `UC-47796` to force manual measurement entries.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC-47988
usecase "Activate Clinical Investigation Mode" as UC_Core
usecase "Execute Structured Morphology Annotation" as UC_Sub
}
Rad --> UC-47988
UC-47988 <.. UC_Core : <<extend>> (If low confidence & empty RAG)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 14. UC-47796: Execute Structured Morphology Annotation
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Execute Structured Morphology Annotation
* Actor: Diagnostic Radiologist (Rad)
* Goal: Force the manual plotting of anatomical coordinates and morphological anomalies using a strict, un-biased framework.
* Interaction: User-to-System
* Stimulus: The workspace forces a manual review layout via the active escalation workflow step.
* SysResponse: Interactive coordinate plotting arrays and mandatory clinical documentation input boxes.
* VerboseForm (Formula Reference View): "The use case 'Execute Structured Morphology Annotation' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Force the manual plotting of anatomical coordinates and morphological anomalies using a strict, un-biased framework. This workflow is triggered when The workspace forces a manual review layout via the active escalation workflow step, causing the system to respond by providing Interactive coordinate plotting arrays and mandatory clinical documentation input boxes."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Execute Structured Morphology Annotation
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System UI layer has transitioned to manual investigation mode parameters (`UC-35956`).
* **Postconditions (Success State):**
* Specialist successfully plots manual structural bounds.
* Text verification parameters capture explicit clinical observations.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** displays an empty, un-biased ultrasound canvas frame alongside a series of mandatory measurement fields.
2. **Diagnostic Radiologist** plots coordinate points across the canvas layer to outline the boundaries of the anomalous tissue.
3. **Diagnostic Radiologist** manually populates text fields describing structural observations (e.g., bone fragments or atypical lesion shapes).
4. **System** compiles these manual coordinates and comments into a detailed case record.
5. **System** includes `UC-01580` to route the data directly to optimization pipelines.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Execute Structured Morphology Annotation" as UC_Core
usecase "Serialize Session to Telemetry Queue" as UC_Sub
}
Rad --> UC_Core : Document manual findings
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 15. UC-01580: Serialize Session to Telemetry Queue
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Serialize Session to Telemetry Queue
* Actor: Hospital EMR System (EMR)
* Goal: Route anomalous case data directly to engineering telemetry streams while bypassing standard hospital records to protect clinical data pipes.
* Interaction: System-to-System
* Stimulus: Completion of manual morphology reporting arrays within the clinical investigation interface.
* SysResponse: Packages unencrypted image tensors, coordinate arrays, and user text blocks directly into core product telemetry queues.
* VerboseForm (Formula Reference View): "The use case 'Serialize Session to Telemetry Queue' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Route anomalous case data directly to engineering telemetry streams while bypassing standard hospital records to protect clinical data pipes. This workflow is triggered when Completion of manual morphology reporting arrays within the clinical investigation interface, causing the system to respond by providing Packages unencrypted image tensors, coordinate arrays, and user text blocks directly into core product telemetry queues."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Serialize Session to Telemetry Queue
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Manual morphology plotting and clinical documentation inputs are finalized (`UC-47796`).
* **Postconditions (Success State):**
* Case files containing structural anomalies bypass standard EMR storage pathways.
* Raw image tensors are queued in engineering streams to expand future model capabilities.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** identifies the active session as an anomalous anomaly case during final compilation.
2. **System** aggregates raw frame tensors, manual coordinate indices, and user-entered clinical commentary blocks into a secure telemetry archive package.
3. **System** bypasses standard EMR production database pipelines to protect standard hospital operational data.
4. **System** routes the telemetry package directly to the product engineering data pipeline for system optimization and future model training runs.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Serialize Session to Telemetry Queue" as UC_Core
}
UC_Core ..> EMR : (Bypasses standard production EMR sync)
@enduml
```
---

59
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/Q1 True Agreement (AI Correct Doctor Correct) 378f910aea758007a841f20e57da0f0d.md Normal file
View File

@@ -0,0 +1,59 @@
# Q1: True Agreement
(AI Correct / Doctor Correct)
Layered Three-Tier ML Stack Performance Impact (Your Proposed Design): Explainable Baseline Sync: The VKIST Grader computes the numerical matrices & the GradCAM. The LLM Explainer parses the raw segmentation parameters + GradCAM and automatically generates an interactive diagnostic draft chat panel & LLM based on the GradCAM + RAG-knowledge + the raw-ultrasound to explain the VKIST-grader. The RAG-Referee confirms zero clinical guidelines variance, and logs a high-trust concur structural block. <note both LLM have to record back the Chain-of-Though for explain why the LLM’s agree & allow the result)
```jsx
@startuml
' Settings
left to right direction
skin rose
' Actors
actor "Diagnostic Radiologist (UP5)" as Rad
actor "Hospital EMR System" as EMR << System >>
' System Boundary
rectangle "VKIST MSK Workspace - Q1: True Agreement Flow" {
usecase "Ingest Diagnostic Ultrasound" as UC-48376
rectangle "Pipeline: Vision & Reasoning" {
usecase "Compute Matrices & GradCAM (VKIST Grader)" as UC_Vision
usecase "Parse Features & Draft Explanation (LLM Explainer)" as UC_Explain
usecase "Log Chain-of-Thought (CoT)" as UC_CoT
}
rectangle "Audit: RAG-Referee" {
usecase "Verify Clinical Guideline Alignment" as UC_Referee
usecase "Cache Concurrence Structural Block" as UC_Log
}
rectangle "Clinical Finalization" {
usecase "Review & Confirm Diagnosis" as UC-47988
usecase "Sign & Commit Record" as UC-92006
}
usecase "Synchronize EMR Ledger" as UC_Sync
}
' Interaction Paths
Rad --> UC-48376
UC-48376 ..> UC_Vision : <<include>>
UC_Vision --> UC_Explain : Provide Tensors & GradCAM
UC_Explain ..> UC_CoT : <<include>> (Persist Reasoning Path)
' Independent Verification Gate
UC_Explain ..> UC_Referee : <<include>>
UC_Referee ..> UC_Log : <<include>> (High-Trust Block)
' Final User Confirmation
Rad --> UC-47988
UC_Log --> UC-47988 : Show "High-Trust Concurrence"
Rad --> UC-92006
UC-92006 ..> UC_Sync : <<include>>
UC_Sync --> EMR : POST Validated JSON Record
@enduml
```
![image.png](Q1%20True%20Agreement%20(AI%20Correct%20Doctor%20Correct)/image.png)

67
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/Q2 Automation Override Risk (AI Correct Doctor Ove 378f910aea75808cb7e5eda9f0b0b89c.md Normal file
View File

@@ -0,0 +1,67 @@
# Q2: Automation Override Risk
(AI Correct / Doctor Oversights / Confuse)
Layered Three-Tier ML Stack Performance Impact (Your Proposed Design): The Conversational Circuit Breaker triggers when a clinician disagrees / confuse / uncertain with the system's diagnostic grade, halting the workflow to launch an interactive Socratic dialogue that bridges the gap between human intuition and machine inference. In this mode, the system (LLM-explainer) shall synthesize raw VKIST-ML vision tensors, GradCAM activation heatmaps, and evidence retrieved via RAG into a collaborative analysis session, forcing the clinician to articulate their reasoning against the machine's spatial and vascular observations. To ensure diagnostic integrity, a BERT-based hallucination detector continuously monitors the chat for semantic drift or illogical premises; if the conversation reaches an impasse or the system detects potential contextual hallucination, the RAG-Referee intervenes as an unbiased arbiter. This referee bypasses the conversational history to provide definitive, evidence-based source material from clinical guidelines (such as ESSR) directly tied to the raw imaging metrics, resolving the ambiguity through objective, verifiable medical evidence rather than subjective negotiation.
```jsx
@startuml
skinparam linetype polyline
skinparam packageStyle rectangle
skinparam rectangle {
BackgroundColor #fefefe
BorderColor #555555
}
' Actors
actor "Radiologist (UP5)" as Rad
actor "Internal Consultor (LLM Chat)" as Cons <<System>>
actor "Hospital EMR" as EMR <<System>>
rectangle "VKIST MSK Workspace - Q2 Architecture" {
usecase "Trigger Circuit Breaker Panel" as UC2_Trigger
rectangle "Socratic Workspace UI Panel" {
usecase "Lock Main Diagnostic Flow" as UC2_Halt
usecase "Engage in Socratic Discussion" as UC2_Socratic
usecase "Display Visual GradCAM Overlay" as UC2_Synth
}
rectangle "Verification & Arbitration Kernel" {
usecase "Audit Chat Token Drift (BERT)" as UC2_BERT
usecase "Execute RAG-Referee Check" as UC2_Referee
usecase "Query Immutable Guideline Base" as UC2_RAG_Fetch
}
rectangle "Clinical Resolution Gate" {
usecase "Review Referee Verdict Card" as UC2_Review
usecase "Commit Signed Diagnosis" as UC2_Finalize
}
usecase "EMR Ledger Sync" as UC2_Sync
}
' Core Interaction Flow
Rad --> UC2_Trigger : Disagreement/Uncertainty
UC2_Trigger ..> UC2_Halt : <<include>>
UC2_Halt ..> UC2_Synth : <<include>>
' Dynamic Chat Loop between Doctor and Internal Consultor LLM
Rad --> UC2_Socratic
Cons --> UC2_Socratic : Drive Pathologic Inquiry Dialogue
' Asynchronous Automated Verification Channel
UC2_Socratic ..> UC2_BERT : Stream Conversation Tokens
UC2_BERT ..> UC2_Referee : <<extend>> (Triggered on Impasse / Chat Hallucination)
UC2_Referee ..> UC2_RAG_Fetch : <<include>>
UC2_RAG_Fetch ..> UC2_Review : Inject Ground-Truth Evidence
' Finalization Steps
Rad --> UC2_Review
Rad --> UC2_Finalize
UC2_Finalize ..> UC2_Sync : <<include>>
UC2_Sync --> EMR : POST Validated JSON Payload
@enduml
```
![image.png](Q2%20Automation%20Override%20Risk%20(AI%20Correct%20Doctor%20Ove/image.png)

69
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/Q3 Clinician Subservience Risk (AI Hallucinates Do 378f910aea7580f8afb1c708eaf53e15.md Normal file
View File

@@ -0,0 +1,69 @@
# Q3: Clinician Subservience Risk
(AI Hallucinates / Doctor Correct)
Layered Three-Tier ML Stack Performance Impact (Your Proposed Design): The Objective Critic Loop initiates when a clinician contests an automated diagnostic grade, triggering an interactive Socratic consultation that bridges human intuition with machine inference via the VKIST-ML vision stack. During this loop, the LLM Explainer renders a GradCAM-anchored reasoning draft that visualizes the specific pixel-level feature activation logic, enabling the clinician to identify and isolate artifacts—such as motion tremors—that may have induced a system hallucination. To ensure diagnostic integrity, a BERT-based detector continuously monitors the dialogue for semantic drift, and if the interaction reaches an impasse or context hallucination is detected, the RAG-Referee intervenes as an unbiased, independent arbiter. By cross-verifying the clinician’s assertion and the model’s reasoning against raw imaging tensors and immutable, source-cited clinical guidelines (e.g., ESSR/OMERACT standards), the Referee resolves diagnostic ambiguity with objective evidence, ultimately committing the validated session as an annotated ground-truth record for targeted system reinforcement.
```jsx
@startuml
' Layout optimizations to secure compact rendering and prevent image fragmentation
skinparam linetype polyline
skinparam packageStyle rectangle
skinparam rectangle {
BackgroundColor #fefefe
BorderColor #555555
}
' Actors strictly mapped to match your canonical architectural definitions
actor "Radiologist (UP5)" as Rad
actor "Internal Consultor (LLM Chat)" as Cons <<System>>
actor "System Maintainer" as Maint <<System>>
rectangle "VKIST MSK Workspace - Q4 Architecture" {
usecase "Evaluate Epistemic Uncertainty Gate" as UC4_Trigger
rectangle "Socratic Workspace UI Panel" {
usecase "Shift to Clinical Investigation Mode" as UC4_Halt
usecase "Engage in Socratic Discussion" as UC4_Socratic
usecase "Render Manual Checklist Canvas" as UC4_Synth
}
rectangle "Verification & Arbitration Kernel" {
usecase "Audit Chat Token Drift (BERT)" as UC4_BERT
usecase "Execute RAG-Referee Check" as UC4_Referee
usecase "Return Null-Match Signal" as UC4_RAG_Fetch
}
rectangle "Clinical Resolution Gate" {
usecase "Document Novel Morphological Features" as UC4_Review
usecase "Authorize Serialized Anomaly Package" as UC4_Finalize
}
usecase "Asynchronous Telemetry Queue Sync" as UC4_Sync
}
' Initial Data Intake and Uncertainty Routing Paths
Rad --> UC4_Trigger : Feed OOD Image Tensors
UC4_Trigger ..> UC4_RAG_Fetch : <<include>> (Triggers Empty Vector Result)
UC4_RAG_Fetch ..> UC4_Halt : <<extend>> (On Zero-Match Guidelines + Low Conf Tensors)
UC4_Halt ..> UC4_Synth : <<include>>
' Direct Socratic Analysis Run-time Workspace
Rad --> UC4_Socratic
Cons --> UC4_Socratic : Drive Exploratory Morphology Dialogue
' Live Guardrail and Exception Evaluation Paths
UC4_Socratic ..> UC4_BERT : Stream Conversation Tokens
UC4_BERT ..> UC4_Referee : <<include>> (Validates Logical Framing Stability)
' Manual Audit, Documenting Anomaly and Consent Finalization
Rad --> UC4_Review : Acknowledge Guideline Limitation
Rad --> UC4_Finalize : Provide Native Opt-In Telemetry Consent
' Async Data Serialization Sink to System Maintainer Ledger
UC4_Finalize ..> UC4_Sync : <<include>>
UC4_Sync --> Maint : POST Encrypted Tensors & Logs for Model Retraining
@enduml
```
![image.png](Q3%20Clinician%20Subservience%20Risk%20(AI%20Hallucinates%20Do/image.png)

69
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/Q4 Double Blind Failure dues to edge-case (AI Faul 378f910aea7580618972f1583ab0e96b.md Normal file
View File

@@ -0,0 +1,69 @@
# Q4: Double Blind Failure dues to edge-case
(AI Faulty / Doctor Biased)
Layered Three-Tier ML Stack Performance Impact (Your Proposed Design): Anomaly Escalation Protocol: In instances where both the diagnostic system and the clinician encounter an edge-case—or "unknown-unknown"—that lacks precedent in the current RAG knowledge base, the system initiates the Anomaly Escalation Protocol. The LLM Explainer detects this "epistemic uncertainty" (via low vision-stack confidence and empty RAG retrieval results) and shifts the interface from "Diagnostic Support" to "Clinical Investigation Mode." Instead of attempting to force a Grade-based diagnosis, the Internal Consultor guides the clinician to document the unique morphological features through a structured annotation protocol, facilitating a Socratic investigation into the anomaly. The system transparently acknowledges the limitation, explicitly stating that current clinical guidelines do not cover this specific presentation, and prompts the clinician to manually document findings. With the clinician’s consent, the workspace commits this session as a "Novel Research Case," automatically serializing the raw imaging tensors, clinician observations, and artifact logs to a secure telemetry queue, flagging the data for system maintainers to perform targeted model retraining and protocol refinement.
```jsx
@startuml
' Layout optimizations to secure compact rendering and prevent image fragmentation
skinparam linetype polyline
skinparam packageStyle rectangle
skinparam rectangle {
BackgroundColor #fefefe
BorderColor #555555
}
' Actors strictly mapped to match your canonical architectural definitions
actor "Radiologist (UP5)" as Rad
actor "Internal Consultor (LLM Chat)" as Cons <<System>>
actor "System Maintainer" as Maint <<System>>
rectangle "VKIST MSK Workspace - Q4 Architecture" {
usecase "Evaluate Epistemic Uncertainty Gate" as UC4_Trigger
rectangle "Socratic Workspace UI Panel" {
usecase "Shift to Clinical Investigation Mode" as UC4_Halt
usecase "Engage in Socratic Discussion" as UC4_Socratic
usecase "Render Manual Checklist Canvas" as UC4_Synth
}
rectangle "Verification & Arbitration Kernel" {
usecase "Audit Chat Token Drift (BERT)" as UC4_BERT
usecase "Execute RAG-Referee Check" as UC4_Referee
usecase "Return Null-Match Signal" as UC4_RAG_Fetch
}
rectangle "Clinical Resolution Gate" {
usecase "Document Novel Morphological Features" as UC4_Review
usecase "Authorize Serialized Anomaly Package" as UC4_Finalize
}
usecase "Asynchronous Telemetry Queue Sync" as UC4_Sync
}
' Initial Data Intake and Uncertainty Routing Paths
Rad --> UC4_Trigger : Feed OOD Image Tensors
UC4_Trigger ..> UC4_RAG_Fetch : <<include>> (Triggers Empty Vector Result)
UC4_RAG_Fetch ..> UC4_Halt : <<extend>> (On Zero-Match Guidelines + Low Conf Tensors)
UC4_Halt ..> UC4_Synth : <<include>>
' Direct Socratic Analysis Run-time Workspace
Rad --> UC4_Socratic
Cons --> UC4_Socratic : Drive Exploratory Morphology Dialogue
' Live Guardrail and Exception Evaluation Paths
UC4_Socratic ..> UC4_BERT : Stream Conversation Tokens
UC4_BERT ..> UC4_Referee : <<include>> (Validates Logical Framing Stability)
' Manual Audit, Documenting Anomaly and Consent Finalization
Rad --> UC4_Review : Acknowledge Guideline Limitation
Rad --> UC4_Finalize : Provide Native Opt-In Telemetry Consent
' Async Data Serialization Sink to System Maintainer Ledger
UC4_Finalize ..> UC4_Sync : <<include>>
UC4_Sync --> Maint : POST Encrypted Tensors & Logs for Model Retraining
@enduml
```
![image.png](Q4%20Double%20Blind%20Failure%20dues%20to%20edge-case%20(AI%20Faul/image.png)

282
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/UC_CONTEXT.md Normal file
View File

@@ -0,0 +1,282 @@
# CONTEXT.md for the Usecase Discovery : FR-25
- The requirement: FR-25 == ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)
- Explain why the se should care on this usecase in the design process
- **The Gap:** Lợi ích kỹ thuật & Giá trị cốt lõi của Use Case Phân cấp Viêm màng hoạt dịch đối với Kiến trúc Phần mềm (Missing Clinical rationale vs. Engineering value optimization for Synovitis Grading).
- **The Question:** Tại sao quy trình lâm sàng chuẩn hóa này lại đảm bảo tính chính xác khi phân cấp (`Synovitis Grading`) và tại sao một Kỹ sư Phần mềm (SE) phải đặc biệt quan tâm đến Use Case này khi thiết kế sản phẩm?
- **The Hint:** Để xây dựng một sản phẩm Y tế (Healthcare AI Product) thành công, chúng ta không được coi Use Case này chỉ là một tính năng CRUD hay hiển thị ảnh đơn thuần. Hiểu rõ bản chất toán học/vật lý của quy trình giúp SE thiết kế cơ chế lưu trữ dữ liệu (Data Schema), cấu hình Pipeline xử lý ảnh AI và tối ưu hóa trải nghiệm UIX không bị lỗi logic giải phẫu.
- **The Recommendations:** Dưới đây là câu trả lời phân tích sâu dưới góc nhìn của một Kỹ sư Hệ thống / Lập trình viên:
### PHẦN 1: Tại sao quy trình này đảm bảo việc phát hiện và phân cấp chính xác? (Góc nhìn Data Pipeline & Signal Processing)
Nếu coi cơ thể người là một hệ thống phần cứng và máy siêu âm là một module quét dữ liệu ngoại vi (Hardware Scanner), quy trình 6 bước lâm sàng chính là các điều kiện tiền đề để **đảm bảo tính toàn vẹn của tín hiệu (Signal Integrity)** và ngăn chặn **nhiễu dữ liệu (Data Corruption)**:
1. **Khử nhiễu biên (Eliminating Boundary Noise - Bước 1):** việc gập đầu gối 20°–30° tương đương với việc thực hiện lệnh `Format / Standardize` bề mặt quét. Nó triệt tiêu hiện tượng *Bất đẳng hướng âm học (Acoustic Anisotropy)* – vốn là một dạng nhiễu tín hiệu vật lý khiến mô khỏe mạnh bị biến đổi thành các pixel đen giả lập tổn thương.
2. **Cố định Hệ tọa độ (Fixing Coordinate System - Bước 2):** Đặt đầu dò dọc (`Longitudinal`) giúp mô hình AI thu được một contract dữ liệu ảnh tĩnh có cấu trúc giải phẫu phân tầng rõ ràng (`Multi-layered Frame`). Đỉnh xương bánh chè hoạt động như một điểm mốc $X, Y = (0,0)$ cố định để hệ thống chạy Edge Detection chuẩn xác.
3. **Phân tích Đa luồng song song (Multi-threading Analytics - Bước 3 & 4):**
- **Luồng B-Mode (Cấu trúc Hình học):** Trích xuất độ dày mô (`float thickness_mm`) $\rightarrow$ Phản ánh dung lượng thiệt hại vật lý tĩnh (Structural Damage).
- **Luồng Power Doppler (Lưu lượng Biến động):** Trích xuất mật độ màu của dòng máu (`float vascular_percentage`) $\rightarrow$ Phản ánh lưu lượng dữ liệu thời gian thực đang chạy (Active Inflammation).
4. **Tránh lỗi nén hệ thống (Avoiding Signal Throttling):** Việc lướt nhẹ tay đầu dò (minimal pressure) giữ cho luồng truyền dẫn tín hiệu mạch máu không bị bóp nghẹt (Throttling), tránh việc hệ thống tính toán sai lệch điểm số hoạt tử/viêm mạch dẫn đến kết quả âm tính giả.
### PHẦN 2: Tại sao Kỹ sư Phần mềm (SE) phải đặc biệt quan tâm đến Use Case này?
Từ góc nhìn sản phẩm và kiến trúc hệ thống của dự án `VKIST_ULTRASOUND`, đây không phải là một tính năng bổ sung, mà chính là **Core Core Business Logic (Lõi nghiệp vụ quyết định)** vì các lý do sau:
### 1. Định hình Data Model (Schema) cho toàn bộ hệ thống
Nếu không hiểu quy trình này, bạn sẽ thiết kế cơ sở dữ liệu bị thiếu trường dữ liệu nghiêm trọng. Điểm số `Synovitis Grade` không thể lưu dưới dạng một trường `int grade` đơn giản. Dữ liệu y khoa chuẩn hóa bắt buộc phải là một đối tượng phức hợp (Compound Object Model):
JSON
```
{
"patient_id": "BN-10023",
"scan_metadata": {
"joint": "KNEE",
"side": "RIGHT",
"plane": "suprapat-long",
"patient_flexion_degree": 25
},
"extracted_metrics": {
"synovial_thickness_mm": 4.2,
"power_doppler_area_percentage": 34.5
},
"severity_classification": {
"suggested_grade": 2,
"confirmed_grade": 2,
"is_overridden_by_doctor": false
}
}
```
### 2. Kích hoạt State Machine & Pipeline xử lý của AI (Mô tả trong tài liệu VKIST)
Theo tài liệu kiến trúc của hệ thống, Use Case này là điểm kết thúc (`Final Destination`) của một Pipeline phân nhánh phức tạp. Khi ảnh DICOM/Siêu âm được đẩy lên hệ thống:
- **Mô hình 1 (ConvNeXt):** Kiểm tra góc chụp. Nếu và chỉ nếu kết quả trả về đúng `sup_up_long`, hệ thống mới kích hoạt State tiếp theo.
- **Mô hình 2 (EfficientNet/MedViT):** Kiểm tra trạng thái phân loại nhị phân `Has Inflammation = True/False`.
- **Mô hình 3 (MedSAM/UNet):** Tiến hành phân đoạn vùng ảnh (Segmentation) tạo Mask đè màu để tính toán diện tích pixel bị tổn thương, từ đó tự động map ra điểm số Phân cấp từ 0 đến 3.
Nếu Use Case này bị lỗi hoặc UIX thiết kế không khớp, toàn bộ Pipeline AI trị giá hàng nghìn giờ huấn luyện phía sau sẽ mất hoàn toàn giá trị sử dụng thực tế.
### 3. Giải quyết bài toán Tải trọng hệ thống và Kiệt sức lâm sàng (Clinical Exhaustion)
Tại các bệnh viện công tuyến trung ương của Việt Nam (Bạch Mai, Bệnh viện E), một bác sĩ (UP5) phải xử lý >100 ca/ca trực.
- Nếu không có phần mềm: Bác sĩ phải đổi ghế, chuyển ứng dụng, gõ tay kết quả vào hệ thống EMR thủ công $\rightarrow$ Nút thắt cổ chai gây delay hệ thống (Latency).
- Khi có Use Case này được tự động hóa trên Dashboard: AI tính toán diện tích, trả về gợi ý bậc viêm ngay trên canvas xem ảnh, bác sĩ chỉ mất đúng 1 click chuột để xác nhận và Sync tự động sang Database tổng. Bạn đang giúp bệnh viện giảm thời gian xử lý một ca từ 5 phút xuống còn 30 giây, trực tiếp tối ưu hóa thông lượng (Throughput) cho toàn bộ hạ tầng y tế.
- **The Alignment Check:** Với góc nhìn bóc tách hệ thống và phân tích Pipeline tín hiệu/AI như trên, bạn đã thấy rõ được bài toán kiến trúc mình cần giải quyết ở Use Case này chưa, hay có điểm nào cần làm sáng tỏ thêm trước khi chúng ta vẽ sơ đồ Use Case bằng PlantUML?
- Explain Why doctor are caring so much on this usecase
- **The Gap:** Hiểu rõ động lực lâm sàng và giá trị chẩn đoán thực tế của Bác sĩ (Missing Clinical Drivers and Real-World Diagnostic Insights for Synovitis Grading).
- **The Question:** Tại sao Bác sĩ Chẩn đoán hình ảnh (UP5) lại đặc biệt quan tâm đến Use Case Phân cấp Viêm màng hoạt dịch (`Synovitis Grading`), và chỉ số này tiết lộ điều gì cốt lõi trong hành trình chẩn đoán, điều trị của bệnh nhân?
- **The Hint:** Trong y khoa, bản thân hình ảnh siêu âm xám chỉ là dữ liệu thô (raw data). Kết quả phân cấp từ Use Case này chính là **thông tin có cấu trúc (structured insights)** giúp bác sĩ trả lời câu hỏi cốt lõi của lâm sàng: Bệnh nhân này đang bị tàn phá khớp ở mức độ nào, tổn thương này là mạn tính (sẹo mô) hay cấp tính (đang bùng phát), và phác đồ điều trị bằng thuốc hoặc can thiệp ngoại khoa nào là chính xác nhất.
- **The Recommendations:** Dưới đây là bóc tách chi tiết lý do vì sao bác sĩ cần Use Case này, được phân tích rõ ràng để một Kỹ sư Phần mềm nắm bắt trọn vẹn nghiệp vụ (Domain Knowledge):
### 1. Phân biệt Giữa "Tổn thương Cũ" (Mạn tính) và "Đợt Viêm Cấp" (Đang bùng phát)
- **Ý nghĩa lâm sàng:** Khi nhìn vào ảnh siêu âm đen trắng (B-mode), bác sĩ thấy một vùng màng hoạt dịch dày lên (ví dụ: dày 4mm). Tuy nhiên, ảnh đen trắng đơn thuần **không thể** cho biết vùng phì đại đó là vết sẹo cũ từ 3 năm trước (mô xơ đã ổn định) hay là vùng mô đang liên tục sưng tấy, ăn mòn sụn khớp.
- **Use Case tiết lộ điều gì:** Bằng cách kết hợp luồng dữ liệu của **Power Doppler**, Use Case này bóc tách và định lượng chính xác mật độ mạch máu tăng sinh (`Hypervascularity`).
- *Dày mô + Không có tín hiệu Doppler (Grade 1):* Tổn thương cũ, chỉ cần theo dõi hoặc vật lý trị liệu.
- *Dày mô + Tín hiệu Doppler dày đặc (Grade 3):* Ổ viêm đang hoạt động cực kỳ dữ dội. Hệ thống miễn dịch của bệnh nhân đang tấn công nhầm vào chính các tế bào khớp gối, giải phóng hàng loạt enzyme ăn mòn sụn và xương. Bác sĩ cần phải can thiệp ngay lập tức bằng thuốc ức chế miễn dịch mạnh (như Corticoid hoặc DMARDs) để chặn đứng dòng thác phá hủy này.
### 2. Điểm Số Quyết Định Phác Đồ Điều Trị (Actionable Clinical Metric)
Điểm số Phân cấp từ 0 đến 3 không phải là một cái tag hiển thị cho đẹp, nó hoạt động giống như một **luồng điều hướng logic (Decision Tree)** quyết định trực tiếp hành động lâm sàng của bác sĩ:
- **Grade 0 (Bình thường):** Chuyển bệnh nhân sang chế độ phòng ngừa, xuất viện.
- **Grade 1 (Nhẹ):** Chỉ định điều trị nội khoa bảo tồn ở mức độ thấp (Dùng thuốc kháng viêm không Steroid - NSAIDs, thay đổi lối sống, tập vật lý trị liệu với bác sĩ PT - UP6).
- **Grade 2 (Vừa):** Cân nhắc tiêm thuốc nội khớp (tiêm Corticoid trực tiếp vào ngách khớp gối để dập dịch viêm tại chỗ) kết hợp điều trị thuốc đặc hiệu.
- **Grade 3 (Nặng/Nghiêm trọng):** Rút dịch khớp (Arthrocentesis) để giảm áp lực, chỉ định nhập viện điều trị tích cực, hoặc chuyển tuyến ngoại khoa để thực hiện phẫu thuật nội soi cắt màng hoạt dịch (Synovectomy) nhằm cứu lấy sụn khớp trước khi gối bị biến dạng hoàn toàn không thể phục hồi.
### 3. Thước Đo Khách Quan Để Đánh Giá Hiệu Quả Thuốc (Treatment Monitoring Dashboard)
- **Nỗi đau của Bác sĩ:** Khi điều trị các bệnh tự miễn như Viêm khớp dạng thấp, bệnh nhân phải uống thuốc ròng rã nhiều tháng trời. Nếu bác sĩ chỉ hỏi bệnh nhân *"Bác có bớt đau không?"*, câu trả lời sẽ cực kỳ chủ quan và không chính xác (do ngưỡng chịu đau của mỗi người khác nhau và có hiệu ứng giả dược).
- **Use Case tiết lộ điều gì:** Use Case này cung cấp một **Standardized Baseline (Mốc chuẩn hóa)** để so sánh liên tục qua các mốc thời gian (Time-series Analysis).
- *Tháng 1:* Bệnh nhân đến khám $\rightarrow$ Hệ thống chấm **Grade 3** (Màng hoạt dịch dày 6mm, Doppler phủ 65% area).
- *Tháng 3 (Sau 2 tháng uống thuốc):* Bệnh nhân tái khám $\rightarrow$ Hệ thống chấm **Grade 1** (Màng hoạt dịch giảm còn 2.5mm, Doppler chỉ còn vài chấm cô lập).
$\rightarrow$ Phần mềm tiết lộ cho bác sĩ một bằng chứng số liệu toán học tuyệt đối: **Phác đồ thuốc hiện tại đang hoạt động hiệu quả**, tiếp tục duy trì liều lượng. Ngược lại, nếu điểm số vẫn là Grade 3, hệ thống cảnh báo bác sĩ rằng bệnh nhân đang kháng thuốc, phải đổi sang loại thuốc sinh học đắt tiền hơn ngay lập tức.
### 4. Triệt Tiêu Biến Thiên Giữa Các Bác Sĩ (Eradicating Inter-observer Variability)
- **Thực trạng tại bệnh viện:** Việc phân cấp siêu âm thủ công phụ thuộc rất nhiều vào mắt nhìn chủ quan và kinh nghiệm của từng người. Bác sĩ A (15 năm kinh nghiệm) nhìn ảnh đoán là Grade 2, nhưng Bác sĩ B (mới ra trường 1 năm) lại chấm là Grade 3 vì thấy túi dịch có vẻ to. Sự lệch pha này gây nguy hiểm cho tính đồng nhất của phác đồ điều trị.
- **Use Case tiết lộ điều gì:** Khi có AI hỗ trợ trích xuất độ dày vùng ngách trên xương bánh chè (`suprapatellar recess`) và tính tỷ lệ pixel màu Doppler một cách tự động, hệ thống đóng vai trò như một **bộ kiểm tra điều kiện logic khách quan (Deterministic Gatekeeper)**. Nó đưa ra một mức điểm gợi ý dựa trên thuật toán tính toán diện tích chuẩn y khoa, giúp đồng bộ hóa chất lượng chẩn đoán tại bệnh viện. Bác sĩ dù già hay trẻ đều nhìn thấy một cơ sở số liệu minh bạch để đưa ra quyết định cuối cùng.
- **The Alignment Check:** Qua bóc tách dưới góc nhìn lâm sàng này, bạn đã hiểu vì sao kết quả đầu ra của Use Case này (`Grade 0-3`) lại đóng vai trò là "trái tim mạch máu" cho toàn bộ Dashboard điều trị phía sau chưa, hay bạn muốn chúng ta đào sâu thêm vào điểm nào trước khi thiết kế các tương tác UIX?
- The System suggest what currently being missed from FR and need to define in the UC:
- **The Gap:** Ambiguous System & Actor Interaction Boundaries inside the Grading Workflow (Thiếu tường minh về ranh giới tương tác giữa Hệ thống và Bác sĩ).
- **The Question:** How exactly should the doctor **interact** with the system's automated AI calculation when adjusting or validating the suggested severity score (e.g., from Grade 2 to Grade 3)? - The answer of this
The precise, clinically accurate baseline workflow executed by a Diagnostic Radiologist (UP5) consists of the following 6 sequential phases:
- **Step 1 (Patient Posture Standardization):** The clinician places the patient in a supine position with the target knee supported by a bolster in **20°–30° of slight flexion**. This stretches the extensor mechanism (the **Quadriceps/Patellar Tendon)** and eliminates diagnostic tracking errors caused by acoustic anisotropy.
- Explain with simplification for Software Engineer
- **The Clinical Action:** The patient lies flat, knee bent exactly 20°–30° over a cushion.
- **The Software Engineer Analogy:** **Setting up consistent environment variables and running an initialization handshake.**
- **Deep Jargon Breakdown:**
- **Extensor Mechanism - Quadriceps/Patellar Tendon:** Think of this as a mechanical rubber band system (quadriceps muscle → tendon →kneecap → shin bone). When the leg is completely straight, this system sags and wrinkles. Bending it 20°–30° stretches it taut, creating a flat, predictable surface line.
- **Acoustic Anisotropy (The Crucial Hardware Bug):** This is a structural physical hardware limitation of ultrasound waves. If the sound beam hits a tendon at a perfect 90° right angle, it bounces back bright white (**Echoic**). If the probe tilts even 5° offline because the tendon is curved/sagging, the wave scatters sideways, and the tissue suddenly registers on-screen as pitch black (**Hypoechoic**), mimicking a fake fluid tear or inflammatory lesion.
- **Why this matters for your UI/Product Design:** This step is your raw input data sanity check. If the patient isn't positioned right, the ultrasound picture is filled with visual artifact bugs (garbage in, garbage out). Your system needs to know it is processing a standardized 20°–30° landscape view.
- **Step 2 (Longitudinal Probe Alignment):** The clinician positions a high-frequency linear transducer probe over the midline of the **suprapatellar recess** (sagittal plane), aligning the distal edge over the upper pole of the patella to capture the clear multi-layered layout of the quadriceps tendon.
- Explain with simplification for SE
- **The Clinical Action:** The linear probe is placed lengthwise right down the middle of the upper knee, overlapping the top edge of the kneecap.
- **The Software Engineer Analogy:** **Pointing your API client path to the exact parent database index to unpack a nested multi-layered object arrays.**
- **Deep Jargon Breakdown:**
- **Suprapatellar Recess:** This is the precise target memory location—a pouch-like joint cavity hiding right above the kneecap (**Supra** = above, **Patella** = kneecap) underneath the deep tissue layers.
- **Sagittal Plane:** A vertical front-to-back cross-section cut. If your application was a 3D video game engine, this is viewing the joint asset precisely from the orthogonal **Side View Viewport**, rather than looking from the front or top down.
- **Why this matters for your UI/Product Design:** This gives the system its coordinate system reference frame. In this view, your AI algorithm can run edge detection along standard anatomical landmarks, treating the top edge of the patella as a rock-solid structural zero-point anchor on a 2D canvas.
- **Step 3 (B-Mode Structural Metric Capture):** Using standard Grey Scale (B-mode), the radiologist identifies the hypoechoic tissue area resting between the *prefemoral fat pad* and the *suprapatellar fat pad*. They visually calculate the maximum vertical distance of joint capsule distension/thickening using the ultrasound console's physical calipers.
- Explain for SE
- **The Clinical Action:** The doctor switches to a black-and-white image, identifies the space between two fat patches, and hits two points on the console to calculate the space thickness.
- **The Software Engineer Analogy:** **Running a 2D Bounding Box Segmentation model to extract a quantitative `float` metric (distance in mm) between two fixed system nodes.**
- **Deep Jargon Breakdown:**
- **B-Mode (Brightness Mode):** This is the baseline structural image format. It transforms reflected sound wave amplitudes into live pixel intensity map arrays (high reflection = white pixels; zero reflection/fluid fluid pools = dark black pixels).
- **Hypoechoic Tissue Area:** Any region that absorbs or passes sound waves easily instead of reflecting them, rendering as a dark grey or black signal pool. Inflamed synovial tissue fluid sits in this category.
- **Prefemoral & Suprapatellar Fat Pads:** These are your permanent upper and lower hardware guardrail markers. The suprapatellar pouch sits wedged right between them like an expandable buffer queue.
- **Why this matters for your UI/Product Design:** This is **REQ-RAD-02** in your requirement documentation. The doctor uses manual calipers to measure this space. Your product UI can introduce a digital bounding path box or automated point-to-point drawing tool overlay to automatically extract this distance variable, completely stripping away the manual console math step.
- **Step 4 (Power Doppler Vascularity Mapping):** The clinician activates the Power Doppler mode on the console, optimizing the wall filter and PRF settings. They carefully hover the probe with **minimal contact pressure** to avoid compressing low-velocity synovial capillaries, visually counting or calculating the percentage area occupied by active blood flow signals inside the suprapatellar landscape.
- Explain for SE
- **The Clinical Action:** The doctor switches on the color overlay feature, tweaks the sensitivity filters, and hovers the probe extremely lightly without pressing down into the skin.
- **The Software Engineer Analogy:** **Activating a live telemetry tracer module with a low-pass noise filter to map active server data traffic volume while avoiding an external physical choke/throttling event.**
- **Deep Jargon Breakdown:**
- **Power Doppler Mode:** A specialized signal tracking sub-routine. Instead of mapping structural tissue borders, it tracks shifts in frequency caused by moving targets (red blood cells). It highlights these regions with bright, glowing color maps overlaid right on top of the black-and-white structural layer.
- **Wall Filter & PRF (Pulse Repetition Frequency):** These are variable noise gates. If configured wrong, minor hand tremors will bleed into the visual feed as massive colored pixels (**Clutter Artifact Noise**).
- synpvia Capillary Compression Edge Case: If the doctor applies heavy hand force, they manually flatten the tiny micro-blood vessels inside the knee. This physically blocks blood flow, wiping out the signal completely on screen and returning a false negative trace.
- **Why this matters for your UI/Product Design:** This maps directly to your **Hypervascularity parameter**. Your interface can assist by calculating the ratio of bright color pixels to the total area of the segmented pouch, converting a subjective visual guess into a precise numerical percentage readout.
- **Step 5 (Semi-Quantitative Grade Synthesis):** The clinician combines both structural metrics mentally against standard musculoskeletal classification tiers: - THE VKIST ML-Module current stop in here
- *Grade 0 (None):* Completely flat layers; no hypoechoic separation or vascular flow signals.
- *Grade 1 (Mild):* Thin hypoechoic line running parallel to the femoral bone path; single or minimal isolated vascular blood flow spots.
- *Grade 2 (Moderate):* Evident hypoechoic expansion pushing the fat pads apart, but lines remain flat; active vascular flow spots occupying less than 50% of the calculated synovial area.
- *Grade 3 (Severe):* Clear convex or distinct bulging capsule distortion extending outward; intense confluent flow signals covering more than 50% of the calculated synovial landscape.
- Explain for SE
- **The Clinical Action:** The doctor looks at both parameters (the pouch thickness + the active color blood flow maps) and maps them to a standard clinical severity tier level (0 to 3).
- **The Software Engineer Analogy:** **Evaluating raw aggregated metric values against a core business logic conditional switch block (`switch(severityGrade)`) to determine system status codes.**
- **Deep Tiers Demystified via Code Logic:**
- **Grade 0 (Healthy Baseline):**
```jsx
if (synovialThickness === 0 && hypervascularityScore === 0) return "Grade 0: Normal Space";
```
- **Grade 1 (Mild Inflammation):** Space is filled with a thin, parallel line of tissue expansion; trace color dots show up.JavaScript
```
if (synovialThickness > 0 && hypervascularityScore <= 0.10) return "Grade 1: Mild Distension";
```
- **Grade 2 (Moderate Inflammation):** The tissue swells enough to visibly push the flanking fat pads apart, and the active blood flow color blocks cover up to half of the pouch container zone.JavaScript
```
if (synoviumDistended === true && hypervascularityScore < 0.50) return "Grade 2: Moderate Pouch Deflection";
```
- **Grade 3 (Severe Inflammation):** The pouch balloons into a curved, outward bulging geometric form; intense, connected color maps take over more than half of the space landscape.JavaScript
```
if (capsuleShape === 'convex_bulge' || hypervascularityScore >= 0.50) return "Grade 3: Critical Structural Flare";
```
- **Step 6 (Manual Multi-Silo Transcription):** The clinician freezes the optimal reference frames on the hardware console, manually assigns a final severity index label, moves away from the ultrasound machine hardware screen to a desktop workstation PC, and types out the structural text variables into the hospital's Electronic Medical Record (EMR) text block.
- Explain for SE
- **The Clinical Action:** The doctor freezes the machine display screen, manually records a final tier index number, stands up, switches chairs to a secondary office computer, logs in, and re-types the exact observations by hand into a text window box.
- **The Software Engineer Analogy:** **A total lack of system database synchronization. Hand-copying raw log data variables from a separate terminal window and typing them line-by-line into a separate decoupled microservice application.**
- **Why this matters for your UI/Product Design:** This is the massive core workflow bottleneck. The goal of your upcoming workspace design is to build an interactive, unified web interface bridge. The AI processes the image data parameters natively, renders an automated classification tag proposal directly inside the primary viewing frame, and updates the shared patient record database with 0 manual transcript entries or physical context-switching loops.
- Additional - from the answer in the `Question` we can model the planUML code solution
!image.png
```jsx
@startuml
' Settings
left to right direction
skin rose
' Actors
actor "Diagnostic Radiologist (UP5)" as Rad
actor "Hospital EMR System" as EMR << System >>
actor "VKIST AI Pipeline" as AI << System >>
' System Boundary
rectangle "VKIST MSK Workspace - Synovitis Grading Engine" {
' Core Viewing & Extraction Use Cases
usecase "Load Patient Ultrasound Session" as UC-48376
usecase "Extract Joint Tissue Metrics" as UC_Extract
' AI Suggestion Processing
usecase "Compute Automated Severity Suggestion" as UC_AI_Compute
usecase "Display Suggestion Tag & Canvas Overlays" as UC_Display
' Clinician Interaction & Decision Loop
usecase "Review Suggested Synovitis Grade (0-3)" as UC-47988
usecase "Manually Override Severity Grade" as UC_Override
usecase "Sign & Finalize Diagnostic Conclusions" as UC-92006
' Data Sync Hand-off
usecase "Synchronize Patient Record" as UC_Sync
}
' Relationships & Flow Boundaries
Rad --> UC-48376
Rad --> UC-47988
Rad --> UC-92006
' AI Pipeline Interactions
UC-48376 ..> UC_Extract : <<include>>
UC_Extract --> AI : Transmit raw image streams
AI --> UC_AI_Compute : Process thickness & Doppler maps
UC_AI_Compute ..> UC_Display : <<include>>
' Review and Override Loop
UC_Display ..> UC-47988 : <<include>>
UC_Override .up.> UC-47988 : <<extend>> (If clinician disagrees with AI)
Rad --> UC_Override
' Finalization and Sync Hand-offs
UC-92006 ..> UC_Sync : <<include>>
UC_Sync --> EMR : Push standardized JSON structural data
@enduml
```
→ For the Synovist Grading the interaction between the clinician & system may occur 4 potential case: —> 4 possible interactions
```jsx
+-----------------------------------------------------------------------+
| HUMAN-AI CONCURRENT STATES |
+-----------------------------------+-----------------------------------+
| QUADRANT 2 | QUADRANT 1 |
| Automation Override Risk | True Agreement |
| | |
| AI: Grade 3 (Accurate) | AI: Grade 2 (Accurate) |
| Human: Grade 1 (Oversight) | Human: Grade 2 (Confident) |
| Risk: Severe Disease Missed | Risk: None (Happy Path) |
+-----------------------------------+-----------------------------------+
| QUADRANT 4 | QUADRANT 3 |
| Double-Blind Failure | Clinician Subservience Risk |
| | |
| AI: Grade 2 (Boundary Error) | AI: Grade 3 (Hallucinated) |
| Human: Grade 1 (Biased Error) | Human: Grade 1 (Accurate) |
| Risk: Cascading System Error | Risk: Over-treatment Danger |
+-----------------------------------+-----------------------------------+
```
THE ML-stack use in this scenarios:
- the grading ML-stack (VKIST-model) → always use (it’s the machine process on the raw-signal from device)
- the LLM Critic & Actor for acting as explainer on the results of the grading stack (de-blackbox) + conversation with the clinics for pathologic analysis <with RAG> + critic-suggestion (this LLM shall have to loaded with SKILL / multi-agent system)
- the LLM-RAG-Referee for prevent bias & blindness of both-side (actor & grader & clinical)
| **Referee Role** | **Problem Solved** | **Mechanism** |
| --- | --- | --- |
| **1. Unbiased Arbiter** | **Conflict & Bias:** Prevents the LLM from hallucinating to match the clinician's incorrect bias (Confirmation Bias). | Operates as a **Session-State Arbiter**: It ignores conversation history and focuses purely on comparing the raw metrics (`GradCAM maps`, `Doppler indices`) against clinical definitions. |
| **2. Domain Guardian** | **Knowledge Obsolescence:**Prevents the system from using outdated medical standards (e.g., guidelines from 2020 instead of 2025). | Operates as a **Knowledge-Retrieval Guardian**: It triggers when the system detects high semantic entropy, fetching the *latest* approved academic guidelines to ensure all explanations remain clinically valid. |
The Actor:
- the UP-5 user working with the hardware
4 scenarios can consider

28
proj_level_reading/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/update_uc_ids.py Normal file
View File

@@ -0,0 +1,28 @@
mapping = {
'UC_Load': 'UC-48376',
'UC_Review': 'UC-47988',
'UC_Finalize': 'UC-92006',
'UC_Q1_Explain': 'UC-25776',
'UC_Q1_Log': 'UC-02423',
'UC_Q2_Intercept': 'UC-22159',
'UC_Q2_Socratic': 'UC-55146',
'UC_Q2_BERT': 'UC-74821',
'UC_Q2_Arbiter': 'UC-65473',
'UC_Q3_Expose': 'UC-25637',
'UC_Q3_Isolate': 'UC-60739',
'UC_Q3_Commit': 'UC-62864',
'UC_Q4_Escalate': 'UC-35956',
'UC_Q4_Annotate': 'UC-47796',
'UC_Q4_Queue': 'UC-01580'
}
# file_path = '/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/Reading_docs/Requirement_Analysis/UC_Design/FR_25_UC_DESIGN/FR_25_UC_SPEC.md'
# with open(file_path, 'r') as f:
# content = f.read()
# for old, new in mapping.items():
# content = content.replace(old, new)
# with open(file_path, 'w') as f:
# f.write(content)

458
proj_level_reading/Technical_Brainstorming/.$TechBrainStorm.drawio.bkp Normal file
View File

File diff suppressed because one or more lines are too long

BIN
proj_level_reading/Technical_Brainstorming/NLP_Edge_Deploy/(Chen et al., 2026).pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/NLP_Edge_Deploy/(Xu et al., 2026).pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/1m-report.docx Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/5. Công nghệ siêu âm khớp gối (PILOT).pptx Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/Công nghệ siêu âm khớp gối (PILOT).pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/Giới thiệu về VKIST_ULTRASOUND.docx Normal file
View File

Binary file not shown.

130531
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/HS50_HS60_User_Manual_Vol1_Eng.pdf Normal file
View File

File diff suppressed because one or more lines are too long

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/HS50_HS60_User_Manual_Vol2_Eng.pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/Image reconstruction by localized impainting for anomaly.pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/Musculoskeletal Ultrasound Technical Guidelines.pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/Mô tả hệ thống (cũ).pdf Normal file
View File

Binary file not shown.

5529
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/Thuật-Ngữ-Y-Khoa-Cơ-Xương-Khớp.pdf Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/Tài liệu HDSD và cài đặt Pilot 2025 - Nguyễn Đỗ Dương.docx Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/fmed-10-1286085.pdf Normal file
View File

Binary file not shown.

15617
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/long2020.pdf Normal file
View File

File diff suppressed because one or more lines are too long

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/làm quen với khớp gối.docx Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/nihms-1967483.pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/quy trình tra cứu sáng chế và hướng dẫn sử dụng phần mềm.docx Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/~$i liệu HDSD và cài đặt Pilot 2025 - Nguyễn Đỗ Dương.docx Normal file
View File

Binary file not shown.

BIN
proj_level_reading/Technical_Brainstorming/PILOT_TECHNICAL_GUIDELINE_DOCS/~$m quen với khớp gối.docx Normal file
View File

Binary file not shown.

544
proj_level_reading/Technical_Brainstorming/TechBrainStorm.drawio Normal file
View File

File diff suppressed because one or more lines are too long

BIN
proj_level_reading/Technical_Brainstorming/watermarked_img_12084041102876525620.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 189 KiB

14813
proj_level_reading/User_Analysis/Clinician_Analysis/(Alshuweihi et al., 2025).pdf Normal file
View File

File diff suppressed because one or more lines are too long

4866
proj_level_reading/User_Analysis/Clinician_Analysis/(Dao et al., 2018).pdf Normal file
View File

File diff suppressed because one or more lines are too long

BIN
proj_level_reading/User_Analysis/Clinician_Analysis/(Duc et al., 2025).pdf Normal file
View File

Binary file not shown.

10746
proj_level_reading/User_Analysis/Clinician_Analysis/(Le et al., 2024).pdf Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
proj_level_reading/User_Analysis/Clinician_Analysis/(Roustan & Bastardot, 2025).pdf Normal file
View File

Binary file not shown.

29367
proj_level_reading/User_Analysis/Clinician_Analysis/(Zhang et al., 2023).pdf Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
proj_level_reading/User_Analysis/Clinician_Analysis/User Profile_ Vietnamese Physiotherapists.pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/User_Analysis/Healthcare_Stack_analysis/Overview_Healthcare_Techstack.pdf Normal file
View File

Binary file not shown.

BIN
proj_level_reading/User_Analysis/Policy_Analysis/how_to_commericalized_legalizing_healthcare_product/96-nd.signed.pdf Normal file
View File

Binary file not shown.

510
proj_level_reading/User_Analysis/Policy_Analysis/how_to_commericalized_legalizing_healthcare_product/split.md Normal file
View File

@@ -0,0 +1,510 @@
<!-- image -->
## Architectural design
## Objectives
The objective of this chapter is to introduce the concepts of software architecture and architectural design. When you have read the chapter, you will:
- ■ understand why the architectural design of software is important;
- ■ understand the decisions that have to be made about the system architecture during the architectural design process;
- ■ have been introduced to the idea of architectural patterns, well-tried ways of organizing system architectures, which can be reused in system designs;
- ■ know the architectural patterns that are often used in different types of application system, including transaction processing systems and language processing systems.
## Contents
- 6.1 Architectural design decisions
- 6.2 Architectural views
- 6.3 Architectural patterns
- 6.4 Application architectures
Architectural design is concerned with understanding how a system should be organized and designing the overall structure of that system. In the model of the software development process, as shown in Chapter 2, architectural design is the first stage in the software design process. It is the critical link between design and requirements engineering, as it identifies the main structural components in a system and the relationships between them. The output of the architectural design process is an architectural model that describes how the system is organized as a set of communicating components.
In agile processes, it is generally accepted that an early stage of the development process should be concerned with establishing an overall system architecture. Incremental development of architectures is not usually successful. While refactoring components in response to changes is usually relatively easy, refactoring a system architecture is likely to be expensive.
To help you understand what I mean by system architecture, consider Figure 6.1. This shows an abstract model of the architecture for a packing robot system that shows the components that have to be developed. This robotic system can pack different kinds of object. It uses a vision component to pick out objects on a conveyor, identify the type of object, and select the right kind of packaging. The system then moves objects from the delivery conveyor to be packaged. It places packaged objects on another conveyor. The architectural model shows these components and the links between them.
In practice, there is a significant overlap between the processes of requirements engineering and architectural design. Ideally, a system specification should not include any design information. This is unrealistic except for very small systems. Architectural decomposition is usually necessary to structure and organize the specification. Therefore, as part of the requirements engineering process, you might propose an abstract system architecture where you associate groups of system functions or features with large-scale components or sub-systems. You can then use this decomposition to discuss the requirements and features of the system with stakeholders.
You can design software architectures at two levels of abstraction, which I call architecture in the small and architecture in the large :
1. Architecture in the small is concerned with the architecture of individual programs. At this level, we are concerned with the way that an individual program is decomposed into components. This chapter is mostly concerned with program architectures.
2. Architecture in the large is concerned with the architecture of complex enterprise systems that include other systems, programs, and program components. These enterprise systems are distributed over different computers, which may be owned and managed by different companies. I cover architecture in the large in Chapters 18 and 19, where I discuss distributed systems architectures.
Figure 6.1 The architecture of a packing robot control system Software architecture is important because it affects the performance, robustness, distributability, and maintainability of a system (Bosch, 2000). As Bosch discusses, individual components implement the functional system requirements. The nonfunctional requirements depend on the system architecture-the way in which these components are organized and communicate. In many systems, non-functional requirements are also influenced by individual components, but there is no doubt that the architecture of the system is the dominant influence.
<!-- image -->
Bass et al. (2003) discuss three advantages of explicitly designing and documenting software architecture:
1. Stakeholder communication The architecture is a high-level presentation of the system that may be used as a focus for discussion by a range of different stakeholders.
2. System analysis Making the system architecture explicit at an early stage in the system development requires some analysis. Architectural design decisions have a profound effect on whether or not the system can meet critical requirements such as performance, reliability, and maintainability.
3. Large-scale reuse A model of a system architecture is a compact, manageable description of how a system is organized and how the components interoperate. The system architecture is often the same for systems with similar requirements and so can support large-scale software reuse. As I explain in Chapter 16, it may be possible to develop product-line architectures where the same architecture is reused across a range of related systems.
Hofmeister et al. (2000) propose that a software architecture can serve firstly as a design plan for the negotiation of system requirements, and secondly as a means of structuring discussions with clients, developers, and managers. They also suggest that it is an essential tool for complexity management. It hides details and allows the designers to focus on the key system abstractions.
System architectures are often modeled using simple block diagrams, as in Figure 6.1. Each box in the diagram represents a component. Boxes within boxes indicate that the component has been decomposed to sub-components. Arrows mean that data and or control signals are passed from component to component in the direction of the arrows. Y ou can see many examples of this type of architectural model in Booch's software architecture catalog (Booch, 2009).
Block diagrams present a high-level picture of the system structure, which people from different disciplines, who are involved in the system development process, can readily understand. However, in spite of their widespread use, Bass et al. (2003) dislike informal block diagrams for describing an architecture. They claim that these informal diagrams are poor architectural representations, as they show neither the type of the relationships among system components nor the components' externally visible properties.
The apparent contradictions between practice and architectural theory arise because there are two ways in which an architectural model of a program is used:
1. As a way of facilitating discussion about the system design A high-level architectural view of a system is useful for communication with system stakeholders and project planning because it is not cluttered with detail. Stakeholders can relate to it and understand an abstract view of the system. They can then discuss the system as a whole without being confused by detail. The architectural model identifies the key components that are to be developed so managers can start assigning people to plan the development of these systems.
2. As a way of documenting an architecture that has been designed The aim here is to produce a complete system model that shows the different components in a system, their interfaces, and their connections. The argument for this is that such a detailed architectural description makes it easier to understand and evolve the system.
Block diagrams are an appropriate way of describing the system architecture during the design process, as they are a good way of supporting communications between the people involved in the process. In many projects, these are often the only architectural documentation that exists. However, if the architecture of a system is to be thoroughly documented then it is better to use a notation with well-defined semantics for architectural description. However, as I discuss in Section 6.2, some people think that detailed documentation is neither useful, nor really worth the cost of its development.
■
## 6.1 Architectural design decisions
Architectural design is a creative process where you design a system organization that will satisfy the functional and non-functional requirements of a system. Because it is a creative process, the activities within the process depend on the type of system being developed, the background and experience of the system architect, and the specific requirements for the system. It is therefore useful to think of architectural design as a series of decisions to be made rather than a sequence of activities.
During the architectural design process, system architects have to make a number of structural decisions that profoundly affect the system and its development process. Based on their knowledge and experience, they have to consider the following fundamental questions about the system:
1. Is there a generic application architecture that can act as a template for the system that is being designed?
2. How will the system be distributed across a number of cores or processors?
3. What architectural patterns or styles might be used?
4. What will be the fundamental approach used to structure the system?
5. How will the structural components in the system be decomposed into subcomponents?
6. What strategy will be used to control the operation of the components in the system?
7. What architectural organization is best for delivering the non-functional requirements of the system?
8. How will the architectural design be evaluated?
9. How should the architecture of the system be documented?
Although each software system is unique, systems in the same application domain often have similar architectures that reflect the fundamental concepts of the domain. For example, application product lines are applications that are built around a core architecture with variants that satisfy specific customer requirements. When designing a system architecture, you have to decide what your system and broader application classes have in common, and decide how much knowledge from these application architectures you can reuse. I discuss generic application architectures in Section 6.4 and application product lines in Chapter 16.
For embedded systems and systems designed for personal computers, there is usually only a single processor and you will not have to design a distributed architecture for the system. However, most large systems are now distributed systems in which the system software is distributed across many different computers. The choice of distribution architecture is a key decision that affects the performance and reliability of the system. This is a major topic in its own right and I cover it separately in Chapter 18.
The architecture of a software system may be based on a particular architectural pattern or style. An architectural pattern is a description of a system organization (Garlan and Shaw, 1993), such as a client-server organization or a layered architecture. Architectural patterns capture the essence of an architecture that has been used in different software systems. You should be aware of common patterns, where they can be used, and their strengths and weaknesses when making decisions about the architecture of a system. I discuss a number of frequently used patterns in Section 6.3.
Garlan and Shaw's notion of an architectural style (style and pattern have come to mean the same thing) covers questions 4 to 6 in the previous list. You have to choose the most appropriate structure, such as client-server or layered structuring, that will enable you to meet the system requirements. To decompose structural system units, you decide on the strategy for decomposing components into sub-components. The approaches that you can use allow different types of architecture to be implemented. Finally, in the control modeling process, you make decisions about how the execution of components is controlled. You develop a general model of the control relationships between the various parts of the system.
Because of the close relationship between non-functional requirements and software architecture, the particular architectural style and structure that you choose for a system should depend on the non-functional system requirements:
1. Performance If performance is a critical requirement, the architecture should be designed to localize critical operations within a small number of components, with these components all deployed on the same computer rather than distributed across the network. This may mean using a few relatively large components rather than small, fine-grain components, which reduces the number of component communications. You may also consider run-time system organizations that allow the system to be replicated and executed on different processors.
2. Security If security is a critical requirement, a layered structure for the architecture should be used, with the most critical assets protected in the innermost layers, with a high level of security validation applied to these layers.
3. Safety If safety is a critical requirement, the architecture should be designed so that safety-related operations are all located in either a single component or in a small number of components. This reduces the costs and problems of safety validation and makes it possible to provide related protection systems that can safely shut down the system in the event of failure.
4. Availability If availability is a critical requirement, the architecture should be designed to include redundant components so that it is possible to replace and update components without stopping the system. I describe two fault-tolerant system architectures for high-availability systems in Chapter 13.
5. Maintainability If maintainability is a critical requirement, the system architecture should be designed using fine-grain, self-contained components that may
readily be changed. Producers of data should be separated from consumers and shared data structures should be avoided.
Obviously there is potential conflict between some of these architectures. For example, using large components improves performance and using small, fine-grain components improves maintainability. If both performance and maintainability are important system requirements, then some compromise must be found. This can sometimes be achieved by using different architectural patterns or styles for different parts of the system.
Evaluating an architectural design is difficult because the true test of an architecture is how well the system meets its functional and non-functional requirements when it is in use. However, you can do some evaluation by comparing your design against reference architectures or generic architectural patterns. Bosch's (2000) description of the non-functional characteristics of architectural patterns can also be used to help with architectural evaluation.
## 6.2 Architectural views
I explained in the introduction to this chapter that architectural models of a software system can be used to focus discussion about the software requirements or design. Alternatively, they may be used to document a design so that it can be used as a basis for more detailed design and implementation, and for the future evolution of the system. In this section, I discuss two issues that are relevant to both of these:
1. What views or perspectives are useful when designing and documenting a system's architecture?
2. What notations should be used for describing architectural models?
It is impossible to represent all relevant information about a system's architecture in a single architectural model, as each model only shows one view or perspective of the system. It might show how a system is decomposed into modules, how the run-time processes interact, or the different ways in which system components are distributed across a network. All of these are useful at different times so, for both design and documentation, you usually need to present multiple views of the software architecture.
There are different opinions as to what views are required. Krutchen (1995), in his well-known 4+1 view model of software architecture, suggests that there should be four fundamental architectural views, which are related using use cases or scenarios. The views that he suggests are:
1. A logical view, which shows the key abstractions in the system as objects or object classes. It should be possible to relate the system requirements to entities in this logical view.
2. A process view, which shows how, at run-time, the system is composed of interacting processes. This view is useful for making judgments about nonfunctional system characteristics such as performance and availability.
3. A development view, which shows how the software is decomposed for development, that is, it shows the breakdown of the software into components that are implemented by a single developer or development team. This view is useful for software managers and programmers.
4. A physical view, which shows the system hardware and how software components are distributed across the processors in the system. This view is useful for systems engineers planning a system deployment.
Hofmeister et al. (2000) suggest the use of similar views but add to this the notion of a conceptual view. This view is an abstract view of the system that can be the basis for decomposing high-level requirements into more detailed specifications, help engineers make decisions about components that can be reused, and represent a product line (discussed in Chapter 16) rather than a single system. Figure 6.1, which describes the architecture of a packing robot, is an example of a conceptual system view.
In practice, conceptual views are almost always developed during the design process and are used to support architectural decision making. They are a way of communicating the essence of a system to different stakeholders. During the design process, some of the other views may also be developed when different aspects of the system are discussed, but there is no need for a complete description from all perspectives. It may also be possible to associate architectural patterns, discussed in the next section, with the different views of a system.
There are differing views about whether or not software architects should use the UML for architectural description (Clements, et al., 2002). A survey in 2006 (Lange et al., 2006) showed that, when the UML was used, it was mostly applied in a loose and informal way. The authors of that paper argued that this was a bad thing. I disagree with this view. The UML was designed for describing object-oriented systems and, at the architectural design stage, you often want to describe systems at a higher level of abstraction. Object classes are too close to the implementation to be useful for architectural description.
I don't find the UML to be useful during the design process itself and prefer informal notations that are quicker to write and which can be easily drawn on a whiteboard. The UML is of most value when you are documenting an architecture in detail or using model-driven development, as discussed in Chapter 5.
A number of researchers have proposed the use of more specialized architectural description languages (ADLs) (Bass et al., 2003) to describe system architectures. The basic elements of ADLs are components and connectors, and they include rules and guidelines for well-formed architectures. However, because of their specialized nature, domain and application specialists find it hard to understand and use ADLs. This makes it difficult to assess their usefulness for practical software engineering. ADLs designed for a particular domain (e.g., automobile systems) may be used as a
■
| Name | MVC (Model-View-Controller) |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Description | Separates presentation and interaction from the system data. The system is structured into three logical components that interact with each other. The Model component manages the system data and associated operations on that data. The View component defines and manages how the data is presented to the user. The Controller component manages user interaction (e.g., key presses, mouse clicks, etc.) and passes these interactions to the View and the Model. See Figure 6.3. |
| Example | Figure 6.4 shows the architecture of a web-based application system organized using the MVC pattern. |
| When used | Used when there are multiple ways to view and interact with data. Also used when the future requirements for interaction and presentation of data are unknown. |
| Advantages | Allows the data to change independently of its representation and vice versa. Supports presentation of the same data in different ways with changes made in one representation shown in all of them. |
| Disadvantages | Can involve additional code and code complexity when the data model and interactions are simple. |
Figure 6.2 The modelview-controller (MVC) pattern basis for model-driven development. However, I believe that informal models and notations, such as the UML, will remain the most commonly used ways of documenting system architectures.
Users of agile methods claim that detailed design documentation is mostly unused. It is, therefore, a waste of time and money to develop it. I largely agree with this view and I think that, for most systems, it is not worth developing a detailed architectural description from these four perspectives. You should develop the views that are useful for communication and not worry about whether or not your architectural documentation is complete. However, an exception to this is when you are developing critical systems, when you need to make a detailed dependability analysis of the system. You may need to convince external regulators that your system conforms to their regulations and so complete architectural documentation may be required.
## 6.3 Architectural patterns
The idea of patterns as a way of presenting, sharing, and reusing knowledge about software systems is now widely used. The trigger for this was the publication of a book on object-oriented design patterns (Gamma et al., 1995), which prompted the development of other types of pattern, such as patterns for organizational design (Coplien and Harrison, 2004), usability patterns (Usability Group, 1998), interaction (Martin and Sommerville, 2004), configuration management (Berczuk and Appleton, 2002), and so on. Architectural patterns were proposed in the 1990s under the name 'architectural styles' (Shaw and Garlan, 1996), with a five-volume series of handbooks on pattern-oriented software architecture published between 1996 and 2007 (Buschmann et al., 1996; Buschmann et al., 2007a; Buschmann et al., 2007b; Kircher and Jain, 2004; Schmidt et al., 2000).
Figure 6.3 The organization of the MVC
<!-- image -->
In this section, I introduce architectural patterns and briefly describe a selection of architectural patterns that are commonly used in different types of systems. For more information about patterns and their use, you should refer to published pattern handbooks.
You can think of an architectural pattern as a stylized, abstract description of good practice, which has been tried and tested in different systems and environments. So, an architectural pattern should describe a system organization that has been successful in previous systems. It should include information of when it is and is not appropriate to use that pattern, and the pattern's strengths and weaknesses.
For example, Figure 6.2 describes the well-known Model-View-Controller pattern. This pattern is the basis of interaction management in many web-based systems. The stylized pattern description includes the pattern name, a brief description (with an associated graphical model), and an example of the type of system where the pattern is used (again, perhaps with a graphical model). You should also include information about when the pattern should be used and its advantages and disadvantages. Graphical models of the architecture associated with the MVC pattern are shown in Figures 6.3 and 6.4. These present the architecture from different views-Figure 6.3 is a conceptual view and Figure 6.4 shows a possible run-time architecture when this pattern is used for interaction management in a web-based system.
In a short section of a general chapter, it is impossible to describe all of the generic patterns that can be used in software development. Rather, I present some selected examples of patterns that are widely used and which capture good architectural design principles. I have included some further examples of generic architectural patterns on the book's web pages.
Figure 6.4 Web application architecture using the MVC pattern
<!-- image -->
<!-- image -->
## 6.3.1 Layered architecture
The notions of separation and independence are fundamental to architectural design because they allow changes to be localized. The MVC pattern, shown in Figure 6.2, separates elements of a system, allowing them to change independently. For example, adding a new view or changing an existing view can be done without any changes to the underlying data in the model. The layered architecture pattern is another way of achieving separation and independence. This pattern is shown in Figure 6.5. Here, the system functionality is organized into separate layers, and each layer only relies on the facilities and services offered by the layer immediately beneath it.
This layered approach supports the incremental development of systems. As a layer is developed, some of the services provided by that layer may be made available to users. The architecture is also changeable and portable. So long as its interface is unchanged, a layer can be replaced by another, equivalent layer. Furthermore, when layer interfaces change or new facilities are added to a layer, only the adjacent layer is affected. As layered systems localize machine dependencies in inner layers, this makes it easier to provide multi-platform implementations of an application system. Only the inner, machine-dependent layers need be re-implemented to take account of the facilities of a different operating system or database.
Figure 6.6 is an example of a layered architecture with four layers. The lowest layer includes system support software-typically database and operating system support. The next layer is the application layer that includes the components concerned with the application functionality and utility components that are used by other application components. The third layer is concerned with user interface
| Name | Layered architecture |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Description | Organizes the system into layers with related functionality associated with each layer. A layer provides services to the layer above it so the lowest-level layers represent core services that are likely to be used throughout the system. See Figure 6.6. |
| Example | A layered model of a system for sharing copyright documents held in different libraries, as shown in Figure 6.7. |
| When used | Used when building new facilities on top of existing systems; when the development is spread across several teams with each team responsibility for a layer of functionality; when there is a requirement for multi-level security. |
| Advantages | Allows replacement of entire layers so long as the interface is maintained. Redundant facilities (e.g., authentication) can be provided in each layer to increase the dependability of the system. |
| Disadvantages | In practice, providing a clean separation between layers is often difficult and a high-level layer may have to interact directly with lower-level layers rather than through the layer immediately below it. Performance can be a problem because of multiple levels of interpretation of a service request as it is processed at each layer. |
## Figure 6.5 The layered architecture pattern
management and providing user authentication and authorization, with the top layer providing user interface facilities. Of course, the number of layers is arbitrary. Any of the layers in Figure 6.6 could be split into two or more layers.
Figure 6.7 is an example of how this layered architecture pattern can be applied to a library system called LIBSYS, which allows controlled electronic access to copyright material from a group of university libraries. This has a five-layer architecture, with the bottom layer being the individual databases in each library.
You can see another example of the layered architecture pattern in Figure 6.17 (found in Section 6.4). This shows the organization of the system for mental healthcare (MHC-PMS) that I have discussed in earlier chapters.
<!-- image -->
Figure 6.7 The architecture of the LIBSYS system
■
<!-- image -->
## 6.3.2 Repository architecture
The layered architecture and MVC patterns are examples of patterns where the view presented is the conceptual organization of a system. My next example, the Repository pattern (Figure 6.8), describes how a set of interacting components can share data.
Figure 6.8 The repository pattern The majority of systems that use large amounts of data are organized around a shared database or repository. This model is therefore suited to applications in which data is generated by one component and used by another. Examples of this type of system include command and control systems, management information systems, CAD systems, and interactive development environments for software.
| Name | Repository |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Description | All data in a system is managed in a central repository that is accessible to all system components. Components do not interact directly, only through the repository. |
| Example | Figure 6.9 is an example of an IDE where the components use a repository of system design information. Each software tool generates information which is then available for use by other tools. |
| When used | You should use this pattern when you have a system in which large volumes of information are generated that has to be stored for a long time. You may also use it in data-driven systems where the inclusion of data in the repository triggers an action or tool. |
| Advantages | Components can be independent-they do not need to know of the existence of other components. Changes made by one component can be propagated to all components. All data can be managed consistently (e.g., backups done at the same time) as it is all in one place. |
| Disadvantages | The repository is a single point of failure so problems in the repository affect the whole system. May be inefficiencies in organizing all communication through the repository. Distributing the repository across several computers may be difficult. |
<!-- image -->
Figure 6.9 is an illustration of a situation in which a repository might be used. This diagram shows an IDE that includes different tools to support model-driven development. The repository in this case might be a version-controlled environment (as discussed in Chapter 25) that keeps track of changes to software and allows rollback to earlier versions.
Organizing tools around a repository is an efficient way to share large amounts of data. There is no need to transmit data explicitly from one component to another. However, components must operate around an agreed repository data model. Inevitably, this is a compromise between the specific needs of each tool and it may be difficult or impossible to integrate new components if their data models do not fit the agreed schema. In practice, it may be difficult to distribute the repository over a number of machines. Although it is possible to distribute a logically centralized repository, there may be problems with data redundancy and inconsistency.
In the example shown in Figure 6.9, the repository is passive and control is the responsibility of the components using the repository. An alternative approach, which has been derived for AI systems, uses a 'blackboard' model that triggers components when particular data become available. This is appropriate when the form of the repository data is less well structured. Decisions about which tool to activate can only be made when the data has been analyzed. This model is introduced by Nii (1986). Bosch (2000) includes a good discussion of how this style relates to system quality attributes.
## 6.3.3 Client-server architecture
The repository pattern is concerned with the static structure of a system and does not show its run-time organization. My next example illustrates a very commonly used run-time organization for distributed systems. The Client-server pattern is described in Figure 6.10.
■
| Name | Client-server |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Description | In a client-server architecture, the functionality of the system is organized into services, with each service delivered from a separate server. Clients are users of these services and access servers to make use of them. |
| Example | Figure 6.11 is an example of a film and video/DVD library organized as a client-server system. |
| When used | Used when data in a shared database has to be accessed from a range of locations. Because servers can be replicated, may also be used when the load on a system is variable. |
| Advantages | The principal advantage of this model is that servers can be distributed across a network. General functionality (e.g., a printing service) can be available to all clients and does not need to be implemented by all services. |
| Disadvantages | Each service is a single point of failure so susceptible to denial of service attacks or server failure. Performance may be unpredictable because it depends on the network as well as the system. May be management problems if servers are owned by different organizations. |
Figure 6.10 The client-server pattern A system that follows the client-server pattern is organized as a set of services and associated servers, and clients that access and use the services. The major components of this model are:
1. A set of servers that offer services to other components. Examples of servers include print servers that offer printing services, file servers that offer file management services, and a compile server, which offers programming language compilation services.
2. A set of clients that call on the services offered by servers. There will normally be several instances of a client program executing concurrently on different computers.
3. A network that allows the clients to access these services. Most client-server systems are implemented as distributed systems, connected using Internet protocols.
Client-server architectures are usually thought of as distributed systems architectures but the logical model of independent services running on separate servers can be implemented on a single computer. Again, an important benefit is separation and independence. Services and servers can be changed without affecting other parts of the system.
Clients may have to know the names of the available servers and the services that they provide. However, servers do not need to know the identity of clients or how many clients are accessing their services. Clients access the services provided by a server through remote procedure calls using a request-reply protocol such as the http protocol used in the WWW. Essentially, a client makes a request to a server and waits until it receives a reply.
Figure 6.11 A clientserver architecture for a film library
Figure 6.12 The pipe and filter pattern
<!-- image -->
Figure 6.11 is an example of a system that is based on the client-server model. This is a multi-user, web-based system for providing a film and photograph library. In this system, several servers manage and display the different types of media. Video frames need to be transmitted quickly and in synchrony but at relatively low resolution. They may be compressed in a store, so the video server can handle video compression and decompression in different formats. Still pictures, however, must be maintained at a high resolution, so it is appropriate to maintain them on a separate server.
The catalog must be able to deal with a variety of queries and provide links into the web information system that includes data about the film and video clips, and an e-commerce system that supports the sale of photographs, film, and video clips. The
| Name | Pipe and filter |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Description | The processing of the data in a system is organized so that each processing component (filter) is discrete and carries out one type of data transformation. The data flows (as in a pipe) from one component to another for processing. |
| Example | Figure 6.13 is an example of a pipe and filter system used for processing invoices. |
| When used | Commonly used in data processing applications (both batch- and transaction-based) where inputs are processed in separate stages to generate related outputs. |
| Advantages | Easy to understand and supports transformation reuse. Workflow style matches the structure of many business processes. Evolution by adding transformations is straightforward. Can be implemented as either a sequential or concurrent system. |
| Disadvantages | The format for data transfer has to be agreed upon between communicating transformations. Each transformation must parse its input and unparse its output to the agreed form. This increases system overhead and may mean that it is impossible to reuse functional transformations that use incompatible data structures. |
■
Figure 6.13 An example of the pipe and filter architecture
<!-- image -->
client program is simply an integrated user interface, constructed using a web browser, to access these services.
The most important advantage of the client-server model is that it is a distributed architecture. Effective use can be made of networked systems with many distributed processors. It is easy to add a new server and integrate it with the rest of the system or to upgrade servers transparently without affecting other parts of the system. I discuss distributed architectures, including client-server architectures and distributed object architectures, in Chapter 18.
## 6.3.4 Pipe and filter architecture
My final example of an architectural pattern is the pipe and filter pattern. This is a model of the run-time organization of a system where functional transformations process their inputs and produce outputs. Data flows from one to another and is transformed as it moves through the sequence. Each processing step is implemented as a transform. Input data flows through these transforms until converted to output. The transformations may execute sequentially or in parallel. The data can be processed by each transform item by item or in a single batch.
The name 'pipe and filter' comes from the original Unix system where it was possible to link processes using 'pipes'. These passed a text stream from one process to another. Systems that conform to this model can be implemented by combining Unix commands, using pipes and the control facilities of the Unix shell. The term 'filter' is used because a transformation 'filters out' the data it can process from its input data stream.
Variants of this pattern have been in use since computers were first used for automatic data processing. When transformations are sequential with data processed in batches, this pipe and filter architectural model becomes a batch sequential model, a common architecture for data processing systems (e.g., a billing system). The architecture of an embedded system may also be organized as a process pipeline, with each process executing concurrently. I discuss the use of this pattern in embedded systems in Chapter 20.
An example of this type of system architecture, used in a batch processing application, is shown in Figure 6.13. An organization has issued invoices to customers. Once a week, payments that have been made are reconciled with the invoices. For
<!-- image -->
## Architectural patterns for control
There are specific architectural patterns that reflect commonly used ways of organizing control in a system. These include centralized control, based on one component calling other components, and event-based control, where the system reacts to external events.
http://www.SoftwareEngineering-9.com/Web/Architecture/ArchPatterns/
those invoices that have been paid, a receipt is issued. For those invoices that have not been paid within the allowed payment time, a reminder is issued.
Interactive systems are difficult to write using the pipe and filter model because of the need for a stream of data to be processed. Although simple textual input and output can be modeled in this way, graphical user interfaces have more complex I/O formats and a control strategy that is based on events such as mouse clicks or menu selections. It is difficult to translate this into a form compatible with the pipelining model.
## 6.4 Application architectures
Application systems are intended to meet a business or organizational need. All businesses have much in common-they need to hire people, issue invoices, keep accounts, and so on. Businesses operating in the same sector use common sectorspecific applications. Therefore, as well as general business functions, all phone companies need systems to connect calls, manage their network, issue bills to customers, etc. Consequently, the application systems used by these businesses also have much in common.
These commonalities have led to the development of software architectures that describe the structure and organization of particular types of software systems. Application architectures encapsulate the principal characteristics of a class of systems. For example, in real-time systems, there might be generic architectural models of different system types, such as data collection systems or monitoring systems. Although instances of these systems differ in detail, the common architectural structure can be reused when developing new systems of the same type.
The application architecture may be re-implemented when developing new systems but, for many business systems, application reuse is possible without reimplementation. We see this in the growth of Enterprise Resource Planning (ERP) systems from companies such as SAP and Oracle, and vertical software packages (COTS) for specialized applications in different areas of business. In these systems, a generic system is configured and adapted to create a specific business application.
<!-- image -->
## Application architectures
There are several examples of application architectures on the book's website. These include descriptions of batch data-processing systems, resource allocation systems, and event-based editing systems.
http://www.SoftwareEngineering-9.com/Web/Architecture/AppArch/
For example, a system for supply chain management can be adapted for different types of suppliers, goods, and contractual arrangements.
As a software designer, you can use models of application architectures in a number of ways:
1. As a starting point for the architectural design process If you are unfamiliar with the type of application that you are developing, you can base your initial design on a generic application architecture. Of course, this will have to be specialized for the specific system being developed, but it is a good starting point for design.
2. As a design checklist If you have developed an architectural design for an application system, you can compare this with the generic application architecture. You can check that your design is consistent with the generic architecture.
3. As a way of organizing the work of the development team The application architectures identify stable structural features of the system architectures and in many cases, it is possible to develop these in parallel. You can assign work to group members to implement different components within the architecture.
4. As a means of assessing components for reuse If you have components you might be able to reuse, you can compare these with the generic structures to see whether there are comparable components in the application architecture.
5. As a vocabulary for talking about types of applications If you are discussing a specific application or trying to compare applications of the same types, then you can use the concepts identified in the generic architecture to talk about the applications.
There are many types of application system and, in some cases, they may seem to be very different. However, many of these superficially dissimilar applications actually have much in common, and thus can be represented by a single abstract application architecture. I illustrate this here by describing the following architectures of two types of application:
1. Transaction processing applications Transaction processing applications are database-centered applications that process user requests for information and update the information in a database. These are the most common type of interactive business systems. They are organized in such a way that user actions can't interfere with each other and the integrity of the database is maintained. This
<!-- image -->
<!-- image -->
- class of system includes interactive banking systems, e-commerce systems, information systems, and booking systems.
2. Language processing systems Language processing systems are systems in which the user's intentions are expressed in a formal language (such as Java). The language processing system processes this language into an internal format and then interprets this internal representation. The best-known language processing systems are compilers, which translate high-level language programs into machine code. However, language processing systems are also used to interpret command languages for databases and information systems, and markup languages such as XML (Harold and Means, 2002; Hunter et al., 2007).
I have chosen these particular types of system because a large number of webbased business systems are transaction-processing systems, and all software development relies on language processing systems.
## 6.4.1 Transaction processing systems
Transaction processing (TP) systems are designed to process user requests for information from a database, or requests to update a database (Lewis et al., 2003). Technically, a database transaction is sequence of operations that is treated as a single unit (an atomic unit). All of the operations in a transaction have to be completed before the database changes are made permanent. This ensures that failure of operations within the transaction does not lead to inconsistencies in the database.
From a user perspective, a transaction is any coherent sequence of operations that satisfies a goal, such as 'find the times of flights from London to Paris'. If the user transaction does not require the database to be changed then it may not be necessary to package this as a technical database transaction.
An example of a transaction is a customer request to withdraw money from a bank account using an ATM. This involves getting details of the customer's account, checking the balance, modifying the balance by the amount withdrawn, and sending commands to the ATM to deliver the cash. Until all of these steps have been completed, the transaction is incomplete and the customer accounts database is not changed.
Transaction processing systems are usually interactive systems in which users make asynchronous requests for service. Figure 6.14 illustrates the conceptual architectural structure of TP applications. First a user makes a request to the system through an I/O processing component. The request is processed by some applicationspecific logic. A transaction is created and passed to a transaction manager, which is usually embedded in the database management system. After the transaction manager has ensured that the transaction is properly completed, it signals to the application that processing has finished.
Figure 6.15 The software architecture of an ATM system
<!-- image -->
<!-- image -->
Transaction processing systems may be organized as a 'pipe and filter' architecture with system components responsible for input, processing, and output. For example, consider a banking system that allows customers to query their accounts and withdraw cash from an ATM. The system is composed of two cooperating software components-the ATM software and the account processing software in the bank's database server. The input and output components are implemented as software in the ATM and the processing component is part of the bank's database server. Figure 6.15 shows the architecture of this system, illustrating the functions of the input, process, and output components.
## 6.4.2 Information systems
All systems that involve interaction with a shared database can be considered to be transaction-based information systems. An information system allows controlled access to a large base of information, such as a library catalog, a flight timetable, or the records of patients in a hospital. Increasingly, information systems are web-based systems that are accessed through a web browser.
Figure 6.16 a very general model of an information system. The system is modeled using a layered approach (discussed in Section 6.3) where the top layer supports the user interface and the bottom layer is the system database. The user communications layer handles all input and output from the user interface, and the information retrieval layer includes application-specific logic for accessing and updating the database. As we shall see later, the layers in this model can map directly onto servers in an Internet-based system.
As an example of an instantiation of this layered model, Figure 6.17 shows the architecture of the MHC-PMS. Recall that this system maintains and manages details of patients who are consulting specialist doctors about mental health problems. I have Figure 6.16 Layered information system architecture added detail to each layer in the model by identifying the components that support user communications and information retrieval and access:
<!-- image -->
1. The top layer is responsible for implementing the user interface. In this case, the UI has been implemented using a web browser.
2. The second layer provides the user interface functionality that is delivered through the web browser. It includes components to allow users to log in to the system and checking components that ensure that the operations they use are allowed by their role. This layer includes form and menu management components that present information to users, and data validation components that check information consistency.
3. The third layer implements the functionality of the system and provides components that implement system security, patient information creation and updating, import and export of patient data from other databases, and report generators that create management reports.
<!-- image -->
■
4. Finally, the lowest layer, which is built using a commercial database management system, provides transaction management and persistent data storage.
Information and resource management systems are now usually web-based systems where the user interfaces are implemented using a web browser. For example, e-commerce systems are Internet-based resource management systems that accept electronic orders for goods or services and then arrange delivery of these goods or services to the customer. In an e-commerce system, the application-specific layer includes additional functionality supporting a 'shopping cart' in which users can place a number of items in separate transactions, then pay for them all together in a single transaction.
The organization of servers in these systems usually reflects the four-layer generic model presented in Figure 6.16. These systems are often implemented as multi-tier client server/architectures, as discussed in Chapter 18:
1. The web server is responsible for all user communications, with the user interface implemented using a web browser;
2. The application server is responsible for implementing application-specific logic as well as information storage and retrieval requests;
3. The database server moves information to and from the database and handles transaction management.
Using multiple servers allows high throughput and makes it possible to handle hundreds of transactions per minute. As demand increases, servers can be added at each level to cope with the extra processing involved.
## 6.4.3 Language processing systems
Language processing systems translate a natural or artificial language into another representation of that language and, for programming languages, may also execute the resulting code. In software engineering, compilers translate an artificial programming language into machine code. Other language-processing systems may translate an XML data description into commands to query a database or to an alternative XML representation. Natural language processing systems may translate one natural language to another e.g., French to Norwegian.
A possible architecture for a language processing system for a programming language is illustrated in Figure 6.18. The source language instructions define the program to be executed and a translator converts these into instructions for an abstract machine. These instructions are then interpreted by another component that fetches the instructions for execution and executes them using (if necessary) data from the environment. The output of the process is the result of interpreting the instructions on the input data.
<!-- image -->
Of course, for many compilers, the interpreter is a hardware unit that processes machine instructions and the abstract machine is a real processor. However, for dynamically typed languages, such as Python, the interpreter may be a software component.
Programming language compilers that are part of a more general programming environment have a generic architecture (Figure 6.19) that includes the following components:
1. A lexical analyzer, which takes input language tokens and converts them to an internal form.
2. A symbol table, which holds information about the names of entities (variables, class names, object names, etc.) used in the text that is being translated.
3. A syntax analyzer, which checks the syntax of the language being translated. It uses a defined grammar of the language and builds a syntax tree.
4. A syntax tree, which is an internal structure representing the program being compiled.
<!-- image -->
Figure 6.19 A pipe and filter compiler architecture
<!-- image -->
## Reference architectures
Reference architectures capture important features of system architectures in a domain. Essentially, they include everything that might be in an application architecture although, in reality, it is very unlikely that any individual application would include all the features shown in a reference architecture. The main purpose of reference architectures is to evaluate and compare design proposals, and to educate people about architectural characteristics in that domain.
http://www.SoftwareEngineering-9.com/Web/Architecture/RefArch.html
5. A semantic analyzer that uses information from the syntax tree and the symbol table to check the semantic correctness of the input language text.
6. A code generator that 'walks' the syntax tree and generates abstract machine code.
Other components might also be included which analyze and transform the syntax tree to improve efficiency and remove redundancy from the generated machine code. In other types of language processing system, such as a natural language translator, there will be additional components such as a dictionary, and the generated code is actually the input text translated into another language.
There are alternative architectural patterns that may be used in a language processing system (Garlan and Shaw, 1993). Compilers can be implemented using a composite of a repository and a pipe and filter model. In a compiler architecture, the symbol table is a repository for shared data. The phases of lexical, syntactic, and semantic analysis are organized sequentially, as shown in Figure 6.19, and communicate through the shared symbol table.
This pipe and filter model of language compilation is effective in batch environments where programs are compiled and executed without user interaction; for example, in the translation of one XML document to another. It is less effective when a compiler is integrated with other language processing tools such as a structured editing system, an interactive debugger or a program prettyprinter. In this situation, changes from one component need to be reflected immediately in other components. It is better, therefore, to organize the system around a repository, as shown in Figure 6.20.
This figure illustrates how a language processing system can be part of an integrated set of programming support tools. In this example, the symbol table and syntax tree act as a central information repository. Tools or tool fragments communicate through it. Other information that is sometimes embedded in tools, such as the grammar definition and the definition of the output format for the program, have been taken out of the tools and put into the repository. Therefore, a syntax-directed editor can check that the syntax of a program is correct as it is being typed and a prettyprinter can create listings of the program in a format that is easy to read.
<!-- image -->
<!-- image -->
## KEY POINTS
- ■ A software architecture is a description of how a software system is organized. Properties of a system such as performance, security, and availability are influenced by the architecture used.
- ■ Architectural design decisions include decisions on the type of application, the distribution of the system, the architectural styles to be used, and the ways in which the architecture should be documented and evaluated.
- ■ Architectures may be documented from several different perspectives or views. Possible views include a conceptual view, a logical view, a process view, a development view, and a physical view.
- ■ Architectural patterns are a means of reusing knowledge about generic system architectures. They describe the architecture, explain when it may be used, and discuss its advantages and disadvantages.
- ■ Commonly used architectural patterns include Model-View-Controller, Layered Architecture, Repository, Client-server, and Pipe and Filter.
- ■ Generic models of application systems architectures help us understand the operation of applications, compare applications of the same type, validate application system designs, and assess large-scale components for reuse.
- ■ Transaction processing systems are interactive systems that allow information in a database to be remotely accessed and modified by a number of users. Information systems and resource management systems are examples of transaction processing systems.
- ■ Language processing systems are used to translate texts from one language into another and to carry out the instructions specified in the input language. They include a translator and an abstract machine that executes the generated language.
## FURTHER READING
Software Architecture: Perspectives on an Emerging Discipline. This was the first book on software architecture and has a good discussion on different architectural styles. (M. Shaw and D. Garlan, Prentice-Hall, 1996.)
Software Architecture in Practice, 2nd ed. This is a practical discussion of software architectures that does not oversell the benefits of architectural design. It provides a clear business rationale explaining why architectures are important. (L. Bass, P. Clements and R. Kazman, Addison-Wesley, 2003.)
'The Golden Age of Software Architecture' This paper surveys the development of software architecture from its beginnings in the 1980s through to its current usage. There is little technical content but it is an interesting historical overview. (M. Shaw and P. Clements, IEEE Software, 21 (2), March-April 2006.) http://dx.doi.org/10.1109/MS.2006.58.
Handbook of Software Architecture . This is a work in progress by Grady Booch, one of the early evangelists for software architecture. He has been documenting the architectures of a range of software systems so you can see reality rather than academic abstraction. Available on the Web and intended to appear as a book. http://www.handbookofsoftwarearchitecture.com/.
## EXERCISES
- 6.1. When describing a system, explain why you may have to design the system architecture before the requirements specification is complete.
- 6.2. You have been asked to prepare and deliver a presentation to a non-technical manager to justify the hiring of a system architect for a new project. Write a list of bullet points setting out the key points in your presentation. Naturally, you have to explain what is meant by system architecture.
- 6.3. Explain why design conflicts might arise when designing an architecture for which both availability and security requirements are the most important non-functional requirements.
- 6.4. Draw diagrams showing a conceptual view and a process view of the architectures of the following systems:
An automated ticket-issuing system used by passengers at a railway station.
A computer-controlled video conferencing system that allows video, audio, and computer data to be visible to several participants at the same time.
A robot floor cleaner that is intended to clean relatively clear spaces such as corridors. The cleaner must be able to sense walls and other obstructions.
<!-- image -->
- 6.5. Explain why you normally use several architectural patterns when designing the architecture of a large system. Apart from the information about patterns that I have discussed in this chapter, what additional information might be useful when designing large systems?
- 6.6. Suggest an architecture for a system (such as iTunes) that is used to sell and distribute music on the Internet. What architectural patterns are the basis for this architecture?
- 6.7. Explain how you would use the reference model of CASE environments (available on the book's web pages) to compare the IDEs offered by different vendors of a programming language such as Java.
- 6.8. Using the generic model of a language processing system presented here, design the architecture of a system that accepts natural language commands and translates these into database queries in a language such as SQL.
- 6.9. Using the basic model of an information system, as presented in Figure 6.16, suggest the components that might be part of an information system that allows users to view information about flights arriving and departing from a particular airport.
- 6.10. Should there be a separate profession of 'software architect' whose role is to work independently with a customer to design the software system architecture? A separate software company would then implement the system. What might be the difficulties of establishing such a profession?
## REFERENCES
Bass, L., Clements, P. and Kazman, R. (2003). Software Architecture in Practice, 2nd ed. Boston: Addison-Wesley.
Berczuk, S. P. and Appleton, B. (2002). Software Configuration Management Patterns: Effective Teamwork, Practical Integration. Boston: Addison-Wesley.
Booch, G. (2009). 'Handbook of software architecture'. Web publication. http:/ /www.handbookofsoftwarearchitecture.com/.
Bosch, J. (2000). Design and Use of Software Architectures. Harlow, UK: Addison-Wesley.
Buschmann, F., Henney, K. and Schmidt, D. C. (2007a). Pattern-oriented Software Architecture Volume 4: A Pattern Language for Distributed Computing. New York: John Wiley &amp; Sons.
Buschmann, F., Henney, K. and Schmidt, D. C. (2007b). Pattern-oriented Software Architecture Volume 5: On Patterns and Pattern Languages. New York: John Wiley &amp; Sons.
Buschmann, F., Meunier, R., Rohnert, H. and Sommerlad, P. (1996). Pattern-oriented Software Architecture Volume 1: A System of Patterns. New York: John Wiley &amp; Sons.
■
Clements, P., Bachmann, F., Bass, L., Garlan, D., Ivers, J., Little, R., Nord, R. and Stafford, J. (2002). Documenting Software Architectures: Views and Beyond. Boston: Addison-Wesley.
Coplien, J. H. and Harrison, N. B. (2004). Organizational Patterns of Agile Software Development. Englewood Cliffs, NJ: Prentice Hall.
Gamma, E., Helm, R., Johnson, R. and Vlissides, J. (1995). Design Patterns: Elements of Reusable Object-Oriented Software. Reading, Mass.: Addison-Wesley.
Garlan, D. and Shaw, M. (1993). 'An introduction to software architecture'. Advances in Software Engineering and Knowledge Engineering, 1 1-39.
Harold, E. R. and Means, W. S. (2002). XML in a Nutshell. Sebastopol. Calif.: O'Reilly.
Hofmeister, C., Nord, R. and Soni, D. (2000). Applied Software Architecture. Boston: AddisonWesley.
Hunter, D., Rafter, J., Fawcett, J. and Van Der Vlist, E. (2007). Beginning XML, 4th ed. Indianapolis, Ind.: Wrox Press.
Kircher, M. and Jain, P. (2004). Pattern-Oriented Software Architecture Volume 3: Patterns for Resource Management. New York: John Wiley &amp; Sons.
Krutchen, P. (1995). 'The 4+1 view model of software architecture'. IEEE Software, 12 (6), 42-50.
Lange, C. F. J., Chaudron, M. R. V. and Muskens, J. (2006). 'UML software description and architecture description'. IEEE Software, 23 (2), 40-6.
Lewis, P. M., Bernstein, A. J. and Kifer, M. (2003). Databases and Transaction Processing: An Application-oriented Approach. Boston: Addison-Wesley.
Martin, D. and Sommerville, I. (2004). 'Patterns of interaction: Linking ethnomethodology and design'. ACM Trans. on Computer-Human Interaction, 11 (1), 59-89.
Nii, H. P . (1986). 'Blackboard systems, parts 1 and 2'. AI Magazine, 7 (3 and 4), 38-53 and 62-9.
Schmidt, D., Stal, M., Rohnert, H. and Buschmann, F. (2000). Pattern-Oriented Software Architecture Volume 2: Patterns for Concurrent and Networked Objects. New York: John Wiley &amp; Sons.
Shaw, M. and Garlan, D. (1996). Software Architecture: Perspectives on an Emerging Discipline. Englewood Cliffs, NJ: Prentice Hall.
Usability group. (1998). 'Usability patterns'. Web publication. http://www.it.bton.ac.uk/cil/usability/patterns/.

BIN
proj_level_reading/User_Analysis/Policy_Analysis/how_to_commericalized_legalizing_healthcare_product/split.pdf Normal file
View File

Binary file not shown.

36
proj_level_reading/User_Analysis/Policy_Analysis/how_to_commericalized_legalizing_healthcare_product/text_extract.py Normal file
View File

@@ -0,0 +1,36 @@
from pathlib import Path
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions, AcceleratorOptions
from docling.document_converter import DocumentConverter, PdfFormatOption
def main():
input_doc_path = Path("se_arch.pdf")
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.do_table_structure = True
accelerator_options = AcceleratorOptions(device="cpu")
converter = DocumentConverter(
format_options={
InputFormat.PDF: PdfFormatOption(
pipeline_options=pipeline_options,
)
}
)
conversion_result = converter.convert(input_doc_path)
doc = conversion_result.document
md = doc.export_to_markdown()
output_path = Path("se_arch.md")
output_path.write_text(md, encoding="utf-8")
# doc_conversion_secs = conversion_result.timings["pipeline_total"].times
print(f"Saved markdown to {output_path}")
# print(f"Conversion secs: {doc_conversion_secs}")
if __name__ == "__main__":
main()

2073
workspace/sprint_1_2/Design_Material/API_docs/API_CONTRACT_DRAFT.md Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
workspace/sprint_1_2/Design_Material/API_docs/Analysis Sequence.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 254 KiB

1103
workspace/sprint_1_2/Design_Material/CI_CD_docs/CI_CD_DEPLOYMENT_PIPELINE.md Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
workspace/sprint_1_2/Design_Material/CI_CD_docs/ci_cd_flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 184 KiB

818
workspace/sprint_1_2/Design_Material/DATA_INGESTION/RELATIONAL_DB_SCHEMA_SPEC.md Normal file
View File

@@ -0,0 +1,818 @@
## PlantUML Deliverable 1 — Logical ER / Schema Diagram
Recommended design file:
```text
PILOT_PROJECT/workspace/sprint_1_2/Design_Material/DATA-INGESTION/RELATIONAL_DB_SCHEMA_SPEC.md
```
Use this ER/schema diagram as the primary schema diagram.
```plantuml
@startuml "VKIST_Relational_DB__ER_Schema"
left to right direction
skinparam linetype ortho
entity "clinician_users" as clinician_users {
* id : uuid <<PK>>
--
display_name : text
role : enum <<not null>>
created_at : timestamp
updated_at : timestamp
}
entity "patient_cases" as patient_cases {
* id : uuid <<PK>>
--
patient_hash : text <<unique>>
case_hash : text <<unique>>
metadata_json : json
created_at : timestamp
}
entity "diagnostic_sessions" as diagnostic_sessions {
* id : uuid <<PK>>
--
patient_case_id : uuid <<FK>>
clinician_user_id : uuid <<FK>>
status : enum <<not null>>
review_decision_id : uuid <<FK nullable>>
created_at : timestamp
updated_at : timestamp
}
entity "image_assets" as image_assets {
* id : uuid <<PK>>
--
session_id : uuid <<FK>>
asset_type : enum <<not null>>
bucket_name : text
object_key : text <<uuid-only>>
sha256_hash : text <<not null>>
size_bytes : bigint
content_type : text
created_at : timestamp
}
entity "scan_frames" as scan_frames {
* id : uuid <<PK>>
--
diagnostic_session_id : uuid <<FK>>
source_asset_id : uuid <<FK>>
extracted_asset_id : uuid <<FK nullable>>
frame_index : int <<default 0>>
width : int
height : int
modality : enum
created_at : timestamp
}
entity "calibrations" as calibrations {
* id : uuid <<PK>>
--
scan_frame_id : uuid <<FK unique>>
pixel_spacing_x_mm : decimal
pixel_spacing_y_mm : decimal
source : enum
confidence : decimal nullable
}
entity "analysis_jobs" as analysis_jobs {
* id : uuid <<PK>>
--
diagnostic_session_id : uuid <<FK>>
scan_frame_id : uuid <<FK unique>>
model_registry_entry_id : uuid <<FK nullable>>
status : enum <<not null>>
trace_id : uuid
idempotency_key : text
created_at : timestamp
started_at : timestamp nullable
completed_at : timestamp nullable
failed_at : timestamp nullable
}
entity "pipeline_steps" as pipeline_steps {
* id : uuid <<PK>>
--
analysis_job_id : uuid <<FK>>
step_name : text
status : enum
started_at : timestamp nullable
completed_at : timestamp nullable
error_code : text nullable
error_message : text nullable
metadata_json : json
}
entity "model_registry" as model_registry {
* id : uuid <<PK>>
--
task_name : enum <<not null>>
model_name : text <<not null>>
version : text <<not null>>
default : boolean
enabled : boolean
input_spec_json : json
output_spec_json : json
}
entity "model_artifacts" as model_artifacts {
* id : uuid <<PK>>
--
model_registry_entry_id : uuid <<FK>>
artifact_uri : text <<not null>>
sha256_hash : text <<not null>>
format : text
created_at : timestamp
}
entity "preprocessed_images" as preprocessed_images {
* id : uuid <<PK>>
--
scan_frame_id : uuid <<FK>>
analysis_job_id : uuid <<FK>>
artifact_id : uuid <<FK nullable>>
resize_w : int
resize_h : int
normalization : text
created_at : timestamp
}
entity "angle_predictions" as angle_predictions {
* id : uuid <<PK>>
--
analysis_job_id : uuid <<FK unique>>
predicted_class : enum
confidence : decimal
created_at : timestamp
}
entity "inflammation_predictions" as inflammation_predictions {
* id : uuid <<PK>>
--
analysis_job_id : uuid <<FK unique>>
detected : boolean
confidence : decimal
created_at : timestamp
}
entity "segmentation_masks" as segmentation_masks {
* id : uuid <<PK>>
--
analysis_job_id : uuid <<FK unique>>
artifact_id : uuid <<FK>>
class_labels_json : json
created_at : timestamp
}
entity "measurements" as measurements {
* id : uuid <<PK>>
--
analysis_job_id : uuid <<FK>>
target_class : text
value_mm : decimal
pixel_count : bigint nullable
confidence : decimal nullable
created_at : timestamp
}
entity "synovitis_grades" as synovitis_grades {
* id : uuid <<PK>>
--
analysis_job_id : uuid <<FK unique>>
suggested_grade : int <<0..3>>
label : text
confidence : decimal
basis_json : json
created_at : timestamp
}
entity "review_decisions" as review_decisions {
* id : uuid <<PK>>
--
diagnostic_session_id : uuid <<FK unique>>
analysis_job_id : uuid <<FK>>
clinician_user_id : uuid <<FK>>
status : enum <<not null>>
clinician_grade : int nullable <<0..3>>
comment : text nullable
digital_signature_ref : text nullable
created_at : timestamp
}
entity "audit_ledger_entries" as audit_ledger_entries {
* id : uuid <<PK>>
--
session_id : uuid <<FK>>
job_id : uuid <<FK nullable>>
event_type : text
previous_hash : text nullable
audit_hash : text <<not null>>
hash_inputs_json : json
created_at : timestamp
}
clinician_users ||--o{ diagnostic_sessions : creates
patient_cases ||--o{ diagnostic_sessions : owns
diagnostic_sessions ||--o{ image_assets : owns
diagnostic_sessions ||--o{ scan_frames : contains
image_assets ||--o{ scan_frames : source_asset
image_assets ||--o{ scan_frames : extracted_asset
scan_frames ||--o| calibrations : has
diagnostic_sessions ||--o{ analysis_jobs : runs
analysis_jobs ||--o{ pipeline_steps : executes
analysis_jobs }o--|| model_registry : uses
model_registry ||--o{ model_artifacts : publishes
analysis_jobs ||--o{ preprocessed_images : transforms
analysis_jobs ||--o| angle_predictions : produces
analysis_jobs ||--o| inflammation_predictions : produces
analysis_jobs ||--o| segmentation_masks : produces
analysis_jobs ||--o{ measurements : produces
analysis_jobs ||--o| synovitis_grades : produces
diagnostic_sessions ||--o| review_decisions : finalizes
analysis_jobs ||--o| review_decisions : supports
clinician_users ||--o{ review_decisions : signs
diagnostic_sessions ||--o{ audit_ledger_entries : appends
analysis_jobs ||--o{ audit_ledger_entries : appends
note right of image_assets
ArtifactReference is generated from image_assets + object store metadata.
end note
note bottom of audit_ledger_entries
Append-only. PostgreSQL triggers block UPDATE/DELETE.
end note
@enduml
```
## PlantUML Deliverable 2 — Chen Notation ER Diagram
Use this as the Chen-notation ER diagram. It emphasizes entities, relationships, and cardinality. Attribute ovals show key attributes only to keep the diagram readable.
```plantuml
@startchen "VKIST_Relational_DB__Chen_Notation"
skinparam linetype ortho
' Entities with their nested attributes
entity ClinicianUser {
id <<key>>
display_name
role
}
entity PatientCase {
id <<key>>
patient_hash
case_hash
}
entity DiagnosticSession {
id <<key>>
status
created_at
}
entity ImageAsset {
id <<key>>
asset_type
sha256_hash
object_key
}
entity ScanFrame {
id <<key>>
frame_index
width
height
}
entity Calibration {
id <<key>>
pixel_spacing
source
confidence
}
entity AnalysisJob {
id <<key>>
status
trace_id
}
entity PipelineStep {
id <<key>>
step_name
status
}
entity ModelRegistryEntry {
id <<key>>
task_name
model_name
version
}
entity ModelArtifact {
id <<key>>
artifact_uri
sha256_hash
}
entity AnglePrediction {
id <<key>>
predicted_class
confidence
}
entity InflammationPrediction {
id <<key>>
detected
confidence
}
entity SegmentationMask {
id <<key>>
artifact_id
class_labels
}
entity Measurement {
id <<key>>
target_class
value_mm
}
entity SynovitisGrade {
id <<key>>
suggested_grade
confidence
}
entity ReviewDecision {
id <<key>>
status
clinician_grade
}
entity AuditLedgerEntry {
id <<key>>
event_type
audit_hash
}
' Relationships
relationship creates {
}
relationship owns {
}
relationship stores {
}
relationship contains {
}
relationship calibrates {
}
relationship runs {
}
relationship executes {
}
relationship uses {
}
relationship publishes {
}
relationship produces_angle {
}
relationship produces_inflam {
}
relationship produces_mask {
}
relationship measures {
}
relationship grades {
}
relationship user_signs {
}
relationship session_signs {
}
relationship job_signs {
}
relationship session_appends {
}
relationship job_appends {
}
' Connectivity & Participation Mapping
creates -1- ClinicianUser
creates -N- DiagnosticSession
owns -1- PatientCase
owns -N- DiagnosticSession
stores -1- DiagnosticSession
stores -N- ImageAsset
contains -1- DiagnosticSession
contains -N- ScanFrame
calibrates -1- ScanFrame
calibrates -(0,1)- Calibration
runs -1- DiagnosticSession
runs -N- AnalysisJob
executes -1- AnalysisJob
executes -N- PipelineStep
uses -N- AnalysisJob
uses -1- ModelRegistryEntry
publishes -1- ModelRegistryEntry
publishes -N- ModelArtifact
produces_angle -1- AnalysisJob
produces_angle -(0,1)- AnglePrediction
produces_inflam -1- AnalysisJob
produces_inflam -(0,1)- InflammationPrediction
produces_mask -1- AnalysisJob
produces_mask -(0,1)- SegmentationMask
measures -1- AnalysisJob
measures -N- Measurement
grades -1- AnalysisJob
grades -(0,1)- SynovitisGrade
user_signs -1- ClinicianUser
user_signs -N- ReviewDecision
session_signs -1- DiagnosticSession
session_signs -(0,1)- ReviewDecision
job_signs -1- AnalysisJob
job_signs -(0,1)- ReviewDecision
session_appends -1- DiagnosticSession
session_appends -N- AuditLedgerEntry
job_appends -1- AnalysisJob
job_appends -N- AuditLedgerEntry
@endchen
```
* Refractor & Splited version for easy to visualizing
### Part 1: Core Clinical & Diagnostic Subsystem
```
@startchen "VKIST_Clinical_Diagnostic_Subsystem"
skinparam linetype ortho
entity ClinicianUser {
id <<key>>
display_name
role
}
entity PatientCase {
id <<key>>
patient_hash
case_hash
}
entity DiagnosticSession {
id <<key>>
status
created_at
}
entity ImageAsset {
id <<key>>
asset_type
sha256_hash
object_key
}
entity ScanFrame {
id <<key>>
frame_index
width
height
}
entity Calibration {
id <<key>>
pixel_spacing
source
confidence
}
entity ReviewDecision {
id <<key>>
status
clinician_grade
}
relationship Creates_Session {
}
relationship Owns_Session {
}
relationship Stores_Asset {
}
relationship Contains_Frame {
}
relationship Calibrates_Frame {
}
relationship User_Signs {
}
relationship Session_Signs {
}
ClinicianUser -1- Creates_Session
Creates_Session -N- DiagnosticSession
PatientCase -1- Owns_Session
Owns_Session -N- DiagnosticSession
DiagnosticSession -1- Stores_Asset
Stores_Asset -N- ImageAsset
DiagnosticSession -1- Contains_Frame
Contains_Frame -N- ScanFrame
ScanFrame -1- Calibrates_Frame
Calibrates_Frame -(0,1)- Calibration
ClinicianUser -1- User_Signs
User_Signs -N- ReviewDecision
DiagnosticSession -1- Session_Signs
Session_Signs -(0,1)- ReviewDecision
@endchen
```
### Part 2: AI/ML Pipeline & Audit Subsystem
```
@startchen "VKIST_ML_Pipeline_Audit_Subsystem"
skinparam linetype ortho
entity DiagnosticSession {
id <<key>>
}
entity ReviewDecision {
id <<key>>
}
entity AnalysisJob {
id <<key>>
status
trace_id
}
entity PipelineStep {
id <<key>>
step_name
status
}
entity ModelRegistryEntry {
id <<key>>
task_name
model_name
version
}
entity ModelArtifact {
id <<key>>
artifact_uri
sha256_hash
}
entity AnglePrediction {
id <<key>>
predicted_class
confidence
}
entity InflammationPrediction {
id <<key>>
detected
confidence
}
entity SegmentationMask {
id <<key>>
artifact_id
class_labels
}
entity Measurement {
id <<key>>
target_class
value_mm
}
entity SynovitisGrade {
id <<key>>
suggested_grade
confidence
}
entity AuditLedgerEntry {
id <<key>>
event_type
audit_hash
}
relationship Runs_Job {
}
relationship Executes_Step {
}
relationship Uses_Model {
}
relationship Publishes_Artifact {
}
relationship Produces_Angle {
}
relationship Produces_Inflam {
}
relationship Produces_Mask {
}
relationship Measures_Metrics {
}
relationship Grades_Synovitis {
}
relationship Job_Signs {
}
relationship Session_Appends {
}
relationship Job_Appends {
}
DiagnosticSession -1- Runs_Job
Runs_Job -N- AnalysisJob
AnalysisJob -1- Executes_Step
Executes_Step -N- PipelineStep
AnalysisJob -N- Uses_Model
Uses_Model -1- ModelRegistryEntry
ModelRegistryEntry -1- Publishes_Artifact
Publishes_Artifact -N- ModelArtifact
AnalysisJob -1- Produces_Angle
Produces_Angle -(0,1)- AnglePrediction
AnalysisJob -1- Produces_Inflam
Produces_Inflam -(0,1)- InflammationPrediction
AnalysisJob -1- Produces_Mask
Produces_Mask -(0,1)- SegmentationMask
AnalysisJob -1- Measures_Metrics
Measures_Metrics -N- Measurement
AnalysisJob -1- Grades_Synovitis
Grades_Synovitis -(0,1)- SynovitisGrade
AnalysisJob -1- Job_Signs
Job_Signs -(0,1)- ReviewDecision
DiagnosticSession -1- Session_Appends
Session_Appends -N- AuditLedgerEntry
AnalysisJob -1- Job_Appends
Job_Appends -N- AuditLedgerEntry
@endchen
```
## Migration / Schema Plan
### Step 1 — Logical schema freeze
Create the design spec first. Include:
- ER/schema PlantUML,
- Chen PlantUML,
- table list,
- FK map,
- indexes,
- constraints,
- NFR/UC traceability.
### Step 2 — SQLite Sprint 1_2 migrations
Implement minimal SQLite migrations for:
- `clinician_users`
- `patient_cases`
- `diagnostic_sessions`
- `image_assets`
- `scan_frames`
- `calibrations`
- `analysis_jobs`
- `pipeline_steps`
- `model_registry`
- `model_artifacts`
- `preprocessed_images`
- `angle_predictions`
- `inflammation_predictions`
- `segmentation_masks`
- `measurements`
- `synovitis_grades`
- `review_decisions`
- `audit_ledger_entries`
SQLite constraints:
- UUIDs stored as `TEXT`.
- `CHECK` constraints for grade ranges, enum-like statuses, and non-empty hashes.
- Foreign keys enabled.
- `audit_ledger_entries` treated as append-only at application layer.
### Step 3 — PostgreSQL target migrations
Add PostgreSQL migrations with:
- `uuid` type,
- `jsonb`,
- `CHECK` constraints,
- `NOT NULL` FKs,
- indexes for FK and query paths,
- append-only triggers on `audit_ledger_entries`,
- RLS policies where required,
- optional `postgis` schema readiness for future spatial markers.
### Step 4 — Object storage contract
Add object storage metadata contract:
```text
image_assets.object_key
image_assets.bucket_name
image_assets.sha256_hash
image_assets.content_type
image_assets.size_bytes
```
Rules:
- UUID-only object keys.
- No PHI in object keys.
- Store binary payloads in object storage.
- Store only metadata and safe references in DB.
## Implementation Steps
1. Confirm whether Sprint 1_2 uses SQLite only or PostgreSQL-ready migrations from the start.
2. Write `PILOT_PROJECT/workspace/sprint_1_2/Design_Material/DATA-INGESTION/RELATIONAL_DB_SCHEMA_SPEC.md`.
3. Add ER/schema PlantUML.
4. Add Chen notation PlantUML.
5. Add table-by-table schema with types, constraints, indexes, and FK rules.
6. Add NFR/UC traceability matrix.
7. Add open decisions and migration plan.
8. After design approval, implement migrations and repositories.
## Open Decisions
1. `patients` table: Sprint 1_2 uses `patient_cases` with hashes only; FR-25 may need a fuller PHI-bearing `patients` table under strict compliance.
2. `review_decisions`: single latest decision table vs append-only decision revisions.
3. `artifact_references`: generated value only vs physical table for presigned URL cache.
4. `preprocessed_images`: keep as metadata table or fold into `image_assets` with `asset_type = preprocessed`.
5. `pipeline_steps`: include per-model VRAM/runtime metrics in Sprint 1_2 or add later.
6. `review_decisions.digital_signature_ref`: store only a reference hash/credential ID, never private keys.
7. Q4 anomaly telemetry: DB metadata only, with raw tensors/masks in isolated object storage.
## Acceptance Criteria
- [ ] ER/schema PlantUML covers all OOP domain objects from Sprint 1_2.
- [ ] Chen notation PlantUML covers core entities, relationships, and cardinalities.
- [ ] Schema includes all required tables from `OOP_DATA_ENGINEERING_SPEC.md`.
- [ ] FK map supports upload, analysis, review, audit, and finalization flows.
- [ ] Constraints enforce grade ranges, status values, hash presence, and human sign-off.
- [ ] NFR traceability covers privacy, immutability, air-gap, explainability, and latency requirements.
- [ ] Object storage boundary is explicit: DB stores refs/checksums, not binary payloads.
- [ ] Design supports SQLite PoC and PostgreSQL/PostGIS target migration path.

361
workspace/sprint_1_2/Design_Material/DATA_INGESTION/data-ingestion-pipeline-etl-design-first-draft.md Normal file
View File

@@ -0,0 +1,361 @@
# Data Ingestion Pipeline ETL First Draft Plan — VKIST MSK Sprint 1_2
## Plan Status
- Source plan file requested: `.kilo/plans/data-ingestion-pipeline-etl-first-draft-plan.md`
- Requested source plan file was missing in workspace.
- This file is now the implementation source of truth for the Data Ingestion ETL plan.
- Primary ingestion design source: `PILOT_PROJECT/workspace/sprint_1_2/Design_Material/DATA-INGESTION/data-ingestion-pipeline-etl-first-draft-plan.md`
- OOP/data-concept source of truth: `PILOT_PROJECT/workspace/sprint_1_2/Design_Material/data_engineering/OOP_DATA_ENGINEERING_SPEC.md`
---
## Goal
Design and implement a small-first, incrementally scalable Data Ingestion ETL pipeline for VKIST MSK Sprint 1_2.
The ingestion design must match the OOP data and concept model in `OOP_DATA_ENGINEERING_SPEC.md`, especially:
- Core domain objects
- Runtime agents/services
- Workflow
- SQLite metadata model
- Cloud object storage layout
- API contract objects
- Validation rules
- Sprint 1_2 acceptance criteria
Target path:
```text
DICOM/image upload → secure artifact storage → frame extraction → preprocessing → vision inference → structured result objects → SQLite metadata → S3-compatible artifact refs → browser mask preview
```
---
## Source Context
### Ingestion Design Context
Use `PILOT_PROJECT/workspace/sprint_1_2/Design_Material/DATA-INGESTION/data-ingestion-pipeline-etl-first-draft-plan.md` as the current ingestion design baseline.
Key ingestion design points:
- ETL phases: `Extract`, `Transform`, `Load`
- Sprint 1_2 PoC stack: FastAPI + SQLite + S3-compatible object store
- Production upgrade path: FastAPI → Redis queue → worker pool → Triton → PostgreSQL/PostGIS + S3 + observability
- No PHI in filenames, object keys, URLs, logs, telemetry, or response paths
- UUID-based object keys and artifact references
- Mock and real PyTorch/Triton-compatible inference adapters
- Stable API responses with `session_id`, `job_id`, `trace_id`, and `audit_hash`
### OOP Data Engineering Context
Use `PILOT_PROJECT/workspace/sprint_1_2/Design_Material/data_engineering/OOP_DATA_ENGINEERING_SPEC.md` as the data/concept source of truth.
Sprint 1_2 scope:
```text
DICOM/image upload → frame extraction → preprocessing → vision inference → structured result objects → SQLite metadata → cloud object storage artifact refs → browser mask preview
```
Sprint 1_2 includes:
- Single-frame DICOM upload
- Standard image upload fallback
- SQLite for structured metadata
- Cloud object service for binary artifacts
- FastAPI API contracts
- PyTorch-compatible inference adapters
- Structured OOP domain model for sessions, frames, jobs, predictions, masks, measurements, and audit records
Sprint 1_2 excludes:
- Multi-frame DICOM series
- Triton runtime
- GraphRAG
- EMR sync
- Socratic safety agents
- Full PWA workspace
- Collaboration/annotations
---
## OOP Boundary
```text
Domain objects = clinical and analysis facts.
Agents/services = runtime workers that transform facts.
Repositories = SQLite persistence adapters.
Artifact stores = S3-compatible binary storage adapters.
Orchestrators = coordinate use cases and workflow state.
```
---
## Required Domain Objects
The Data Ingestion design must produce, persist, or reference these OOP objects from `OOP_DATA_ENGINEERING_SPEC.md`.
### Clinical/session objects
- `ClinicianUser`
- `PatientCase`
- `DiagnosticSession`
- `ReviewDecision`
- `AuditLedgerEntry`
### Ingestion/artifact objects
- `ImageAsset`
- `ScanFrame`
- `Calibration`
- `ArtifactReference`
### Analysis/job objects
- `AnalysisJob`
- `PipelineStep`
- `ModelRegistryEntry`
- `ModelArtifact`
- `PreprocessedImage`
### Prediction/result objects
- `AnglePrediction`
- `InflammationPrediction`
- `SegmentationMask`
- `Measurement`
- `SynovitisGrade`
---
## Required Runtime Agents / Services
The ingestion implementation must align with these runtime roles from `OOP_DATA_ENGINEERING_SPEC.md`.
- `DICOMIngestAgent`
- `accept_upload(file) -> ImageAsset`
- `extract_frame(image_asset) -> ScanFrame`
- `extract_calibration(image_asset) -> Calibration`
- `ImageUploadIngestAgent`
- `accept_upload(file) -> ImageAsset`
- `build_scan_frame(image_asset) -> ScanFrame`
- `FramePreprocessor`
- CLAHE, resize, normalization, tensor preparation
- `AngleValidatorAgent`
- Predicts `AnglePrediction`
- Validates supported angle branch
- `ROICropperAgent`
- Optional PoC/no-op first
- `VisionPipelineAgent`
- Coordinates `run(session_id, frame_id) -> AnalysisJob`
- `InferenceRunner`
- Loads and runs PyTorch-compatible adapters
- `MeasurementAgent`
- Converts mask pixels to mm using `Calibration`
- `SeverityScorerAgent`
- Maps measurements to `SynovitisGrade`
- `ModelRegistryAgent`
- Selects approved model names and versions
- `ArtifactStoreAgent`
- Stores raw and derived artifacts
- Returns `ImageAsset` / `ArtifactReference`
- `LedgerWriterAgent`
- Appends immutable `AuditLedgerEntry`
---
## ETL Design Aligned to OOP Objects
### Phase 1 — Extract
Purpose:
Accept upload, quarantine, hash, store raw artifact, and create canonical ingestion metadata.
Inputs:
- `POST /api/v1/sessions/{session_id}/frames`
- Single-frame DICOM or standard image upload
Components:
- `UploadController`
- `QuarantineStorage`
- `HashingService`
- `ArtifactStoreAgent`
- `DICOMIngestAgent`
- `ImageUploadIngestAgent`
- `LedgerWriterAgent`
OOP outputs:
- `ImageAsset`
- `ScanFrame`
- `Calibration`
- `AuditLedgerEntry`
Validation:
- Accept single-frame DICOM
- Extract pixel array
- Extract pixel spacing if available
- Accept common image formats
- Generate synthetic/fallback calibration for standard images
- Reject unreadable DICOM
- No PHI in filenames, object keys, URLs, logs, telemetry, or response paths
### Phase 2 — Transform
Purpose:
Convert the extracted frame into clinical analysis facts.
Components:
- `AnalysisJobOrchestrator`
- `FramePreprocessor`
- `AngleValidatorAgent`
- `ROICropperAgent`
- `InferenceRunner`
- `MeasurementAgent`
- `SeverityScorerAgent`
- `SafetyRouter`
OOP outputs:
- `AnalysisJob`
- `PipelineStep`
- `PreprocessedImage`
- `AnglePrediction`
- `InflammationPrediction`
- `SegmentationMask`
- `Measurement`
- `SynovitisGrade`
- `AuditLedgerEntry`
Validation:
- Every result links to `analysis_job_id`
- Mask artifact links to `artifact_id`
- Measurements use calibration when available
- Grade range is `0..3`
- Unsupported angle, low confidence, missing calibration, or artifact correction flags are preserved
### Phase 3 — Load
Purpose:
Persist structured facts and return safe artifact references.
Components:
- `SQLiteMetadataRepository`
- `ArtifactReferenceBuilder`
- `AnalysisResultAssembler`
- `AuditHashBuilder`
- `ObservabilityEmitter`
OOP outputs:
- Stable API response
- Browser mask preview refs
- Immutable audit chain
Validation:
- Every structured object has UUID primary key
- Every analysis result links to `session_id` and `job_id`
- Every audit entry has `audit_hash`
- Audit hash inputs include:
- `session_id`
- `job_id`
- model versions
- prediction IDs
- artifact hashes
- review decision when present
---
## SQLite Metadata Alignment
Use the Sprint 1_2 SQLite model from `OOP_DATA_ENGINEERING_SPEC.md:1058`.
Required tables:
- `diagnostic_sessions`
- `image_assets`
- `scan_frames`
- `calibrations`
- `analysis_jobs`
- `pipeline_steps`
- `model_registry`
- `model_artifacts`
- `angle_predictions`
- `inflammation_predictions`
- `segmentation_masks`
- `measurements`
- `synovitis_grades`
- `review_decisions`
- `audit_ledger_entries`
Additive PoC columns allowed by ingestion design:
- `analysis_jobs.trace_id`
- `analysis_jobs.idempotency_key`
- `pipeline_steps.error_code`
- `audit_ledger_entries.previous_hash`
Do not add PHI-bearing columns or original filenames as required fields.
---
## Object Storage Alignment
Use the UUID-only storage layout from `OOP_DATA_ENGINEERING_SPEC.md:1240`.
```text
s3://vkist-poc/
sessions/
{session_id}/
source/
{asset_id}.dcm
{asset_id}.png
frames/
{frame_id}.png
masks/
{mask_id}.png
preprocessed/
{preprocessed_id}.npy
audit/
{audit_id}.json
```
Ingestion design may include these additional UUID-keyed artifact prefixes:
```text
preprocessed/
overlays/
outputs/
```
Rules:
- No patient name in object key
- No raw patient ID in object key
- No timestamp-only object key
- Use UUID for all keys
- Store SHA-256 hash for every artifact
- Store metadata in SQLite
- SQLite/Postgres stores refs only, not binary image payloads
---
## API Contract Alignment
Use the OOP API contract objects from `OOP_DATA_ENGINEERING_SPEC.md:1274`.
Required Sprint 1_2 endpoints:
```text
POST /api/v1/sessions
GET /api/v1/sessions/{session_id}
POST /api/v1/sessions/{session_id}/frames
POST /api/v1/analysis-jobs
GET /api/v1/analysis-jobs/{job_id}
GET /api/v1/analysis-jobs/{job_id}/steps
PATCH /api/v1/sessions/{session_id}/review
```
Create Session Request must include:
```json
{
"patient_hash": "sha256_patient_hash",
"case_hash": "sha256_case_hash",
"clinician_user_id": "uuid"
}
```
Upload Frame Request:
```text
POST /api/v1/sessions/{session_id}/frames
Content-Type: multipart/form-data
file: .dcm or image
```
Upload Frame Response must expose:
- `frame_id`
- `source_asset`
- `calibration`
Analysis Job Response must expose stable objects:
- `job_id`
- `status`
- `angle`
- `inflammation`
- `segmentation_mask`
- `measurements`
- `synovitis_grade`
- safe artifact references

186
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/CONTEXT_FR_25_UC_ELIT.md Normal file
View File

@@ -0,0 +1,186 @@
BELOW is the consolidated structural baseline engineering reference document tracking all architectural constraints, system interactions, and discovered sub-components for the **FR-25 Synovitis Grading Engine**.
---
# Context_FR_25_UC.md
## 1. Context, Mission Boundary & Core Rationale
### 1.1 Scope Identification
* **Target Core Functional Requirement:** `FR-25` (ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch / Synovitis Grading Engine).
* **Primary System Boundary:** The workspace acts as a strict secure diagnostic execution wrapper. In order to manage systemic liability and avoid black-box compliance failures, the advanced multi-agent checking modules (**LLM Explainer**, **BERT Hallucination Detector**, and **RAG-Referee**) are restricted from handling generic application operations. They are encapsulated entirely as **Internal Layered Workspace Subsystems** dedicated exclusively to validating human-AI coordination logs for `FR-25`.
### 1.2 Engineering Value Optimization
* **The Clinical Chasm:** In high-volume Vietnamese public clinics, specialists face intensive shift demands often exceeding 100 scans daily. Basic AI setups risk inducing automated checklist fatigue or introducing catastrophic blindness loops if human clinicians simply blind-concur with machine estimations.
* **The System Solution:** By engineering clear internal state boundaries separating standard CRUD processing from multi-tier validation agents, the system systematically handles four concurrent behavioral quadrants. It forces explicit human verification loops during disagreements, cross-references findings against un-biased clinical knowledge nodes, and maintains diagnostic speed metrics without degrading data correctness limits.
---
## 2. Structural Actor Profile Mapping
| Actor Name | Canonical Identifier | Role Scope & Operational Profile within FR-25 Boundary |
| --- | --- | --- |
| **Diagnostic Radiologist** | `Rad (UP5)` | **Primary Human Actor:** National-level clinical expert (Specialist II / Professor, age 40–60+). Holds ultimate medical accountability; validates and signs off pixel segmentations, metrics, and grading summaries. |
| **Hospital EMR System** | `EMR` | **External System Actor:** Recipient database server. Receives finalized JSON structures and signed clinical data logs over localized network pipes post human validation. |
| **VKIST Vision Grader Engine** | `Grader` | **External System Actor:** Foundation deep-learning array (ConvNeXt/MedSAM). Ingests raw frame parameters and produces pixel segmentations, thickness markers (mm), and classification tensors. |
---
## 3. Discovered Use Cases (4-Quadrant Framework)
### 3.1 Core Image Data Intake & Workflow Baselines
* **`UC-48376` (Load Patient Scan Session):** Ingests incoming image frames, maps spatial structures, and activates local session states.
* **`UC-47988` (Review Suggested Synovitis Grade):** Renders the initial classification summary panel (Grades 0-3) alongside color-coded segmentation overlaps.
* **`UC-92006` (Finalize & Sign Electronic Record):** Seals the session data via localized human cryptographic signing steps before dispatching payload JSON logs to the hospital storage sinks.
### 3.2 Quadrant 1: True Agreement Flow (AI Correct / Doctor Correct)
* **`UC-25776` (Generate GradCAM & CoT Explanation Panel):** The internal LLM Explainer checks raw pixel masks and maps multi-modal prompt matrices to output clear, human-scannable rationales.
* **`UC-02423` (Log High-Trust Concur Block):** Encapsulates the corresponding Chain-of-Thought logs confirming human-machine consensus into a structured block to verify system state traceability.
### 3.3 Quadrant 2: Automation Override Risk Loop (AI Correct / Doctor Oversight)
* **`UC-22159` (Trigger Conversational Circuit Breaker):** Intercepts standard workspace finalization pathways if high mouse click adjustments or text conflict markers indicate user friction or ambiguity.
* **`UC-55146` (Facilitate Socratic Reasoning Dialogue):** Initiates an inline workspace chat panel, prompting the specialist to evaluate spatial discrepancies or vascular metrics versus the machine's model inputs.
* **`UC-74821` (Monitor Drift via BERT Sub-Layer):** Scans active conversation tokens continuously to detect illogical claims or contextual drift during active discussion.
* **`UC-65473` (Arbitrate Evidence via RAG-Referee):** Intervenes if human-machine disputes reach an impasse, bypassing active chat logs to pull verified medical guidelines directly from fixed reference sources.
### 3.4 Quadrant 3: Clinician Subservience Risk Loop (AI Hallucinates / Doctor Correct)
* **`UC-25637` (Expose Pixel-Level Activation Logic):** Displays granular layer activations and weight scores when a clinician actively contests a machine grade suggestion.
* **`UC-60739` (Isolate Visual Noise/Artifacts):** Provides on-screen cursor brushes for the specialist to isolate and mask out clutter variables like acoustic shadowing or bone scattering.
* **`UC-62864` (Commit Validated Ground-Truth Record):** Re-runs data logs through the verification referee, updating final reports to show human superiority while saving the masked framework for subsequent model training runs.
### 3.5 Quadrant 4: Double Blind Failure Loop (AI Faulty / Doctor Biased)
* **`UC-35956` (Activate Clinical Investigation Mode):** Transitions the user interface environment instantly to a strict manual tracking orientation when low vision confidence values align with zero-match RAG search responses.
* **`UC-47796` (Execute Structured Morphology Annotation):** Displays a standardized template forcing manual plotting of novel structural modifications or unrecognized lesion variations.
* **`UC-01580` (Serialize Session to Telemetry Queue):** Packages unencrypted image tensors, coordinate indices, and clinical commentary blocks into localized storage pipelines, bypassing standard EMR charts to flag data directly for software engineering team review.
---
## 4. Master PlantUML System Compilation
```plantuml
@startuml
' Settings & Aesthetic Optimization
left to right direction
skin rose
' External Actors
actor "Diagnostic Radiologist (UP5)" as Rad
actor "Hospital EMR System" as EMR << System >>
actor "VKIST Vision Grader Engine" as Grader << System >>
' System Boundary
rectangle "VKIST MSK Workspace (FR-25: Synovitis Grading Scope)" {
' Core Viewing & Data Intake Pipelines
usecase "UC-48376\nLoad Patient Scan Session" as UC_Load
usecase "UC-47988\nReview Suggested Synovitis Grade (0-3)" as UC_Review
usecase "UC-92006\nFinalize & Sign Electronic Record" as UC_Finalize
' Sub-Boundary for the Internal Cognitive/Multi-Agent Subsystems
rectangle "Internal Cognitive & Validation Stack" {
' Q1: True Agreement Use Cases
usecase "UC-25776\nGenerate GradCAM & CoT Explanation Panel" as UC_Q1_Explain
usecase "UC-02423\nLog High-Trust Concur Block" as UC_Q1_Log
' Q2: Automation Override Risk Use Cases
usecase "UC-22159\nTrigger Conversational Circuit Breaker" as UC_Q2_Intercept
usecase "UC-55146\nFacilitate Socratic Reasoning Dialogue" as UC_Q2_Socratic
usecase "UC-74821\nMonitor Drift via BERT Sub-Layer" as UC_Q2_BERT
usecase "UC-65473\nArbitrate Evidence via RAG-Referee" as UC_Q2_Arbiter
' Q3: Clinician Subservience Risk Use Cases
usecase "UC-25637\nExpose Pixel-Level Activation Logic" as UC_Q3_Expose
usecase "UC-60739\nIsolate Visual Noise/Artifacts" as UC_Q3_Isolate
usecase "UC-62864\nCommit Validated Ground-Truth Record" as UC_Q3_Commit
' Q4: Double Blind Failure Use Cases
usecase "UC-35956\nActivate Clinical Investigation Mode" as UC_Q4_Escalate
usecase "UC-47796\nExecute Structured Morphology Annotation" as UC_Q4_Annotate
usecase "UC-01580\nSerialize Session to Telemetry Queue" as UC_Q4_Queue
}
}
' Human-System Interactions
Rad --> UC_Load
Rad --> UC_Review
Rad --> UC_Finalize
' Q2, Q3 & Q4 Interaction Entrypoints
Rad --> UC_Q2_Socratic : Argue observations
Rad --> UC_Q3_Isolate : Tag artifacts
Rad --> UC_Q4_Annotate : Document manual findings
' Machine-to-Machine Pipelines
Grader --> UC_Load : Feeds vision tensors & initial scores
' Internal Use Case Associations & Extends
UC_Load ..> UC_Q1_Explain : <<include>>
UC_Q1_Explain ..> UC_Q1_Log : <<include>>
' Q2 Loop Connections
UC_Review <.. UC_Q2_Intercept : <<extend>> (If clinician friction detected)
UC_Q2_Intercept ..> UC_Q2_Socratic : <<include>>
UC_Q2_Socratic ..> UC_Q2_BERT : <<include>>
UC_Q2_BERT ..> UC_Q2_Arbiter : <<extend>> (If impasse or semantic drift caught)
' Q3 Loop Connections
UC_Review <.. UC_Q3_Expose : <<extend>> (If clinician contests AI score)
UC_Q3_Expose ..> UC_Q3_Isolate : <<include>>
UC_Q3_Isolate ..> UC_Q3_Commit : <<include>>
' Q4 Loop Connections
UC_Review <.. UC_Q4_Escalate : <<extend>> (If low confidence & empty RAG)
UC_Q4_Escalate ..> UC_Q4_Annotate : <<include>>
UC_Q4_Annotate ..> UC_Q4_Queue : <<include>>
' Final Hand-off Synchronization
UC_Finalize ..> EMR : Sync standardized structural JSON data
@enduml
```
---
## 5. Blueprint Cross-Traceability Matrices
### 5.1 Scenario-to-Agent Mapping Tracking Matrix
This structural trace links the user behavior scenarios directly back to the active internal validation elements processing the loop.
```
+---------------------------+-----------------------+-------------------------+-------------------------+
| Interaction Scenario | Core Vision Component | Dialogue Safety Layer | Arbitration Safety Node |
+---------------------------+-----------------------+-------------------------+-------------------------+
| Q1: True Agreement | VKIST Vision Grader | LLM Explainer (CoT Log) | RAG-Referee (Clear) |
| Q2: Automation Override | VKIST Vision Grader | Socratic Circuit Breaker| RAG-Referee (Active) |
| Q3: Clinician Subservience| Feature Map Vis | Objective Critic Dialog | RAG-Referee (Active) |
| Q4: Double Blind Edge Case| Anomaly State Ingest | Exploratory Morphology | Telemetry Retrain Queue |
+---------------------------+-----------------------+-------------------------+-------------------------+
```
### 5.2 Functional Requirements Validation Trace
* **ULTS-FR-25 Criteria Trace 01:** The system must process initial classifications using pixel-percentage markers. Checked by: `UC_Load` $\rightarrow$ `UC_Review`.
* **ULTS-FR-25 Criteria Trace 02:** System designs must enforce a circuit breaker step if user actions indicate diagnostic mismatch or context drift. Checked by: `UC_Q2_Intercept` $\rightarrow$ `UC_Q2_BERT`.
* **ULTS-FR-25 Criteria Trace 03:** Sessions documenting unmapped anatomical variants must bypass standard hospital charts and stream records directly to optimization sinks. Checked by: `UC_Q4_Escalate` $\rightarrow$ `UC_Q4_Queue`.
---
## 6. Downstream UIX & Specification Target Anchors
This baseline file establishes structural anchor configurations for subsequent product development phases:
1. **Phase 4 (Workspace Dashboard Wireframing):** Wireframe templates must reserve split-screen display blocks: one side hosting the medical canvas with artifact isolation tools (`UC_Q3_Isolate`), and an inline section mapping socratic messaging interactions (`UC_Q2_Socratic`).
2. **Use Case Specification Drafting:** Individual use case descriptions can reference this anchor block to maintain absolute consistency regarding precondition bounds, primary exception vectors, and hand-off synchronization parameters (`EMR`).
---
*This engineering reference document accurately captures the system boundaries finalized during the requirement discovery sprint.*

180
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/Insight_note.md Normal file
View File

@@ -0,0 +1,180 @@
### Insight-Note - @Đạt Trần Tiến (Daves Tran)
→ Additionally we shall develop the app follow this manner: PWA - progressive web app
- UP-6 insight (suggest the insight for converting toward FRs)
- Insight - to FR-draft 1
- Core Insight 1: The Information Bottleneck
- Formulated Pain Point
- **User Vulnerability:** Vietnamese Physiotherapists struggle to accurately target internal tissue pathologies during physical therapy sessions.
- **Root Cause:** Diagnosing medical doctors rarely or poorly pass digital DICOM imaging streams down the operational chain, providing only brief, low-context paper or text-based prescription sheets.
- **Negative Impact:** Clinicians are forced to execute high-intensity therapeutic modalities semi-blindly over estimated surface anatomy, drastically reducing treatment precision and patient efficacy.
- Target Structural Keywords
- `{information-clarification & context clarification}`
- `{from the prescribe → detect where to treat}`
- Functional Requirements Blueprint
- **The Ingestion & Context Clarification Pipeline:** The platform must feature an integrated Optical Character Recognition (OCR) scanner tool optimized for mobile tablet arrays. When a PT receives a text-only sheet, the system scans the raw text, extracts localized shorthand clinical terms, and cross-references them with centralized clinical guidelines to generate immediate context clarification regarding structural contraindications.
- **Automated Spatial Target Generation ("Prescribe → Guide on Detect the Region of Treatment"):**
- Your database architecture must map abstract text instructions to specific coordinate layers. When a text prescription is parsed (e.g., *"Ultrasound therapy, left shoulder"*), the system can:
- automatically triggers a default, rotatable 3D musculoskeletal target field, highlighting the structural depth and biological tissue boundaries where the treatment must physically occur.
- Generating suggestion guidance on how to interpret the prescrbe under PT knowledge-base + suggest the certain treatment methodology for referential value
- Core Insight 2: The Cross-Domain Literacy Gap
- Formulated Pain Point
- **User Vulnerability:** Vietnamese Physiotherapists struggle to accurately interpret raw diagnostic findings and seamlessly coordinate with prescribing medical specialists.
- **Root Cause:** Their foundational training is rooted entirely in kinetic biomechanics, which completely mismatches the physician’s world of complex radiological pixel data. This structural literacy gap is severely compounded by a massive 84% foreign language deficit and zero academic background in evaluating clinical statistics or research methodologies.
- **Negative Impact:** The communication mismatch creates high inter-departmental silos, forces a reliance on subjective clinical guesswork, and increases the risk of deploying highly ineffective or contraindicated treatment tracks.
- Target Structural Keywords
- `{Cross-Domain Knowledge Translator Between Clinicians & Specialist}`
- `{Educating Channel / Communication medium}`
- **Functional Requirements Blueprint**
- **Cross-Domain Knowledge Translation Canvas:** Your frontend rendering engine must not display a raw, uninterpreted grayscale DICOM viewport. The system must feature a visual abstraction layer that automatically translates multi-slice pixel matrices and annotations into an interactive 3D musculoskeletal medium. Complex radiological data points are remapped into intuitive anatomical indicators (e.g., muscle layer depth maps, color-coded inflammation zones) that line up natively with the PT's biomechanical domain knowledge.
- **Asynchronous Bidirectional Communication Medium:** Because local medical regulations strictly bar technicians from editing primary physician diagnosis records, the collaborative workspace must provide an isolated "Clinical Observation & Progress Flagging" backchannel. The PT interacts with the workspace by pinning tactile assessment data directly onto the shared 3D scan canvas, which compiles an objective, standardized data summary that can be pushed seamlessly to the physician's review dashboard.
- **The Visual Patient-Educating Channel:** To address the locomotive health education requirement, the workspace must feature a decoupled "Patient View" mode switch. This toggle filters out dense clinical indicators and transforms the active 3D biomechanical model into a simplified, clear educational medium. The therapist utilizes this channel to visually demonstrate joint mechanics and injury zones directly to the patient, replacing blind compliance with objective spatial understanding.
###
- **Insight to FR draft 2**
To ensure our engineering team does not waste resources rebuilding duplicate features, we need to carefully cross-reference this **Physiotherapist (PT) Blueprint** with our previous **Rheumatologist & Orthopedic Surgeon Workspace (UP-7)**.
Below is a structural overlap analysis, followed by the refined, non-overlapping Functional Requirements written strictly from the PT’s unique clinical point of view.
#### Part 1: Overlap & Delta Analysis (UP-7 vs. PT Workspace)
Our primary goal is to ensure the PT requirements capture **functional differences**, not just terminology differences.
### 🏢 What is Overlapped (Shared Infrastructure)
- **The Asynchronous Communication Medium vs. UP-7 FR-02 (Voice Memo/JSON Timeline):** Both requirements solve the same technical problem: asynchronous communication via metadata layers over a shared canvas. They should be unified into a single backend thread module.
- **The Visual Patient-Educating Channel vs. UP-7 FR-04 & FR-05 (Adaptive 3D & Sandbox Link):** The code needed to switch to a simplified 3D viewport or hand over a view to a patient is identical to the underlying architecture we designed for the doctor's profile.
### ⚡ What is Unique to the PT Context (The Real Deltas)
- **Upstream Data Ingestion:** Doctors *create* the DICOM and write text prescriptions. PTs *receive* the raw text and have to parse it. The OCR ingestion pipeline is $100\%$ unique to the PT workflow.
- **Text-to-3D Coordinate Projection:** Doctors map 2D DICOM coordinates to 3D. PTs need to map **abstract text descriptions** (e.g., *"Supraspinatus tendinitis"*) to 3D coordinates on a model when the raw DICOM is missing.
- **Biomechanics vs. Radiology:** Doctors look for raw structural or inflammatory data. PTs look for kinematic impact (e.g., muscle depth layers, range-of-motion constraints, therapy execution depths).
### Part 2: Refined, Non-Overlapping PT Functional Requirements
#### FR-PT-01: Client-Side WebML Prescription Parser (TensorFlow.js)
- **PT Point of View:** "Patients walk in with a crumpled piece of text-based paper from the doctor. I need to instantly parse what treatment to give them without sending their medical notes to an insecure external cloud server."
- **Technical & Demography Pivot:** Instead of heavy, costly cloud-based OCR APIs, this runs entirely in the mobile web browser. To keep sensitive health data strictly private under **Decree 13/2023/ND-CP**, no images leave the phone.
- **Functional Scope:**
- The PWA (progressive web-app) must use a lightweight, browser-optimized `MobileNetV2` text-segmentation model via TensorFlow.js to scan text via the phone's native camera stream (`getUserMedia`).
- The script must parse Vietnamese localized shorthand clinical terms directly on-device to extract the targeted joint zone, prescribed therapy modality (e.g., Ultrasound, Shockwave), and frequency.
- **Instant Safety Warning:** The client-side logic immediately processes the extracted words against a lightweight dictionary to trigger a prominent warning panel if any structural contraindications exist (e.g., severe osteoporosis warnings for manual manipulation).
#### FR-PT-02: Zero-GPU Text-to-3D Target Mapping Framework
- **PT Point of View:** "When the doctor provides zero digital X-ray files, I have to guess how deep the tissue pathology is based on their text notes. I need a clear visual guide on my phone, even if it's an old device."
- **Technical & Demography Pivot:** Running a live, mathematically intense 3D translation matrix inside a mobile browser on a legacy, weak-GPU phone will drop frame rates and crash. We implement a **Hybrid Dual-Engine** directly in the PWA.
- **Functional Scope:**
- **High-Spec Profile (Three.js):** If the browser passes a WebGL capabilities test, the abstract text tokens parsed in FR-PT-01 are mapped to spatial coordinates on an interactive 3D bone/muscle model.
- **Low-Spec Profile (CPU-Bound Sprite Animator):** If the device's GPU is flagged as outdated, the system halts Three.js execution. It fetches a pre-rendered 36-frame flat image sequence (a 360-degree turntable shot of the musculoskeletal target). The phone's CPU simply switches the index of the visible 2D image based on the PT's swipe gestures, creating a zero-GPU "3D rotation" effect.
- The system dynamically draws an SVG vector shape highlight over the target area to indicate precisely which tissue layer depth (superficial skin vs. deep muscle belly) the therapy must focus on.
#### FR-PT-03: Biomechanical Kinetic Overlay & Muscle Depth Mapping
- **PT Point of View:** "Doctors care about bone structural alignment. I care about the kinetic soft-tissue layers, muscle fibers, and where exactly to place my physical therapy machine probes."
- **Technical & Demography Pivot:** Since we cannot use native OS GPU layers or native haptic engines in a standard PWA context, we rely on pure CSS layout composition to avoid interface lag.
- **Functional Scope:**
- The canvas view must provide a dedicated **Kinetic Overlay Toggle**. This maps a colorful, transparent cross-section depth map ($1\text{cm}$ to $5\text{cm}$ color coding) directly over the target treatment region.
- Rather than relying on heavy WebGL shader calculations, the app dynamically appends lightweight, text-based HTML `<svg>` paths detailing muscle cross-sections on top of the base image viewport.
- This allows the PT to visualize the estimated soft-tissue depth to calculate the correct angle of approach when placing ultrasound transducers or laser therapy devices on the patient's body.
#### FR-PT-04: Isolated Data-Segregated Observation & Progress Tracking Track
- **PT Point of View:** "Legally, I cannot change the primary doctor’s medical diagnosis. But as I work with the patient daily, I need to track their range-of-motion improvements and flag pain triggers that the doctor should see before their next follow-up."
- **Technical & Demography Pivot:** To satisfy both local medical regulations and the strict access control requirements of **Decree 13/2023/ND-CP**, data tracks must be isolated.
- **Functional Scope:**
- The system implements strict role-based data encapsulation. The PT frontend interface operates on a **Read-Only** schema regarding the doctor's primary diagnostic charts or annotations.
- The PWA provides a distinct **Kinetic Tracking Channel**. The PT can tap the screen to place "Kinetic Progress Pins" onto a separate workspace layer.
- Each pin logs localized, chronological metrics: Range of Motion (ROM) angles, subjective pain indices ($1\text{--}10$), and local tissue behavior notes. This timeline sub-packet is serialized as text data and pushed directly to the physician's tracking panel without mutating the primary medical file.
#### FR-PT-05: DOM-Mirrored Kinetic Demonstration (Patient Education Mode)
- **PT Point of View:** "When doing manual therapy, poor patients often resist or tense up because they don't understand their joint mechanics. I need to show them exactly why they are hurting using their own legacy phones, without the app stuttering."
- **Technical & Demography Pivot:** Emulating dynamic bone impingements in real-time WebGL on a patient's low-end phone causes extreme overheating. We move the animation burden from the GPU to simple DOM manipulation.
- **Functional Scope:**
- The PWA features a dedicated "Patient Demonstration Mode" with a clean, low-density layout interface.
- The view presents a split layout: a static anatomical image on one side, and a simple html Range-of-Motion slider on the other.
- As the PT moves the slider to match the patient’s physical arm or leg position, the app cycles through a lightweight array of cached 2D illustrations. This visual progression dynamically demonstrates joint flexion and extension, color-coding the exact soft tissues that are tightening or impinging. This gives the patient an immediate visual understanding of their pain using $0\%$ GPU processing power.
#### Low-Cost PWA Technical Architecture Overview
![Screenshot 2026-06-04 at 09.30.46.png](User-Research%20Result/Screenshot_2026-06-04_at_09.30.46.png)
#### Engineering Architecture Stack for MVP:
- **Frontend Core:** React.js configured as an installable PWA with a robust Service Worker for aggressive caching, optimizing performance for patchy hospital Wi-Fi networks.
- **Data Encryption:** WebCrypto API on the client side to securely wrap sensitive patient details before syncing with a local Vietnamese host (e.g., Viettel IDC) to ensure compliance with Decree 13.
- **Graphics Delivery:** Hybrid WebGL-to-DOM rendering logic, ensuring that poor patients with legacy CPU-strong/GPU-weak phones receive the exact same educational data via lightweight 2D frame-switching.
- UP-7 insight (suggest the insight for converting toward FRs)
- Some keywords & insight on **Rheumatologist & Orthopedic Surgeon** from the user-profile
- Who they are: senior specialist that `ultimate consumers of the diagnostic imaging data and the primary architects of the patient's comprehensive treatment plan.` → they are the must character in the patient’s journey & patient shall have to interact with them & they shall interact with multiple patients
- They have to work with multiple information on user’s profile & pathologies → synthesize to have a picture of patients & yeild the treatment journey & treatment strategy & handle the legal & ethical & patient’s safetiness & outcome
- Understand the clinical implication + patient’s psychology + ready to explain & spend-time to explain with patient & debunk misinformation - but while they still have tight-time constrain
- They may not known surely what patient’s are doing before reach toward them → harder to form the patient’s pathologies and harder to form diagnosing-picture & put them under a broken interaction & challenging case where patient may come with compilcations that exacerbating the conditions
- They less-interest in shallow ML algorithm for identify the fracture where they can do , but interest more on consultative & deep while fast analysis & predictive (like explain the root-cause & the pathologies pattern & the potential adjustment - covering edge_case of miss-diagnosing)
- They also interest with `a massive potential force multiplier for patient education, provided it **visually translates complex DICOM data into beautifully simple formats the patient can instantly understand**, thereby saving precious consultation minutes for more personalized discussion on treatment plan. (while doctors are assure the model are faithful & accurate)`
- These clincians `need the platform to automatically aggregate highly fragmented patient data (historical X-rays, recent MRIs, scattered lab results) into a single, unified, rapid-consumption dashboard to exponentially expedite their clinical decision-making process.`
- From Insight toward FR
#### FR-01: Haptic-Assisted Touch Viewport & Edge-Snapping Magnifier
- **User Insight:** Rheumatologists and Orthopedic Surgeons require pixel-level accuracy to calculate structural joint metrics (e.g., Cobb angles, joint space narrowing). On a compact 6-inch mobile screen, human fingers naturally obscure these fine anatomical landmarks.
- **Engineering Feasibility:** High (9/10). Utilizes native iOS/Android low-latency graphics canvas and built-in vibration APIs.
- **Functional Scope:**
- **Touch Viewport:** Renders a single DICOM viewport optimized for native multi-touch gestures (pinch-to-zoom, two-finger pan, single-finger window/level adjustments).
- **Floating Lens:** Activating an annotation tool and pressing down must trigger a floating, high-magnification "lens" widget positioned $150\text{px}$ vertically above the touch point to bypass finger obstruction.
- **Edge-Snapping:** Incorporates a lightweight, client-side edge-detection algorithm (Canny/Hough transform). When drawing, the crosshairs automatically snap to the nearest high-contrast bone boundary, confirmed by a localized native haptic pulse.
#### FR-02: Asynchronous Voice-Over Annotation & Timeline Canvas
- **User Insight:** Clinicians navigate highly fragmented, fast-paced hospital rounds and surgical schedules in Vietnamese facilities. Coordinating live, simultaneous multi-user phone calls is functionally unfeasible, yet basic text messaging lacks spatial anatomical context.
- **Engineering Feasibility:** High (8/10). Replaces complex real-time WebSockets with an offline-first, asynchronous data synchronization model suited for patchy hospital Wi-Fi networks.
- **Functional Scope:**
- **Metadata Recorder:** Captures microphone input while recording all viewport coordinate state changes ($X, Y$ positions, zoom vectors, panning arrays, and hand-drawn vectors) instead of recording a heavy video file.
- **Interactive Playback:** Compiles these telemetry inputs into a serialized JSON timeline file. When the receiving doctor opens the case memo, the app replays the sender’s exact viewport transformations and vector drawing steps synchronized with the audio track.
- **Threaded Replays:** Supports nested, asynchronous audio/canvas replies directly inside the specific case file workspace.
#### FR-03: Progressive Disclosure Sheets & Native Workflow Alerts
- **User Insight:** Displaying automated medical guidelines (e.g., Kellgren-Lawrence grading profiles) alongside a high-fidelity image on a mobile screen causes severe cognitive overload.
- **Engineering Feasibility:** High (9/10). Uses highly optimized, native OS interface layouts and lightweight push services (FCM/APNS) that run efficiently on both flagship and mid-tier Android devices.
- **Functional Scope:**
- **Single-Focus Layout:** Dedicates $100\%$ of the background viewport strictly to the active DICOM canvas.
- **Progressive Bottom-Sheet:** Confines automated clinical telemetry, AI-driven objective calculations, and reference guidelines within an expandable native Bottom-Sheet component. Supports three swipe states: $25\%$ peek view, $60\%$ detailed data view, and $100\%$ full-screen deep dive.
- **Deep-Linked Push Notifications:** Triggers a native OS push alert when a case update occurs, deep-linking the receiving doctor directly into the specific case viewport configuration state.
#### FR-04: Hardware-Adaptive 3D Musculoskeletal Synchronization Engine
- **User Insight:** Patients struggle to interpret abstract 2D X-ray slices, which directly hinders their locomotive health literacy. The platform must connect 2D pathologies to an intuitive 3D visualization without crashing the devices of low-income or rural patients utilizing legacy phone chipsets.
- **Engineering Feasibility:** High (8/10). Dual-Engine Framework. The system executes a client-side feature detection script probing WebGL and GPU vendor extensions (filtering out low-end units like Mali-T, Adreno 3xx, or PowerVR Rogue architectures).
- **Functional Scope:**
- **Profile A (High-Performance WebGL Engine):** Maps 2D DICOM coordinates onto a standardized, lightweight 3D skeletal mesh running on an embedded cross-platform WebGL/Three.js engine. Tapping a pathology highlights the isolated 3D node in real time.
- **Profile B (CPU-Bound Sprite-Sheet Fallback):** Bypasses WebGL entirely if weak GPU flags are triggered. The system downloads a pre-compiled, 36-frame turntable "sprite sheet" of the model (pre-rendered at $10^\circ$ increments on the cloud backend). The client phone uses its stable CPU to index and switch the visible frame based on the patient's swipe gestures, creating a zero-GPU 3D rotation effect.
#### FR-05: Sensitive Data Sandbox & Patient Share Portal (Decree 13/2023/ND-CP Compliant)
- **User Insight:** Patients need clean, accessible, jargon-free medical information on their personal devices post-consultation without dealing with complex medical document readers or risking leakages of their sensitive health histories.
- **Engineering Feasibility:** Moderate (8/10). Strictly aligned with **Vietnam's Decree 13/2023/ND-CP** requirements for processing sensitive personal data (health status and clinical records).
- **Functional Scope:**
- **Explicit Consent Check:** The portal cannot render or process the patient packet until a native, explicit "Opt-In Consent" click-action is logged and cryptographically recorded from the patient, conforming to Decree 13 legal consent parameters.
- **Data Sanitization & Server-Side Flattening:** Strips away raw DICOM arrays, institutional metadata, and backend telemetry. If a `LOW_GPU` profile is active, the local cloud server flattens all clinician vector overlays directly into a compressed static JPEG to offload rendering tasks from weak patient browsers.
- **Decentralized Local AES-256 Encryption:** In accordance with Decree 13 mandates for technical protection measures, the app must encrypt the patient's packet using localized AES-256 bit keys.
- **Time-Expiring Tokenized Access:** Generates a unique QR code or deep link mapped to a one-time token with a $14\text{-day}$ Time-To-Live (TTL). When scanned over standard local 4G, it loads an adaptive dashboard in $\le 2.0\text{ seconds}$ hosting only the simplified locomotive health summaries and clinician voice memos.
### Updated Technical Blueprint & Architecture Summary
![Screenshot 2026-06-04 at 09.31.42.png](User-Research%20Result/Screenshot_2026-06-04_at_09.31.42.png)
### Updated Recommended Target MVP Tech Stack
- **Cross-Platform Interface:** Flutter (Dart) or React Native (TypeScript) to optimize code reusability across Vietnam's divided OS market.
- **DICOM Framework:** OFFIS DCMTK compiled to native C++ mobile binaries via platform channels.
- **3D & Hybrid Visualization Subsystem:** An inline WebView context using vanilla JavaScript. The script evaluates graphics-pipe telemetry and dynamically switches rendering branches between Three.js (WebGL) and optimized CSS/DOM-level image switching (Sprite-Sheet).
- **Data Compliance Module:** Client-side encryption using localized cryptographic plugins. All production cloud infrastructure, file caches, and backend web databases must be hosted on local cloud server providers (e.g., Viettel IDC, VNPT, or local AWS/GCP regions) to fully satisfy local data protection audit requirements under Decree 13.

59
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/Q1 True Agreement.md Normal file
View File

@@ -0,0 +1,59 @@
# Q1: True Agreement
(AI Correct / Doctor Correct)
Layered Three-Tier ML Stack Performance Impact (Your Proposed Design): Explainable Baseline Sync: The VKIST Grader computes the numerical matrices & the GradCAM. The LLM Explainer parses the raw segmentation parameters + GradCAM and automatically generates an interactive diagnostic draft chat panel & LLM based on the GradCAM + RAG-knowledge + the raw-ultrasound to explain the VKIST-grader. The RAG-Referee confirms zero clinical guidelines variance, and logs a high-trust concur structural block. <note both LLM have to record back the Chain-of-Though for explain why the LLM’s agree & allow the result)
```planuml
@startuml
' Settings
left to right direction
skin rose
' Actors
actor "Diagnostic Radiologist (UP5)" as Rad
actor "Hospital EMR System" as EMR << System >>
' System Boundary
rectangle "VKIST MSK Workspace - Q1: True Agreement Flow" {
usecase "Ingest Diagnostic Ultrasound" as UC_Load
rectangle "Pipeline: Vision & Reasoning" {
usecase "Compute Matrices & GradCAM (VKIST Grader)" as UC_Vision
usecase "Parse Features & Draft Explanation (LLM Explainer)" as UC_Explain
usecase "Log Chain-of-Thought (CoT)" as UC_CoT
}
rectangle "Audit: RAG-Referee" {
usecase "Verify Clinical Guideline Alignment" as UC_Referee
usecase "Cache Concurrence Structural Block" as UC_Log
}
rectangle "Clinical Finalization" {
usecase "Review & Confirm Diagnosis" as UC_Review
usecase "Sign & Commit Record" as UC_Finalize
}
usecase "Synchronize EMR Ledger" as UC_Sync
}
' Interaction Paths
Rad --> UC_Load
UC_Load ..> UC_Vision : <<include>>
UC_Vision --> UC_Explain : Provide Tensors & GradCAM
UC_Explain ..> UC_CoT : <<include>> (Persist Reasoning Path)
' Independent Verification Gate
UC_Explain ..> UC_Referee : <<include>>
UC_Referee ..> UC_Log : <<include>> (High-Trust Block)
' Final User Confirmation
Rad --> UC_Review
UC_Log --> UC_Review : Show "High-Trust Concurrence"
Rad --> UC_Finalize
UC_Finalize ..> UC_Sync : <<include>>
UC_Sync --> EMR : POST Validated JSON Record
@enduml
```
![image.png](Q1%20True%20Agreement%20(AI%20Correct%20Doctor%20Correct)/image.png)

67
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/Q2 Automation Override Risk.md Normal file
View File

@@ -0,0 +1,67 @@
# Q2: Automation Override Risk
(AI Correct / Doctor Oversights / Confuse)
Layered Three-Tier ML Stack Performance Impact (Your Proposed Design): The Conversational Circuit Breaker triggers when a clinician disagrees / confuse / uncertain with the system's diagnostic grade, halting the workflow to launch an interactive Socratic dialogue that bridges the gap between human intuition and machine inference. In this mode, the system (LLM-explainer) shall synthesize raw VKIST-ML vision tensors, GradCAM activation heatmaps, and evidence retrieved via RAG into a collaborative analysis session, forcing the clinician to articulate their reasoning against the machine's spatial and vascular observations. To ensure diagnostic integrity, a BERT-based hallucination detector continuously monitors the chat for semantic drift or illogical premises; if the conversation reaches an impasse or the system detects potential contextual hallucination, the RAG-Referee intervenes as an unbiased arbiter. This referee bypasses the conversational history to provide definitive, evidence-based source material from clinical guidelines (such as ESSR) directly tied to the raw imaging metrics, resolving the ambiguity through objective, verifiable medical evidence rather than subjective negotiation.
```planuml
@startuml
skinparam linetype polyline
skinparam packageStyle rectangle
skinparam rectangle {
BackgroundColor #fefefe
BorderColor #555555
}
' Actors
actor "Radiologist (UP5)" as Rad
actor "Internal Consultor (LLM Chat)" as Cons <<System>>
actor "Hospital EMR" as EMR <<System>>
rectangle "VKIST MSK Workspace - Q2 Architecture" {
usecase "Trigger Circuit Breaker Panel" as UC2_Trigger
rectangle "Socratic Workspace UI Panel" {
usecase "Lock Main Diagnostic Flow" as UC2_Halt
usecase "Engage in Socratic Discussion" as UC2_Socratic
usecase "Display Visual GradCAM Overlay" as UC2_Synth
}
rectangle "Verification & Arbitration Kernel" {
usecase "Audit Chat Token Drift (BERT)" as UC2_BERT
usecase "Execute RAG-Referee Check" as UC2_Referee
usecase "Query Immutable Guideline Base" as UC2_RAG_Fetch
}
rectangle "Clinical Resolution Gate" {
usecase "Review Referee Verdict Card" as UC2_Review
usecase "Commit Signed Diagnosis" as UC2_Finalize
}
usecase "EMR Ledger Sync" as UC2_Sync
}
' Core Interaction Flow
Rad --> UC2_Trigger : Disagreement/Uncertainty
UC2_Trigger ..> UC2_Halt : <<include>>
UC2_Halt ..> UC2_Synth : <<include>>
' Dynamic Chat Loop between Doctor and Internal Consultor LLM
Rad --> UC2_Socratic
Cons --> UC2_Socratic : Drive Pathologic Inquiry Dialogue
' Asynchronous Automated Verification Channel
UC2_Socratic ..> UC2_BERT : Stream Conversation Tokens
UC2_BERT ..> UC2_Referee : <<extend>> (Triggered on Impasse / Chat Hallucination)
UC2_Referee ..> UC2_RAG_Fetch : <<include>>
UC2_RAG_Fetch ..> UC2_Review : Inject Ground-Truth Evidence
' Finalization Steps
Rad --> UC2_Review
Rad --> UC2_Finalize
UC2_Finalize ..> UC2_Sync : <<include>>
UC2_Sync --> EMR : POST Validated JSON Payload
@enduml
```
![image.png](Q2%20Automation%20Override%20Risk%20(AI%20Correct%20Doctor%20Ove/image.png)

69
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/Q3 Clinician Subservience Risk.md Normal file
View File

@@ -0,0 +1,69 @@
# Q3: Clinician Subservience Risk
(AI Hallucinates / Doctor Correct)
Layered Three-Tier ML Stack Performance Impact (Your Proposed Design): The Objective Critic Loop initiates when a clinician contests an automated diagnostic grade, triggering an interactive Socratic consultation that bridges human intuition with machine inference via the VKIST-ML vision stack. During this loop, the LLM Explainer renders a GradCAM-anchored reasoning draft that visualizes the specific pixel-level feature activation logic, enabling the clinician to identify and isolate artifacts—such as motion tremors—that may have induced a system hallucination. To ensure diagnostic integrity, a BERT-based detector continuously monitors the dialogue for semantic drift, and if the interaction reaches an impasse or context hallucination is detected, the RAG-Referee intervenes as an unbiased, independent arbiter. By cross-verifying the clinician’s assertion and the model’s reasoning against raw imaging tensors and immutable, source-cited clinical guidelines (e.g., ESSR/OMERACT standards), the Referee resolves diagnostic ambiguity with objective evidence, ultimately committing the validated session as an annotated ground-truth record for targeted system reinforcement.
```planuml
@startuml
' Layout optimizations to secure compact rendering and prevent image fragmentation
skinparam linetype polyline
skinparam packageStyle rectangle
skinparam rectangle {
BackgroundColor #fefefe
BorderColor #555555
}
' Actors strictly mapped to match your canonical architectural definitions
actor "Radiologist (UP5)" as Rad
actor "Internal Consultor (LLM Chat)" as Cons <<System>>
actor "System Maintainer" as Maint <<System>>
rectangle "VKIST MSK Workspace - Q4 Architecture" {
usecase "Evaluate Epistemic Uncertainty Gate" as UC4_Trigger
rectangle "Socratic Workspace UI Panel" {
usecase "Shift to Clinical Investigation Mode" as UC4_Halt
usecase "Engage in Socratic Discussion" as UC4_Socratic
usecase "Render Manual Checklist Canvas" as UC4_Synth
}
rectangle "Verification & Arbitration Kernel" {
usecase "Audit Chat Token Drift (BERT)" as UC4_BERT
usecase "Execute RAG-Referee Check" as UC4_Referee
usecase "Return Null-Match Signal" as UC4_RAG_Fetch
}
rectangle "Clinical Resolution Gate" {
usecase "Document Novel Morphological Features" as UC4_Review
usecase "Authorize Serialized Anomaly Package" as UC4_Finalize
}
usecase "Asynchronous Telemetry Queue Sync" as UC4_Sync
}
' Initial Data Intake and Uncertainty Routing Paths
Rad --> UC4_Trigger : Feed OOD Image Tensors
UC4_Trigger ..> UC4_RAG_Fetch : <<include>> (Triggers Empty Vector Result)
UC4_RAG_Fetch ..> UC4_Halt : <<extend>> (On Zero-Match Guidelines + Low Conf Tensors)
UC4_Halt ..> UC4_Synth : <<include>>
' Direct Socratic Analysis Run-time Workspace
Rad --> UC4_Socratic
Cons --> UC4_Socratic : Drive Exploratory Morphology Dialogue
' Live Guardrail and Exception Evaluation Paths
UC4_Socratic ..> UC4_BERT : Stream Conversation Tokens
UC4_BERT ..> UC4_Referee : <<include>> (Validates Logical Framing Stability)
' Manual Audit, Documenting Anomaly and Consent Finalization
Rad --> UC4_Review : Acknowledge Guideline Limitation
Rad --> UC4_Finalize : Provide Native Opt-In Telemetry Consent
' Async Data Serialization Sink to System Maintainer Ledger
UC4_Finalize ..> UC4_Sync : <<include>>
UC4_Sync --> Maint : POST Encrypted Tensors & Logs for Model Retraining
@enduml
```
![image.png](Q3%20Clinician%20Subservience%20Risk%20(AI%20Hallucinates%20Do/image.png)

69
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/Q4 Double Blind Failure.md Normal file
View File

@@ -0,0 +1,69 @@
# Q4: Double Blind Failure dues to edge-case
(AI Faulty / Doctor Biased)
Layered Three-Tier ML Stack Performance Impact (Your Proposed Design): Anomaly Escalation Protocol: In instances where both the diagnostic system and the clinician encounter an edge-case—or "unknown-unknown"—that lacks precedent in the current RAG knowledge base, the system initiates the Anomaly Escalation Protocol. The LLM Explainer detects this "epistemic uncertainty" (via low vision-stack confidence and empty RAG retrieval results) and shifts the interface from "Diagnostic Support" to "Clinical Investigation Mode." Instead of attempting to force a Grade-based diagnosis, the Internal Consultor guides the clinician to document the unique morphological features through a structured annotation protocol, facilitating a Socratic investigation into the anomaly. The system transparently acknowledges the limitation, explicitly stating that current clinical guidelines do not cover this specific presentation, and prompts the clinician to manually document findings. With the clinician’s consent, the workspace commits this session as a "Novel Research Case," automatically serializing the raw imaging tensors, clinician observations, and artifact logs to a secure telemetry queue, flagging the data for system maintainers to perform targeted model retraining and protocol refinement.
```planuml
@startuml
' Layout optimizations to secure compact rendering and prevent image fragmentation
skinparam linetype polyline
skinparam packageStyle rectangle
skinparam rectangle {
BackgroundColor #fefefe
BorderColor #555555
}
' Actors strictly mapped to match your canonical architectural definitions
actor "Radiologist (UP5)" as Rad
actor "Internal Consultor (LLM Chat)" as Cons <<System>>
actor "System Maintainer" as Maint <<System>>
rectangle "VKIST MSK Workspace - Q4 Architecture" {
usecase "Evaluate Epistemic Uncertainty Gate" as UC4_Trigger
rectangle "Socratic Workspace UI Panel" {
usecase "Shift to Clinical Investigation Mode" as UC4_Halt
usecase "Engage in Socratic Discussion" as UC4_Socratic
usecase "Render Manual Checklist Canvas" as UC4_Synth
}
rectangle "Verification & Arbitration Kernel" {
usecase "Audit Chat Token Drift (BERT)" as UC4_BERT
usecase "Execute RAG-Referee Check" as UC4_Referee
usecase "Return Null-Match Signal" as UC4_RAG_Fetch
}
rectangle "Clinical Resolution Gate" {
usecase "Document Novel Morphological Features" as UC4_Review
usecase "Authorize Serialized Anomaly Package" as UC4_Finalize
}
usecase "Asynchronous Telemetry Queue Sync" as UC4_Sync
}
' Initial Data Intake and Uncertainty Routing Paths
Rad --> UC4_Trigger : Feed OOD Image Tensors
UC4_Trigger ..> UC4_RAG_Fetch : <<include>> (Triggers Empty Vector Result)
UC4_RAG_Fetch ..> UC4_Halt : <<extend>> (On Zero-Match Guidelines + Low Conf Tensors)
UC4_Halt ..> UC4_Synth : <<include>>
' Direct Socratic Analysis Run-time Workspace
Rad --> UC4_Socratic
Cons --> UC4_Socratic : Drive Exploratory Morphology Dialogue
' Live Guardrail and Exception Evaluation Paths
UC4_Socratic ..> UC4_BERT : Stream Conversation Tokens
UC4_BERT ..> UC4_Referee : <<include>> (Validates Logical Framing Stability)
' Manual Audit, Documenting Anomaly and Consent Finalization
Rad --> UC4_Review : Acknowledge Guideline Limitation
Rad --> UC4_Finalize : Provide Native Opt-In Telemetry Consent
' Async Data Serialization Sink to System Maintainer Ledger
UC4_Finalize ..> UC4_Sync : <<include>>
UC4_Sync --> Maint : POST Encrypted Tensors & Logs for Model Retraining
@enduml
```
![image.png](Q4%20Double%20Blind%20Failure%20dues%20to%20edge-case%20(AI%20Faul/image.png)

946
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/FR_25_UC_SPEC.md Normal file
View File

@@ -0,0 +1,946 @@
---
# PART 1: Core Viewing & Data Intake Pipelines
## 1. UC-48376: Load Patient Scan Session
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Load Patient Scan Session
* Actor: Diagnostic Radiologist (Rad), VKIST Vision Grader Engine (Grader)
* Goal: Ingest raw ultrasound frame arrays and initialize the diagnostic session state.
* Interaction: System-to-System / User-to-System
* Stimulus: User opens an unreviewed patient file, or the workspace catches an active DICOM stream hook.
* SysResponse: Confirmation that raw frame arrays are mapped, spatial calibrations are set, and the local session state is active.
* VerboseForm (Formula Reference View): "The use case 'Load Patient Scan Session' defines a User-to-System / System-to-System interaction where the Diagnostic Radiologist (Rad) and VKIST Vision Grader Engine (Grader) aim to Ingest raw ultrasound frame arrays and initialize the diagnostic session state. This workflow is triggered when User opens an unreviewed patient file, or the workspace catches an active DICOM stream hook, causing the system to respond by providing Confirmation that raw frame arrays are mapped, spatial calibrations are set, and the local session state is active."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Load Patient Scan Session
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Local workspace application is authenticated and has secure socket access to the local image buffer.
* DICOM/raw frame data payload is uncorrupted and readable.
* **Postconditions (Success State):**
* Core frame parameters are loaded into memory with spatial scale calibrations preserved.
* Background parsing pipeline registers the unique session hash and prepares the context matrix for downstream agents.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** selects a patient case file from the workspace worklist interface.
2. **VKIST Vision Grader Engine** feeds raw ultrasound image tensors, spatial calibrations, and foundational frame telemetry metadata into the workspace memory layer.
3. **System** extracts pixel dimensions and constructs localized rendering viewports.
4. **System** includes `UC_Q1_Explain` in the background to spin up explanation prompt matrices.
5. **System** displays the fully loaded image frame in the workspace canvas, preparing the viewport for immediate review.
### Alternative & Exception Flows
* **Exception Flow A: Corrupted Image Frame Payload**
* At step [2], if the payload data fails format validation or structural check headers, the system halts execution, logs a data corruption fault code, and alerts the user with an "Unable to Parse Scan Session" dialog box.
* **Exception Flow B: Resolution / Calibration Mismatch**
* At step [3], if spatial aspect ratios or metadata pixel matrices lack the standardized calibration tags required by the vision engine, the workspace falls back to a safe default scale flag and displays a non-blocking diagnostic accuracy warning icon.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
actor "VKIST Vision Grader Engine" as Grader << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "UC-48376\nLoad Patient Scan Session" as UC_Core
usecase "UC-25776\nGenerate GradCAM & CoT Explanation Panel" as UC_Sub
}
Rad --> UC_Core
Grader --> UC_Core
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 2. UC-47988: Review Suggested Synovitis Grade (0-3)
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Review Suggested Synovitis Grade (0-3)
* Actor: Diagnostic Radiologist (Rad)
* Goal: Evaluate the ML engine's proposed synovitis classification and structural overlays.
* Interaction: User-to-System
* Stimulus: The workspace completes localized UI construction and displays the diagnostic panel.
* SysResponse: Display of classification metrics (Grades 0-3), color-coded overlays, and active risk-extension hooks.
* VerboseForm (Formula Reference View): "The use case 'Review Suggested Synovitis Grade (0-3)' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Evaluate the ML engine's proposed synovitis classification and structural overlays. This workflow is triggered when The workspace completes localized UI construction and displays the diagnostic panel, causing the system to respond by providing Display of classification metrics (Grades 0-3), color-coded overlays, and active risk-extension hooks."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Review Suggested Synovitis Grade (0-3)
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Image frames and raw ML prediction tensors (segmentation masks, classification weights) are fully loaded in memory via `Load Patient Scan Session`.
* **Postconditions (Success State):**
* System records human gaze/interaction initialization flags.
* System keeps exception-based extend vectors armed (`UC_Q2_Intercept`, `UC_Q3_Expose`, `UC_Q4_Escalate`).
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** presents the active ultrasound canvas with interactive, toggleable, color-coded segmentation mask overlays.
2. **System** displays the vision engine's suggested synovitis grading estimation (Grade 0, 1, 2, or 3) alongside structural pixel-percentage distribution metrics.
3. **Diagnostic Radiologist** inspects the spatial distribution of the synovial hypertrophy markers and reads the inline text panels.
4. **Diagnostic Radiologist** approves the visual data metrics without requesting alterations or triggering corrective dialogue paths.
### Alternative & Exception Flows
* **Extension Flow A: Clinician Friction / Disagreement Caught**
* At step [3], if mouse click frequencies suggest hesitation or manual adjustments cross a conflict delta threshold, the execution path triggers `UC_Q2_Intercept` to prevent blind override errors.
* **Extension Flow B: Expert Contests Automated Grade**
* At step [3], if the clinician explicitly changes the classification dropdown away from the ML-proposed score, the workspace extends to `UC_Q3_Expose` to display the machine activation weights.
* **Extension Flow C: Anomaly / Confidence Failure Detected**
* At step [1], if the deep-learning array returned a classification confidence metric below safety bounds paired with blank knowledge base lookups, the interface branches into `UC_Q4_Escalate`.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "UC-47988\nReview Suggested Synovitis Grade (0-3)" as UC_Core
usecase "UC-22159\nTrigger Conversational Circuit Breaker" as UC_Q2
usecase "UC-25637\nExpose Pixel-Level Activation Logic" as UC_Q3
usecase "UC-35956\nActivate Clinical Investigation Mode" as UC_Q4
}
Rad --> UC_Core
UC_Core <.. UC_Q2 : <<extend>>
UC_Core <.. UC_Q3 : <<extend>>
UC_Core <.. UC_Q4 : <<extend>>
@enduml
```
---
## 3. UC-92006: Finalize & Sign Electronic Record
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Finalize & Sign Electronic Record
* Actor: Diagnostic Radiologist (Rad), Hospital EMR System (EMR)
* Goal: Authenticate, cryptographically seal, and sync verified diagnostic reports down to storage infrastructure.
* Interaction: User-to-System / System-to-System
* Stimulus: User executes the final confirmation/signature command button in the workspace utility ribbon.
* SysResponse: Generation of a signed cryptographic log block and structured JSON transmission payload delivered to the EMR endpoint.
* VerboseForm (Formula Reference View): "The use case 'Finalize & Sign Electronic Record' defines a User-to-System / System-to-System interaction where the Diagnostic Radiologist (Rad) and Hospital EMR System (EMR) aim to Authenticate, cryptographically seal, and sync verified diagnostic reports down to storage infrastructure. This workflow is triggered when User executes the final confirmation/signature command button in the workspace utility ribbon, causing the system to respond by providing Generation of a signed cryptographic log block and structured JSON transmission payload delivered to the EMR endpoint."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Finalize & Sign Electronic Record
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active scan session evaluation has been resolved, and grading metrics are verified by the human specialist.
* Local localized network channel to the hospital server framework is functional.
* **Postconditions (Success State):**
* Session record is transformed into a read-only state.
* Standardized structural JSON payload data is safely stored within the Hospital EMR System sink.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** initiates the session finalization pipeline by interacting with the cryptographic signature command trigger.
2. **System** prompts for the secure authentication credentials of the signing specialist.
3. **System** generates a unified clinical log structure, packing structural thickness measurements (mm), final validated synovitis tier scores, and accompanying multi-agent trace logs.
4. **System** calculates a secure cryptographic data hash, locking the session record into an immutable post-review profile.
5. **System** delivers the structured data package across localized network pipes to the **Hospital EMR System**.
6. **Hospital EMR System** confirms safe database commit storage updates and provides an acknowledgment packet back to the workspace.
### Alternative & Exception Flows
* **Exception Flow A: Network Pipeline Transmission Failure**
* At step [5], if network communications timeout or socket breaks occur, the workspace locks the finalized JSON package into a local encrypted offline buffer, changes the session status tag to "Pending Sync", and presents a clear connectivity warning alert.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "UC-92006\nFinalize & Sign Electronic Record" as UC_Core
}
Rad --> UC_Core
UC_Core ..> EMR : Sync standardized structural JSON data
@enduml
```
---
# PART 2: Quadrant 1 — True Agreement Flows (AI Correct / Doctor Correct)
## 4. UC-25776: Generate GradCAM & CoT Explanation Panel
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Generate GradCAM & CoT Explanation Panel
* Actor: Diagnostic Radiologist (Rad)
* Goal: Present clear, pixel-linked visuospatial explanations and multi-modal clinical reasoning for high-trust verification.
* Interaction: User-to-System
* Stimulus: Inclusion trigger initialized during session data intake (`Load Patient Scan Session`).
* SysResponse: Renders heatmaps highlighting model focus zones alongside structured, clear reasoning steps.
* VerboseForm (Formula Reference View): "The use case 'Generate GradCAM & CoT Explanation Panel' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Present clear, pixel-linked visuospatial explanations and multi-modal clinical reasoning for high-trust verification. This workflow is triggered when Inclusion trigger initialized during session data intake (`Load Patient Scan Session`), causing the system to respond by providing Renders heatmaps highlighting model focus zones alongside structured, clear reasoning steps."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Generate GradCAM & CoT Explanation Panel
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Raw image frames and vision engine inference matrix weights have been imported via `Load Patient Scan Session`.
* **Postconditions (Success State):**
* Split-screen layout displays visual explanation elements without adding visual noise to the core image frame workspace canvas.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** evaluates the internal deep-learning model gradient parameters for the target ultrasound image slice.
2. **System** generates a visual GradCAM heatmap layer mapping feature locations that dictated model classifications (e.g., hypervascularized synovial proliferation zones).
3. **System** maps multi-modal prompt metrics through the internal LLM Explainer module to produce a concise, point-by-point clinical reasoning string.
4. **System** populates the split-screen workspace sub-section block with this explanation data to guide human inspection efficiently.
5. **System** includes `UC_Q1_Log` to serialize verification metadata.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "UC-25776\nGenerate GradCAM & CoT Explanation Panel" as UC_Core
usecase "UC-02423\nLog High-Trust Concur Block" as UC_Sub
}
Rad --> UC_Core
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 5. UC-02423: Log High-Trust Concur Block
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Log High-Trust Concur Block
* Actor: Hospital EMR System (EMR)
* Goal: Secure the human-AI alignment log trace within the final diagnostic report payload.
* Interaction: System-to-System
* Stimulus: Explanatory panel validation completes successfully without user override actions.
* SysResponse: Appends a tamper-evident audit trace block verifying explicit human-AI agreement into the session log cache.
* VerboseForm (Formula Reference View): "The use case 'Log High-Trust Concur Block' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Secure the human-AI alignment log trace within the final diagnostic report payload. This workflow is triggered when Explanatory panel validation completes successfully without user override actions, causing the system to respond by providing Appends a tamper-evident audit trace block verifying explicit human-AI agreement into the session log cache."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Log High-Trust Concur Block
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Multi-modal explanations were fully generated (`UC_Q1_Explain`) and passed without human alteration marks.
* **Postconditions (Success State):**
* Explicit audit string trace tracking high-trust convergence is formatted for downstream pipeline compilation.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** detects a direct consensus condition where the human expert confirms the model data without text/grading edits.
2. **System** serializes the multi-modal text breakdown and pixel attribution coordinates into an immutable log string block.
3. **System** assigns an explicit alignment token header flag (`HIGH_TRUST_CONCURRENCE`).
4. **System** caches this specialized tracking trace within the localized session state data, making it ready to be appended during final data hand-off routines (`UC_Finalize`).
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "UC-02423\nLog High-Trust Concur Block" as UC_Core
}
UC_Core ..> EMR : (Prepares payload for final sync)
@enduml
```
---
# PART 3: Quadrant 2 — Automation Override Risk Loops (AI Correct / Doctor Oversight)
## 6. UC-22159: Trigger Conversational Circuit Breaker
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Trigger Conversational Circuit Breaker
* Actor: Diagnostic Radiologist (Rad)
* Goal: Intercept premature finalization workflows if interface telemetry reveals friction, hesitation, or cognitive blind-spots.
* Interaction: User-to-System
* Stimulus: Extended extension trace caught during review steps if user behavior markers diverge from smooth consensus paths.
* SysResponse: Halts default workspace finalization routes and shifts the UI into a mandatory safety evaluation mode.
* VerboseForm (Formula Reference View): "The use case 'Trigger Conversational Circuit Breaker' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Intercept premature finalization workflows if interface telemetry reveals friction, hesitation, or cognitive blind-spots. This workflow is triggered when Extended extension trace caught during review steps if user behavior markers diverge from smooth consensus paths, causing the system to respond by providing Halts default workspace finalization routes and shifts the UI into a mandatory safety evaluation mode."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Trigger Conversational Circuit Breaker
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active session is inside the `UC_Review` workflow phase.
* UI layer telemetry captures specific friction indicators (e.g., high-frequency cursor oscillation, repeatedly typing and deleting text, or conflicting grading inputs).
* **Postconditions (Success State):**
* Direct finalization path is securely locked down.
* System-forced conversational validation interface is deployed into view.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** evaluates live workspace telemetry tracking patterns during active case validation.
2. **System** detects user behavior triggers signaling high diagnostic friction or potential automatic oversight trends.
3. **System** blocks the immediate execution availability of the standard finalization command sequence (`UC_Finalize`).
4. **System** transforms workspace panel focus areas to present an interactive confirmation overlay.
5. **System** executes `UC_Q2_Socratic` to initialize direct safety check communications.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "UC-47988\nReview Suggested Synovitis Grade (0-3)" as UC_Review
usecase "UC-22159\nTrigger Conversational Circuit Breaker" as UC_Core
usecase "UC-55146\nFacilitate Socratic Reasoning Dialogue" as UC_Sub
}
Rad --> UC_Review
UC_Review <.. UC_Core : <<extend>> (If clinician friction detected)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 7. UC-55146: Facilitate Socratic Reasoning Dialogue
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Facilitate Socratic Reasoning Dialogue
* Actor: Diagnostic Radiologist (Rad)
* Goal: Engage the specialist in a targeted, conversational double-check loop regarding controversial structural markers.
* Interaction: User-to-System
* Stimulus: Core execution request passed down by the active circuit breaker module (`UC_Q2_Intercept`).
* SysResponse: Interactive conversational sub-panel displaying focused prompt choices that check specific diagnostic criteria.
* VerboseForm (Formula Reference View): "The use case 'Facilitate Socratic Reasoning Dialogue' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Engage the specialist in a targeted, conversational double-check loop regarding controversial structural markers. This workflow is triggered when Core execution request passed down by the active circuit breaker module (`UC_Q2_Intercept`), causing the system to respond by providing Interactive conversational sub-panel displaying focused prompt choices that check specific diagnostic criteria."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Facilitate Socratic Reasoning Dialogue
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Circuit breaker safety intercept sequence has completed successfully, freezing generic CRUD paths.
* **Postconditions (Success State):**
* User inputs conversational defense arguments or confirms specific anatomical findings.
* Live conversation data tokens are actively streamed to automated safety monitors.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** initializes a conversational chat element right next to the ultrasound display field.
2. **System** presents a non-confrontational, clinically grounded question regarding the identified discrepancies (e.g., *"Note the echo-free thickening layer in the suprapatellar recess; please confirm if this modification represents minor effusion or structural pannus tissue"*).
3. **Diagnostic Radiologist** enters text responses or selects structural tag tokens to clarify their assessment.
4. **System** includes `UC_Q2_BERT` in real time to process active conversation token patterns.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "UC-55146\nFacilitate Socratic Reasoning Dialogue" as UC_Core
usecase "UC-74821\nMonitor Drift via BERT Sub-Layer" as UC_Sub
}
Rad --> UC_Core : Argue observations
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 8. UC_Q2_BERT: Monitor Drift via BERT Sub-Layer
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Monitor Drift via BERT Sub-Layer
* Actor: Diagnostic Radiologist (Rad)
* Goal: Continuously parse communication tokens to identify logical contradictions or semantic drift during clinical debates.
* Interaction: User-to-System
* Stimulus: Streamed entry of communication tokens within the active dialogue loop.
* SysResponse: Real-time semantic checking flags; extends out to the RAG referee if an impasse or severe drift is captured.
* VerboseForm (Formula Reference View): "The use case 'Monitor Drift via BERT Sub-Layer' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Continuously parse communication tokens to identify logical contradictions or semantic drift during clinical debates. This workflow is triggered when Streamed entry of communication tokens within the active dialogue loop, causing the system to respond by providing Real-time semantic checking flags; extends out to the RAG referee if an impasse or severe drift is captured."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Monitor Drift via BERT Sub-Layer
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active conversational dialogue module is processing user data strings (`UC_Q2_Socratic`).
* **Postconditions (Success State):**
* Log structures capture semantic alignment metrics.
* System successfully catches contradictions before data parameters flow to final storage.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** continuously intercepts conversation tokens as the human expert types input strings.
2. **System** runs token matrices through an embedded BERT checking model to calculate contextual semantic coherence scores.
3. **System** verifies that user claims line up logically with the visual indicators under review.
4. **System** approves the validated conversational step, allowing the specialist to complete the confirmation cycle smoothly.
### Alternative & Exception Flows
* **Extension Flow A: Impasse or Semantic Contradiction Detected**
* At step [3], if the specialist's input text contradicts objective structural metrics (e.g., claiming a region is "completely normal" while the visual layer registers massive synovial proliferation) or exhibits context drift, the process branches into `UC_Q2_Arbiter` to request evidence evaluation.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Monitor Drift via BERT Sub-Layer" as UC_Core
usecase "Arbitrate Evidence via RAG-Referee" as UC_Ext
}
Rad --> UC_Core
UC_Core <.. UC_Ext : <<extend>> (If impasse or semantic drift caught)
@enduml
```
---
## 9. UC_Q2_Arbiter: Arbitrate Evidence via RAG-Referee
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Arbitrate Evidence via RAG-Referee
* Actor: Diagnostic Radiologist (Rad)
* Goal: Query static, authoritative clinical knowledge bases to resolve human-machine disagreements with objective evidence.
* Interaction: User-to-System
* Stimulus: Triggered when communication tracking scores cross a severe semantic mismatch or impasse threshold.
* SysResponse: Inline injection of un-biased diagnostic text extracts and guidelines matching the active frame conditions.
* VerboseForm (Formula Reference View): "The use case 'Arbitrate Evidence via RAG-Referee' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Query static, authoritative clinical knowledge bases to resolve human-machine disagreements with objective evidence. This workflow is triggered when Triggered when communication tracking scores cross a severe semantic mismatch or impasse threshold, causing the system to respond by providing Inline injection of un-biased diagnostic text extracts and guidelines matching the active frame conditions."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Arbitrate Evidence via RAG-Referee
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* BERT analytics layers detect a diagnostic impasse or significant semantic drift.
* Authoritative local clinical knowledge base index (e.g., OMERACT synovitis grading reference manuals) is online and responsive.
* **Postconditions (Success State):**
* Disagreement matrix is resolved via verified medical data injection.
* Final chosen path is linked directly to a standard medical guideline anchor.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** halts active conversational dialogue inputs temporarily to execute a localized context search.
2. **System** extracts spatial measurements and text tokens to construct a specialized RAG search string.
3. **System** queries local, validated medical knowledge data banks to locate matching diagnostic criteria sections.
4. **System** displays the verified guideline text extract right inside the workspace alert view block (e.g., *"OMERACT standardizes Grade 2 as hypoechoic synovial hypertrophy demonstrating fluid-filled distension up to structural boundary bounds"*).
5. **Diagnostic Radiologist** reviews the authoritative reference framework and either adjusts their classification choice or submits a structured expert override justifying their deviation.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Arbitrate Evidence via RAG-Referee" as UC_Core
}
Rad --> UC_Core
@enduml
```
---
# PART 4: Quadrant 3 — Clinician Subservience Risk Loops (AI Hallucinates / Doctor Correct)
## 10. UC_Q3_Expose: Expose Pixel-Level Activation Logic
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Expose Pixel-Level Activation Logic
* Actor: Diagnostic Radiologist (Rad)
* Goal: Reveal fine-grained layer weights and activation responses when the human specialist challenges an automated grade prediction.
* Interaction: User-to-System
* Stimulus: Clinician manually alters or rejects the ML-proposed classification score in the review pane.
* SysResponse: Interactive visual mapping showing the exact high-frequency noise regions driving model prediction errors.
* VerboseForm (Formula Reference View): "The use case 'Expose Pixel-Level Activation Logic' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Reveal fine-grained layer weights and activation responses when the human specialist challenges an automated grade prediction. This workflow is triggered when Clinician manually alters or rejects the ML-proposed classification score in the review pane, causing the system to respond by providing Interactive visual mapping showing the exact high-frequency noise regions driving model prediction errors."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Expose Pixel-Level Activation Logic
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active session is inside the `UC_Review` interface phase.
* Specialist chooses an option that breaks clean model agreement paths.
* **Postconditions (Success State):**
* Internal neural layer weight vectors are visually mapped onto the primary medical viewport.
* Core manual artifact isolation tool sets become active on the canvas layout.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** changes the system-suggested grade classification dropdown setting.
2. **System** captures the modification step and branches away from the standard review pathway to reveal underlying model mechanics.
3. **System** transforms image layers to display fine-grained activation weights, revealing exactly which pixel clusters (e.g., acoustic shadowing regions or bone interfaces) skewed the model's calculation.
4. **System** includes `UC_Q3_Isolate` to let the specialist manually clean up the noise zones.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC_Review
usecase "Expose Pixel-Level Activation Logic" as UC_Core
usecase "Isolate Visual Noise/Artifacts" as UC_Sub
}
Rad --> UC_Review
UC_Review <.. UC_Core : <<extend>> (If clinician contests AI score)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 11. UC_Q3_Isolate: Isolate Visual Noise/Artifacts
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Isolate Visual Noise/Artifacts
* Actor: Diagnostic Radiologist (Rad)
* Goal: Provide manual brush and selection overlays to mask out acoustic shadows, bone scattering, or artifacts causing model calculation errors.
* Interaction: User-to-System
* Stimulus: Human operator activates canvas cleanup tools within the exposed model layer layout.
* SysResponse: Real-time visual updates to the pixel mask array, isolating clean anatomical structures from surrounding imaging noise.
* VerboseForm (Formula Reference View): "The use case 'Isolate Visual Noise/Artifacts' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Provide manual brush and selection overlays to mask out acoustic shadows, bone scattering, or artifacts causing model calculation errors. This workflow is triggered when Human operator activates canvas cleanup tools within the exposed model layer layout, causing the system to respond by providing Real-time visual updates to the pixel mask array, isolating clean anatomical structures from surrounding imaging noise."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Isolate Visual Noise/Artifacts
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System exposure arrays are visible across the image viewport layout (`UC_Q3_Expose`).
* **Postconditions (Success State):**
* Corrected ground-truth frame masks are calculated and locked into memory.
* System updates local diagnostic metrics using the isolated anatomical data.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** activates a manual canvas tool overlay, giving the user access to high-precision brush, eraser, and selection vectors.
2. **Diagnostic Radiologist** applies brush vectors directly over areas containing acoustic artifacts or non-synovial structures that skewed the automated classification score.
3. **System** recalculates active region dimensions in real time, excluding the masked pixels from the active grading parameters.
4. **System** updates diagnostic panel displays to confirm the human-corrected measurements.
5. **System** includes `UC_Q3_Commit` to lock the updated session state securely.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Isolate Visual Noise/Artifacts" as UC_Core
usecase "Commit Validated Ground-Truth Record" as UC_Sub
}
Rad --> UC_Core : Tag artifacts
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 12. UC_Q3_Commit: Commit Validated Ground-Truth Record
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Commit Validated Ground-Truth Record
* Actor: Hospital EMR System (EMR)
* Goal: Secure the human-corrected ground-truth dataset variant while appending clean, expert-validated report payloads to the EMR.
* Interaction: System-to-System
* Stimulus: Completion of manual artifact masking operations and confirmation of corrected metrics.
* SysResponse: Stores the corrected medical report in the EMR and saves the isolated image mask to an optimization cache for subsequent retraining.
* VerboseForm (Formula Reference View): "The use case 'Commit Validated Ground-Truth Record' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Secure the human-corrected ground-truth dataset variant while appending clean, expert-validated report payloads to the EMR. This workflow is triggered when Completion of manual artifact masking operations and confirmation of corrected metrics, causing the system to respond by providing Stores the corrected medical report in the EMR and saves the isolated image mask to an optimization cache for subsequent retraining."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Commit Validated Ground-Truth Record
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Human-directed canvas modification steps are locked in place without remaining pixel parity errors (`UC_Q3_Isolate`).
* **Postconditions (Success State):**
* EMR database updates receive the human expert's diagnostic findings.
* Isolated ground-truth tensor pairs are safely cached for AI training refinement runs.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** packages the human expert's corrected diagnostic data metrics into the primary transmission bundle.
2. **System** isolates the human-brushed image mask layers alongside the initial incorrect model classification output.
3. **System** tags the data pair as a validated retraining asset (`GROUND_TRUTH_OVERRIDE`).
4. **System** saves the optimization asset to a secure local retraining storage folder, while preparing the primary medical report for delivery to the **Hospital EMR System**.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Commit Validated Ground-Truth Record" as UC_Core
}
UC_Core ..> EMR : (Prepares clean report for EMR sync)
@enduml
```
---
# PART 5: Quadrant 4 — Double Blind Failure Loops (AI Faulty / Doctor Biased)
## 13. UC_Q4_Escalate: Activate Clinical Investigation Mode
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Activate Clinical Investigation Mode
* Actor: Diagnostic Radiologist (Rad)
* Goal: Switch the system into a strict, template-driven manual examination mode when low vision confidence values align with a lack of reference data.
* Interaction: User-to-System
* Stimulus: The workspace detects a critical double-blind failure criteria match during the case evaluation phase.
* SysResponse: Disables automated diagnostic suggestions entirely and forces a standardized manual morphology review.
* VerboseForm (Formula Reference View): "The use case 'Activate Clinical Investigation Mode' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Switch the system into a strict, template-driven manual examination mode when low vision confidence values align with a lack of reference data. This workflow is triggered when The workspace detects a critical double-blind failure criteria match during the case evaluation phase, causing the system to respond by providing Disables automated diagnostic suggestions entirely and forces a standardized manual morphology review."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Activate Clinical Investigation Mode
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System classification loops return low-confidence indices.
* Authoritative RAG reference lookups return no matches, indicating an unmapped anatomical variant or a severe image anomaly.
* **Postconditions (Success State):**
* Automated suggestions are masked out to prevent cognitive bias.
* Mandatory manual template verification frameworks are deployed into active workspace view.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** monitors deep-learning inference score bounds during case evaluation.
2. **System** runs background reference data lookups and catches a dual failure state (Low confidence + Empty knowledge reference).
3. **System** drops the standard review interface layout to prevent automated suggestion bias or human misinterpretation loops.
4. **System** changes UI display focus markers to activate an explicit, template-driven investigation layout.
5. **System** includes `UC_Q4_Annotate` to force manual measurement entries.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC_Review
usecase "Activate Clinical Investigation Mode" as UC_Core
usecase "Execute Structured Morphology Annotation" as UC_Sub
}
Rad --> UC_Review
UC_Review <.. UC_Core : <<extend>> (If low confidence & empty RAG)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 14. UC_Q4_Annotate: Execute Structured Morphology Annotation
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Execute Structured Morphology Annotation
* Actor: Diagnostic Radiologist (Rad)
* Goal: Force the manual plotting of anatomical coordinates and morphological anomalies using a strict, un-biased framework.
* Interaction: User-to-System
* Stimulus: The workspace forces a manual review layout via the active escalation workflow step.
* SysResponse: Interactive coordinate plotting arrays and mandatory clinical documentation input boxes.
* VerboseForm (Formula Reference View): "The use case 'Execute Structured Morphology Annotation' defines a User-to-System interaction where the Diagnostic Radiologist (Rad) aims to Force the manual plotting of anatomical coordinates and morphological anomalies using a strict, un-biased framework. This workflow is triggered when The workspace forces a manual review layout via the active escalation workflow step, causing the system to respond by providing Interactive coordinate plotting arrays and mandatory clinical documentation input boxes."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Execute Structured Morphology Annotation
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System UI layer has transitioned to manual investigation mode parameters (`UC_Q4_Escalate`).
* **Postconditions (Success State):**
* Specialist successfully plots manual structural bounds.
* Text verification parameters capture explicit clinical observations.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** displays an empty, un-biased ultrasound canvas frame alongside a series of mandatory measurement fields.
2. **Diagnostic Radiologist** plots coordinate points across the canvas layer to outline the boundaries of the anomalous tissue.
3. **Diagnostic Radiologist** manually populates text fields describing structural observations (e.g., bone fragments or atypical lesion shapes).
4. **System** compiles these manual coordinates and comments into a detailed case record.
5. **System** includes `UC_Q4_Queue` to route the data directly to optimization pipelines.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Execute Structured Morphology Annotation" as UC_Core
usecase "Serialize Session to Telemetry Queue" as UC_Sub
}
Rad --> UC_Core : Document manual findings
UC_Core ..> UC_Sub : <<include>>
@enduml
```
---
## 15. UC_Q4_Queue: Serialize Session to Telemetry Queue
### Notion Properties Input Panel
```text
* Name [Verb + Noun]: Serialize Session to Telemetry Queue
* Actor: Hospital EMR System (EMR)
* Goal: Route anomalous case data directly to engineering telemetry streams while bypassing standard hospital records to protect clinical data pipes.
* Interaction: System-to-System
* Stimulus: Completion of manual morphology reporting arrays within the clinical investigation interface.
* SysResponse: Packages unencrypted image tensors, coordinate arrays, and user text blocks directly into core product telemetry queues.
* VerboseForm (Formula Reference View): "The use case 'Serialize Session to Telemetry Queue' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Route anomalous case data directly to engineering telemetry streams while bypassing standard hospital records to protect clinical data pipes. This workflow is triggered when Completion of manual morphology reporting arrays within the clinical investigation interface, causing the system to respond by providing Packages unencrypted image tensors, coordinate arrays, and user text blocks directly into core product telemetry queues."
```
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Serialize Session to Telemetry Queue
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Manual morphology plotting and clinical documentation inputs are finalized (`UC_Q4_Annotate`).
* **Postconditions (Success State):**
* Case files containing structural anomalies bypass standard EMR storage pathways.
* Raw image tensors are queued in engineering streams to expand future model capabilities.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** identifies the active session as an anomalous anomaly case during final compilation.
2. **System** aggregates raw frame tensors, manual coordinate indices, and user-entered clinical commentary blocks into a secure telemetry archive package.
3. **System** bypasses standard EMR production database pipelines to protect standard hospital operational data.
4. **System** routes the telemetry package directly to the product engineering data pipeline for system optimization and future model training runs.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Serialize Session to Telemetry Queue" as UC_Core
}
UC_Core ..> EMR : (Bypasses standard production EMR sync)
@enduml
```
---

60
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-01580.md Normal file
View File

@@ -0,0 +1,60 @@
# Serialize Session to Telemetry Queue
Actor: Hospital EMR System (EMR)
DateAdd: June 7, 2026 10:37 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Route anomalous case data directly to engineering telemetry streams while bypassing standard hospital records to protect clinical data pipes
Interaction: System-to-System
Stimulus: Completion of manual morphology reporting arrays within the clinical investigation interface
SysResponse: Packages unencrypted image tensors, coordinate arrays, and user text blocks directly into core product telemetry queues
Title [Verb + Noun]: Serialize Session to Telemetry Queue
UC-ID: UC-01580
VerboseForm: The use case 'Serialize Session to Telemetry Queue' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Route anomalous case data directly to engineering telemetry streams while bypassing standard hospital records to protect clinical data pipes. This workflow is triggered when Completion of manual morphology reporting arrays within the clinical investigation interface, causing the system to respond by providing Packages unencrypted image tensors, coordinate arrays, and user text blocks directly into core product telemetry queues.
```markdown
```markdown
# Use Case Deep-Dive: Serialize Session to Telemetry Queue
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Manual morphology plotting and clinical documentation inputs are finalized (`UC_Q4_Annotate`).
* **Postconditions (Success State):**
* Case files containing structural anomalies bypass standard EMR storage pathways.
* Raw image tensors are queued in engineering streams to expand future model capabilities.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** identifies the active session as an anomalous anomaly case during final compilation.
2. **System** aggregates raw frame tensors, manual coordinate indices, and user-entered clinical commentary blocks into a secure telemetry archive package.
3. **System** bypasses standard EMR production database pipelines to protect standard hospital operational data.
4. **System** routes the telemetry package directly to the product engineering data pipeline for system optimization and future model training runs.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Serialize Session to Telemetry Queue" as UC_Core
}
UC_Core ..> EMR : (Bypasses standard production EMR sync)
@enduml
```
---
```
![image.png](Serialize%20Session%20to%20Telemetry%20Queue/image.png)

54
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-02423.md Normal file
View File

@@ -0,0 +1,54 @@
# Log High-Trust Concur Block
Actor: Hospital EMR System (EMR)
DateAdd: June 7, 2026 10:09 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Secure the human-AI alignment log trace within the final diagnostic report payload
Interaction: System-to-System
Stimulus: Explanatory panel validation completes successfully without user override actions
SysResponse: Appends a tamper-evident audit trace block verifying explicit human-AI agreement into the session log cache
Title [Verb + Noun]: Log High-Trust Concur Block
UC-ID: UC-02423
VerboseForm: The use case 'Log High-Trust Concur Block' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Secure the human-AI alignment log trace within the final diagnostic report payload. This workflow is triggered when Explanatory panel validation completes successfully without user override actions, causing the system to respond by providing Appends a tamper-evident audit trace block verifying explicit human-AI agreement into the session log cache.
![image.png](Log%20High-Trust%20Concur%20Block/image.png)
```markdown
# Use Case Deep-Dive: Log High-Trust Concur Block
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Multi-modal explanations were fully generated (`UC_Q1_Explain`) and passed without human alteration marks.
* **Postconditions (Success State):**
* Explicit audit string trace tracking high-trust convergence is formatted for downstream pipeline compilation.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** detects a direct consensus condition where the human expert confirms the model data without text/grading edits.
2. **System** serializes the multi-modal text breakdown and pixel attribution coordinates into an immutable log string block.
3. **System** assigns an explicit alignment token header flag (`HIGH_TRUST_CONCURRENCE`).
4. **System** caches this specialized tracking trace within the localized session state data, making it ready to be appended during final data hand-off routines (`UC_Finalize`).
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Log High-Trust Concur Block" as UC_Core
}
UC_Core ..> EMR : (Prepares payload for final sync)
@enduml
```
```

65
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-22159.md Normal file
View File

@@ -0,0 +1,65 @@
# Trigger Conversational Circuit Breaker
Actor: UP5
DateAdd: June 7, 2026 10:11 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Intercept premature finalization workflows if interface telemetry reveals friction, hesitation, or cognitive blind-spots
Interaction: User-to-System
Stimulus: Extended extension trace caught during review steps if user behavior markers diverge from smooth consensus paths
SysResponse: Halts default workspace finalization routes and shifts the UI into a mandatory safety evaluation mode
Title [Verb + Noun]: Trigger Conversational Circuit Breaker
UC-ID: UC-22159
VerboseForm: The use case 'Trigger Conversational Circuit Breaker' defines a User-to-System interaction where the UP5 aims to Intercept premature finalization workflows if interface telemetry reveals friction, hesitation, or cognitive blind-spots. This workflow is triggered when Extended extension trace caught during review steps if user behavior markers diverge from smooth consensus paths, causing the system to respond by providing Halts default workspace finalization routes and shifts the UI into a mandatory safety evaluation mode.
![image.png](Trigger%20Conversational%20Circuit%20Breaker/image.png)
```markdown
### Page Body Content (`SpecificationWithDiagram`)
```markdown
# Use Case Deep-Dive: Trigger Conversational Circuit Breaker
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active session is inside the `UC_Review` workflow phase.
* UI layer telemetry captures specific friction indicators (e.g., high-frequency cursor oscillation, repeatedly typing and deleting text, or conflicting grading inputs).
* **Postconditions (Success State):**
* Direct finalization path is securely locked down.
* System-forced conversational validation interface is deployed into view.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** evaluates live workspace telemetry tracking patterns during active case validation.
2. **System** detects user behavior triggers signaling high diagnostic friction or potential automatic oversight trends.
3. **System** blocks the immediate execution availability of the standard finalization command sequence (`UC_Finalize`).
4. **System** transforms workspace panel focus areas to present an interactive confirmation overlay.
5. **System** executes `UC_Q2_Socratic` to initialize direct safety check communications.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC_Review
usecase "Trigger Conversational Circuit Breaker" as UC_Core
usecase "Facilitate Socratic Reasoning Dialogue" as UC_Sub
}
Rad --> UC_Review
UC_Review <.. UC_Core : <<extend>> (If clinician friction detected)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
```

62
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-25637.md Normal file
View File

@@ -0,0 +1,62 @@
# Expose Pixel-Level Activation Logic
Actor: UP5
DateAdd: June 7, 2026 10:21 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Reveal fine-grained layer weights and activation responses when the human specialist challenges an automated grade prediction
Interaction: User-to-System
Stimulus: Clinician manually alters or rejects the ML-proposed classification score in the review pane
SysResponse: Interactive visual mapping showing the exact high-frequency noise regions driving model prediction errors
Title [Verb + Noun]: Expose Pixel-Level Activation Logic
UC-ID: UC-25637
VerboseForm: The use case ' Expose Pixel-Level Activation Logic' defines a User-to-System interaction where the UP5 aims to Reveal fine-grained layer weights and activation responses when the human specialist challenges an automated grade prediction. This workflow is triggered when Clinician manually alters or rejects the ML-proposed classification score in the review pane, causing the system to respond by providing Interactive visual mapping showing the exact high-frequency noise regions driving model prediction errors.
```markdown
```markdown
# Use Case Deep-Dive: Expose Pixel-Level Activation Logic
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active session is inside the `UC_Review` interface phase.
* Specialist chooses an option that breaks clean model agreement paths.
* **Postconditions (Success State):**
* Internal neural layer weight vectors are visually mapped onto the primary medical viewport.
* Core manual artifact isolation tool sets become active on the canvas layout.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** changes the system-suggested grade classification dropdown setting.
2. **System** captures the modification step and branches away from the standard review pathway to reveal underlying model mechanics.
3. **System** transforms image layers to display fine-grained activation weights, revealing exactly which pixel clusters (e.g., acoustic shadowing regions or bone interfaces) skewed the model's calculation.
4. **System** includes `UC_Q3_Isolate` to let the specialist manually clean up the noise zones.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC_Review
usecase "Expose Pixel-Level Activation Logic" as UC_Core
usecase "Isolate Visual Noise/Artifacts" as UC_Sub
}
Rad --> UC_Review
UC_Review <.. UC_Core : <<extend>> (If clinician contests AI score)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
```
![image.png](Expose%20Pixel-Level%20Activation%20Logic/image.png)

58
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-25776.md Normal file
View File

@@ -0,0 +1,58 @@
# Generate GradCAM & CoT Explanation Panel
Actor: UP5
DateAdd: June 7, 2026 10:00 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Present clear, pixel-linked visuospatial explanations and multi-modal clinical reasoning for high-trust verification
Interaction: User-to-System
Stimulus: Inclusion trigger initialized during session data intake (Load Patient Scan Session)
SysResponse: Renders heatmaps highlighting model focus zones alongside structured, clear reasoning steps
Title [Verb + Noun]: Generate GradCAM & CoT Explanation Panel
UC-ID: UC-25776
VerboseForm: The use case 'Generate GradCAM & CoT Explanation Panel' defines a User-to-System interaction where the UP5 aims to Present clear, pixel-linked visuospatial explanations and multi-modal clinical reasoning for high-trust verification. This workflow is triggered when Inclusion trigger initialized during session data intake (Load Patient Scan Session), causing the system to respond by providing Renders heatmaps highlighting model focus zones alongside structured, clear reasoning steps.
![image.png](Generate%20GradCAM%20&%20CoT%20Explanation%20Panel/image.png)
```markdown
# Use Case Deep-Dive: Generate GradCAM & CoT Explanation Panel
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Raw image frames and vision engine inference matrix weights have been imported via `Load Patient Scan Session`.
* **Postconditions (Success State):**
* Split-screen layout displays visual explanation elements without adding visual noise to the core image frame workspace canvas.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** evaluates the internal deep-learning model gradient parameters for the target ultrasound image slice.
2. **System** generates a visual GradCAM heatmap layer mapping feature locations that dictated model classifications (e.g., hypervascularized synovial proliferation zones).
3. **System** maps multi-modal prompt metrics through the internal LLM Explainer module to produce a concise, point-by-point clinical reasoning string.
4. **System** populates the split-screen workspace sub-section block with this explanation data to guide human inspection efficiently.
5. **System** includes `UC_Q1_Log` to serialize verification metadata.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Generate GradCAM & CoT Explanation Panel" as UC_Core
usecase "Log High-Trust Concur Block" as UC_Sub
}
Rad --> UC_Core
UC_Core ..> UC_Sub : <<include>>
@enduml
```
```

64
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-35956.md Normal file
View File

@@ -0,0 +1,64 @@
# Activate Clinical Investigation Mode
Actor: UP5
DateAdd: June 7, 2026 10:29 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Switch the system into a strict, template-driven manual examination mode when low vision confidence values align with a lack of reference data
Interaction: User-to-System
Stimulus: The workspace detects a critical double-blind failure criteria match during the case evaluation phase
SysResponse: Disables automated diagnostic suggestions entirely and forces a standardized manual morphology review
Title [Verb + Noun]: Activate Clinical Investigation Mode
UC-ID: UC-35956
VerboseForm: The use case 'Activate Clinical Investigation Mode' defines a User-to-System interaction where the UP5 aims to Switch the system into a strict, template-driven manual examination mode when low vision confidence values align with a lack of reference data. This workflow is triggered when The workspace detects a critical double-blind failure criteria match during the case evaluation phase, causing the system to respond by providing Disables automated diagnostic suggestions entirely and forces a standardized manual morphology review.
```markdown
```markdown
# Use Case Deep-Dive: Activate Clinical Investigation Mode
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System classification loops return low-confidence indices.
* Authoritative RAG reference lookups return no matches, indicating an unmapped anatomical variant or a severe image anomaly.
* **Postconditions (Success State):**
* Automated suggestions are masked out to prevent cognitive bias.
* Mandatory manual template verification frameworks are deployed into active workspace view.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** monitors deep-learning inference score bounds during case evaluation.
2. **System** runs background reference data lookups and catches a dual failure state (Low confidence + Empty knowledge reference).
3. **System** drops the standard review interface layout to prevent automated suggestion bias or human misinterpretation loops.
4. **System** changes UI display focus markers to activate an explicit, template-driven investigation layout.
5. **System** includes `UC_Q4_Annotate` to force manual measurement entries.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC_Review
usecase "Activate Clinical Investigation Mode" as UC_Core
usecase "Execute Structured Morphology Annotation" as UC_Sub
}
Rad --> UC_Review
UC_Review <.. UC_Core : <<extend>> (If low confidence & empty RAG)
UC_Core ..> UC_Sub : <<include>>
@enduml
```
```
![image.png](Activate%20Clinical%20Investigation%20Mode/image.png)

61
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-47796.md Normal file
View File

@@ -0,0 +1,61 @@
# Execute Structured Morphology Annotation
Actor: UNK
DateAdd: June 7, 2026 10:32 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Force the manual plotting of anatomical coordinates and morphological anomalies using a strict, un-biased framework
Interaction: User-to-System
Stimulus: The workspace forces a manual review layout via the active escalation workflow step
SysResponse: Interactive visual mapping showing the exact high-frequency noise regions driving model prediction errors
Title [Verb + Noun]: Execute Structured Morphology Annotation
UC-ID: UC-47796
VerboseForm: The use case 'Execute Structured Morphology Annotation' defines a User-to-System interaction where the UNK aims to Force the manual plotting of anatomical coordinates and morphological anomalies using a strict, un-biased framework. This workflow is triggered when The workspace forces a manual review layout via the active escalation workflow step, causing the system to respond by providing Interactive visual mapping showing the exact high-frequency noise regions driving model prediction errors.
```markdown
```markdown
# Use Case Deep-Dive: Execute Structured Morphology Annotation
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System UI layer has transitioned to manual investigation mode parameters (`UC_Q4_Escalate`).
* **Postconditions (Success State):**
* Specialist successfully plots manual structural bounds.
* Text verification parameters capture explicit clinical observations.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** displays an empty, un-biased ultrasound canvas frame alongside a series of mandatory measurement fields.
2. **Diagnostic Radiologist** plots coordinate points across the canvas layer to outline the boundaries of the anomalous tissue.
3. **Diagnostic Radiologist** manually populates text fields describing structural observations (e.g., bone fragments or atypical lesion shapes).
4. **System** compiles these manual coordinates and comments into a detailed case record.
5. **System** includes `UC_Q4_Queue` to route the data directly to optimization pipelines.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Execute Structured Morphology Annotation" as UC_Core
usecase "Serialize Session to Telemetry Queue" as UC_Sub
}
Rad --> UC_Core : Document manual findings
UC_Core ..> UC_Sub : <<include>>
@enduml
```
```
![image.png](Execute%20Structured%20Morphology%20Annotation/image.png)

74
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-47988.md Normal file
View File

@@ -0,0 +1,74 @@
# Review Suggested Synovitis Grade (0-3)
Actor: UP5
DateAdd: June 7, 2026 9:54 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Evaluate the ML engine's (VKIST-visual detector & classifier) proposed synovitis classification and structural overlays
Interaction: User-to-System
Stimulus: The workspace completes localized UI construction and displays the diagnostic panel
SysResponse: Display of classification metrics (Grades 0-3), color-coded overlays, and active risk-extension hooks
Title [Verb + Noun]: Review Suggested Synovitis Grade (0-3)
UC-ID: UC-47988
VerboseForm: The use case 'Review Suggested Synovitis Grade (0-3)' defines a User-to-System interaction where the UP5 aims to Evaluate the ML engine's (VKIST-visual detector & classifier) proposed synovitis classification and structural overlays. This workflow is triggered when The workspace completes localized UI construction and displays the diagnostic panel, causing the system to respond by providing Display of classification metrics (Grades 0-3), color-coded overlays, and active risk-extension hooks.
```markdown
```markdown
# Use Case Deep-Dive: Review Suggested Synovitis Grade (0-3)
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Image frames and raw ML prediction tensors (segmentation masks, classification weights) are fully loaded in memory via `Load Patient Scan Session`.
* **Postconditions (Success State):**
* System records human gaze/interaction initialization flags.
* System keeps exception-based extend vectors armed (`UC_Q2_Intercept`, `UC_Q3_Expose`, `UC_Q4_Escalate`).
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** presents the active ultrasound canvas with interactive, toggleable, color-coded segmentation mask overlays.
2. **System** displays the vision engine's suggested synovitis grading estimation (Grade 0, 1, 2, or 3) alongside structural pixel-percentage distribution metrics.
3. **Diagnostic Radiologist** inspects the spatial distribution of the synovial hypertrophy markers and reads the inline text panels.
4. **Diagnostic Radiologist** approves the visual data metrics without requesting alterations or triggering corrective dialogue paths.
### Alternative & Exception Flows
* **Extension Flow A: Clinician Friction / Disagreement Caught**
* At step [3], if mouse click frequencies suggest hesitation or manual adjustments cross a conflict delta threshold, the execution path triggers `UC_Q2_Intercept` to prevent blind override errors.
* **Extension Flow B: Expert Contests Automated Grade**
* At step [3], if the clinician explicitly changes the classification dropdown away from the ML-proposed score, the workspace extends to `UC_Q3_Expose` to display the machine activation weights.
* **Extension Flow C: Anomaly / Confidence Failure Detected**
* At step [1], if the deep-learning array returned a classification confidence metric below safety bounds paired with blank knowledge base lookups, the interface branches into `UC_Q4_Escalate`.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Review Suggested Synovitis Grade (0-3)" as UC_Core
usecase "Trigger Conversational Circuit Breaker" as UC_Q2
usecase "Expose Pixel-Level Activation Logic" as UC_Q3
usecase "Activate Clinical Investigation Mode" as UC_Q4
}
Rad --> UC_Core
UC_Core <.. UC_Q2 : <<extend>>
UC_Core <.. UC_Q3 : <<extend>>
UC_Core <.. UC_Q4 : <<extend>>
@enduml
```
```
```
![image.png](Review%20Suggested%20Synovitis%20Grade%20(0-3)/image.png)

66
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-48376.md Normal file
View File

@@ -0,0 +1,66 @@
# Load Patient Scan Session
Actor: UP5, VKIST Vision Grader Engine (Grader)
DateAdd: June 6, 2026 1:01 AM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Ingest raw ultrasound frame arrays and initialize the diagnostic session state
Interaction: System-to-System, User-to-System
Stimulus: User opens an unreviewed patient file, or the workspace catches an active DICOM stream hook
SysResponse: Confirmation that raw frame arrays are mapped, spatial calibrations are set, and the local session state is active
Title [Verb + Noun]: Load Patient Scan Session
UC-ID: UC-48376
VerboseForm: The use case 'Load Patient Scan Session' defines a User-to-System,System-to-System interaction where the UP5, VKIST Vision Grader Engine (Grader) aims to Ingest raw ultrasound frame arrays and initialize the diagnostic session state. This workflow is triggered when User opens an unreviewed patient file, or the workspace catches an active DICOM stream hook, causing the system to respond by providing Confirmation that raw frame arrays are mapped, spatial calibrations are set, and the local session state is active.
```markdown
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Local workspace application is authenticated and has secure socket access to the local image buffer.
* DICOM/raw frame data payload is uncorrupted and readable.
* **Postconditions (Success State):**
* Core frame parameters are loaded into memory with spatial scale calibrations preserved.
* Background parsing pipeline registers the unique session hash and prepares the context matrix for downstream agents.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** selects a patient case file from the workspace worklist interface.
2. **VKIST Vision Grader Engine** feeds raw ultrasound image tensors, spatial calibrations, and foundational frame telemetry metadata into the workspace memory layer.
3. **System** extracts pixel dimensions and constructs localized rendering viewports.
4. **System** includes `UC_Q1_Explain` in the background to spin up explanation prompt matrices.
5. **System** displays the fully loaded image frame in the workspace canvas, preparing the viewport for immediate review.
### Alternative & Exception Flows
* **Exception Flow A: Corrupted Image Frame Payload**
* At step [2], if the payload data fails format validation or structural check headers, the system halts execution, logs a data corruption fault code, and alerts the user with an "Unable to Parse Scan Session" dialog box.
* **Exception Flow B: Resolution / Calibration Mismatch**
* At step [3], if spatial aspect ratios or metadata pixel matrices lack the standardized calibration tags required by the vision engine, the workspace falls back to a safe default scale flag and displays a non-blocking diagnostic accuracy warning icon.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
actor "VKIST Vision Grader Engine" as Grader << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Load Patient Scan Session" as UC_Core
usecase "Generate GradCAM & CoT Explanation Panel" as UC_Sub
}
Rad --> UC_Core
Grader --> UC_Core
UC_Core ..> UC_Sub : <<include>>
@enduml
```
```
![image.png](Load%20Patient%20Scan%20Session/image.png)

59
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-55146.md Normal file
View File

@@ -0,0 +1,59 @@
# Facilitate Socratic Reasoning Dialogue
Actor: UP5
DateAdd: June 7, 2026 10:14 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Engage the specialist in a targeted, conversational double-check loop regarding controversial structural markers.
Interaction: User-to-System
Stimulus: Core execution request passed down by the active circuit breaker module.
SysResponse: Interactive conversational sub-panel displaying focused prompt choices that check specific diagnostic criteria
Title [Verb + Noun]: Facilitate Socratic Reasoning Dialogue
UC-ID: UC-55146
VerboseForm: The use case 'Facilitate Socratic Reasoning Dialogue' defines a User-to-System interaction where the UP5 aims to Engage the specialist in a targeted, conversational double-check loop regarding controversial structural markers.. This workflow is triggered when Core execution request passed down by the active circuit breaker module., causing the system to respond by providing Interactive conversational sub-panel displaying focused prompt choices that check specific diagnostic criteria.
```markdown
```markdown
# Use Case Deep-Dive: Facilitate Socratic Reasoning Dialogue
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Circuit breaker safety intercept sequence has completed successfully, freezing generic CRUD paths.
* **Postconditions (Success State):**
* User inputs conversational defense arguments or confirms specific anatomical findings.
* Live conversation data tokens are actively streamed to automated safety monitors.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** initializes a conversational chat element right next to the ultrasound display field.
2. **System** presents a non-confrontational, clinically grounded question regarding the identified discrepancies (e.g., *"Note the echo-free thickening layer in the suprapatellar recess; please confirm if this modification represents minor effusion or structural pannus tissue"*).
3. **Diagnostic Radiologist** enters text responses or selects structural tag tokens to clarify their assessment.
4. **System** includes `UC_Q2_BERT` in real time to process active conversation token patterns.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Facilitate Socratic Reasoning Dialogue" as UC_Core
usecase "Monitor Drift via BERT Sub-Layer" as UC_Sub
}
Rad --> UC_Core : Argue observations
UC_Core ..> UC_Sub : <<include>>
@enduml
```
```
![image.png](Facilitate%20Socratic%20Reasoning%20Dialogue/image.png)

60
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-60739.md Normal file
View File

@@ -0,0 +1,60 @@
# Isolate Visual Noise/Artifacts
Actor: UP5
DateAdd: June 7, 2026 10:24 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Provide manual brush and selection overlays to mask out acoustic shadows, bone scattering, or artifacts causing model calculation errors.
Interaction: User-to-System
Stimulus: Human operator activates canvas cleanup tools within the exposed model layer layout
SysResponse: Real-time visual updates to the pixel mask array, isolating clean anatomical structures from surrounding imaging noise
Title [Verb + Noun]: Isolate Visual Noise/Artifacts
UC-ID: UC-60739
VerboseForm: The use case 'Isolate Visual Noise/Artifacts' defines a User-to-System interaction where the UP5 aims to Provide manual brush and selection overlays to mask out acoustic shadows, bone scattering, or artifacts causing model calculation errors.. This workflow is triggered when Human operator activates canvas cleanup tools within the exposed model layer layout, causing the system to respond by providing Real-time visual updates to the pixel mask array, isolating clean anatomical structures from surrounding imaging noise.
```markdown
```markdown
# Use Case Deep-Dive: Isolate Visual Noise/Artifacts
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* System exposure arrays are visible across the image viewport layout (`UC_Q3_Expose`).
* **Postconditions (Success State):**
* Corrected ground-truth frame masks are calculated and locked into memory.
* System updates local diagnostic metrics using the isolated anatomical data.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** activates a manual canvas tool overlay, giving the user access to high-precision brush, eraser, and selection vectors.
2. **Diagnostic Radiologist** applies brush vectors directly over areas containing acoustic artifacts or non-synovial structures that skewed the automated classification score.
3. **System** recalculates active region dimensions in real time, excluding the masked pixels from the active grading parameters.
4. **System** updates diagnostic panel displays to confirm the human-corrected measurements.
5. **System** includes `UC_Q3_Commit` to lock the updated session state securely.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Isolate Visual Noise/Artifacts" as UC_Core
usecase "Commit Validated Ground-Truth Record" as UC_Sub
}
Rad --> UC_Core : Tag artifacts
UC_Core ..> UC_Sub : <<include>>
@enduml
```
```
![image.png](Isolate%20Visual%20Noise%20Artifacts/image.png)

57
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-62864.md Normal file
View File

@@ -0,0 +1,57 @@
# Commit Validated Ground-Truth Record
Actor: Hospital EMR System (EMR)
DateAdd: June 7, 2026 10:26 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Secure the human-corrected ground-truth dataset variant while appending clean, expert-validated report payloads to the EMR
Interaction: System-to-System
Stimulus: Completion of manual artifact masking operations and confirmation of corrected metrics
SysResponse: Stores the corrected medical report in the EMR and saves the isolated image mask to an optimization cache for subsequent retraining
Title [Verb + Noun]: Commit Validated Ground-Truth Record
UC-ID: UC-62864
VerboseForm: The use case 'Commit Validated Ground-Truth Record' defines a System-to-System interaction where the Hospital EMR System (EMR) aims to Secure the human-corrected ground-truth dataset variant while appending clean, expert-validated report payloads to the EMR. This workflow is triggered when Completion of manual artifact masking operations and confirmation of corrected metrics, causing the system to respond by providing Stores the corrected medical report in the EMR and saves the isolated image mask to an optimization cache for subsequent retraining.
```markdown
```markdown
# Use Case Deep-Dive: Commit Validated Ground-Truth Record
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Human-directed canvas modification steps are locked in place without remaining pixel parity errors (`UC_Q3_Isolate`).
* **Postconditions (Success State):**
* EMR database updates receive the human expert's diagnostic findings.
* Isolated ground-truth tensor pairs are safely cached for AI training refinement runs.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** packages the human expert's corrected diagnostic data metrics into the primary transmission bundle.
2. **System** isolates the human-brushed image mask layers alongside the initial incorrect model classification output.
3. **System** tags the data pair as a validated retraining asset (`GROUND_TRUTH_OVERRIDE`).
4. **System** saves the optimization asset to a secure local retraining storage folder, while preparing the primary medical report for delivery to the **Hospital EMR System**.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Commit Validated Ground-Truth Record" as UC_Core
}
UC_Core ..> EMR : (Prepares clean report for EMR sync)
@enduml
```
```
![image.png](Commit%20Validated%20Ground-Truth%20Record/image.png)

59
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-65473.md Normal file
View File

@@ -0,0 +1,59 @@
# Arbitrate Evidence via RAG-Referee
Actor: UP5
DateAdd: June 7, 2026 10:18 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Query static, authoritative clinical knowledge bases to resolve human-machine disagreements with objective evidence
Interaction: User-to-System
Stimulus: Triggered when communication tracking scores cross a severe semantic mismatch or impasse threshold
SysResponse: Inline injection of un-biased diagnostic text extracts and guidelines matching the active frame conditions
Title [Verb + Noun]: Arbitrate Evidence via RAG-Referee
UC-ID: UC-65473
VerboseForm: The use case 'Arbitrate Evidence via RAG-Referee' defines a User-to-System interaction where the UP5 aims to Query static, authoritative clinical knowledge bases to resolve human-machine disagreements with objective evidence. This workflow is triggered when Triggered when communication tracking scores cross a severe semantic mismatch or impasse threshold, causing the system to respond by providing Inline injection of un-biased diagnostic text extracts and guidelines matching the active frame conditions.
```markdown
```markdown
# Use Case Deep-Dive: Arbitrate Evidence via RAG-Referee
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* BERT analytics layers detect a diagnostic impasse or significant semantic drift.
* Authoritative local clinical knowledge base index (e.g., OMERACT synovitis grading reference manuals) is online and responsive.
* **Postconditions (Success State):**
* Disagreement matrix is resolved via verified medical data injection.
* Final chosen path is linked directly to a standard medical guideline anchor.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** halts active conversational dialogue inputs temporarily to execute a localized context search.
2. **System** extracts spatial measurements and text tokens to construct a specialized RAG search string.
3. **System** queries local, validated medical knowledge data banks to locate matching diagnostic criteria sections.
4. **System** displays the verified guideline text extract right inside the workspace alert view block (e.g., *"OMERACT standardizes Grade 2 as hypoechoic synovial hypertrophy demonstrating fluid-filled distension up to structural boundary bounds"*).
5. **Diagnostic Radiologist** reviews the authoritative reference framework and either adjusts their classification choice or submits a structured expert override justifying their deviation.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Arbitrate Evidence via RAG-Referee" as UC_Core
}
Rad --> UC_Core
@enduml
```
```
![image.png](Arbitrate%20Evidence%20via%20RAG-Referee/image.png)

64
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-74821.md Normal file
View File

@@ -0,0 +1,64 @@
# Monitor Context Drift via BERT Sub-Layer
Actor: UP5
DateAdd: June 7, 2026 10:17 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Continuously parse communication tokens to identify logical contradictions or semantic drift during clinical debates
Interaction: User-to-System
Stimulus: Streamed entry of communication tokens within the active dialogue loop
SysResponse: Real-time semantic checking flags; extends out to the RAG referee if an impasse or severe drift is captured
Title [Verb + Noun]: Monitor Context Drift via BERT Sub-Layer
UC-ID: UC-74821
VerboseForm: The use case 'Monitor Context Drift via BERT Sub-Layer' defines a User-to-System interaction where the UP5 aims to Continuously parse communication tokens to identify logical contradictions or semantic drift during clinical debates. This workflow is triggered when Streamed entry of communication tokens within the active dialogue loop, causing the system to respond by providing Real-time semantic checking flags; extends out to the RAG referee if an impasse or severe drift is captured.
```markdown
```markdown
# Use Case Deep-Dive: Monitor Drift via BERT Sub-Layer
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active conversational dialogue module is processing user data strings (`UC_Q2_Socratic`).
* **Postconditions (Success State):**
* Log structures capture semantic alignment metrics.
* System successfully catches contradictions before data parameters flow to final storage.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **System** continuously intercepts conversation tokens as the human expert types input strings.
2. **System** runs token matrices through an embedded BERT checking model to calculate contextual semantic coherence scores.
3. **System** verifies that user claims line up logically with the visual indicators under review.
4. **System** approves the validated conversational step, allowing the specialist to complete the confirmation cycle smoothly.
### Alternative & Exception Flows
* **Extension Flow A: Impasse or Semantic Contradiction Detected**
* At step [3], if the specialist's input text contradicts objective structural metrics (e.g., claiming a region is "completely normal" while the visual layer registers massive synovial proliferation) or exhibits context drift, the process branches into `UC_Q2_Arbiter` to request evidence evaluation.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Monitor Drift via BERT Sub-Layer" as UC_Core
usecase "Arbitrate Evidence via RAG-Referee" as UC_Ext
}
Rad --> UC_Core
UC_Core <.. UC_Ext : <<extend>> (If impasse or semantic drift caught)
@enduml
```
```
![image.png](Monitor%20Context%20Drift%20via%20BERT%20Sub-Layer/image.png)

69
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC-92006.md Normal file
View File

@@ -0,0 +1,69 @@
# Finalize & Sign Electronic Record
Actor: Hospital EMR System (EMR), UP5
DateAdd: June 7, 2026 9:54 PM
Engineer: Đạt Trần Tiến (Daves Tran)
Functional Requirement Engineer DB: CHUẨN ĐOÁN Phân loại Mức độ Viêm Khớp gối (https://app.notion.com/p/CHU-N-O-N-Ph-n-lo-i-M-c-Vi-m-Kh-p-g-i-375f910aea75800199d4feb8b07f9145?pvs=21)
Goal: Authenticate, cryptographically seal, and sync verified diagnostic reports down to storage infrastructure
Interaction: System-to-System, User-to-System
Stimulus: User executes the final confirmation/signature command button in the workspace utility ribbon
SysResponse: Generation of a signed cryptographic log block and structured JSON transmission payload delivered to the EMR endpoint
Title [Verb + Noun]: Finalize & Sign Electronic Record
UC-ID: UC-92006
VerboseForm: The use case 'Finalize & Sign Electronic Record' defines a User-to-System,System-to-System interaction where the UP5, Hospital EMR System (EMR) aims to Authenticate, cryptographically seal, and sync verified diagnostic reports down to storage infrastructure. This workflow is triggered when User executes the final confirmation/signature command button in the workspace utility ribbon, causing the system to respond by providing Generation of a signed cryptographic log block and structured JSON transmission payload delivered to the EMR endpoint.
![image.png](Finalize%20&%20Sign%20Electronic%20Record/image.png)
```markdown
```markdown
# Use Case Deep-Dive: Finalize & Sign Electronic Record
## 1. Structural Preconditions & Postconditions
* **Preconditions:**
* Active scan session evaluation has been resolved, and grading metrics are verified by the human specialist.
* Local localized network channel to the hospital server framework is functional.
* **Postconditions (Success State):**
* Session record is transformed into a read-only state.
* Standardized structural JSON payload data is safely stored within the Hospital EMR System sink.
---
## 2. Interaction Scenarios (Step-by-Step Flow)
### Main Success Scenario (Happy Path)
1. **Diagnostic Radiologist** initiates the session finalization pipeline by interacting with the cryptographic signature command trigger.
2. **System** prompts for the secure authentication credentials of the signing specialist.
3. **System** generates a unified clinical log structure, packing structural thickness measurements (mm), final validated synovitis tier scores, and accompanying multi-agent trace logs.
4. **System** calculates a secure cryptographic data hash, locking the session record into an immutable post-review profile.
5. **System** delivers the structured data package across localized network pipes to the **Hospital EMR System**.
6. **Hospital EMR System** confirms safe database commit storage updates and provides an acknowledgment packet back to the workspace.
### Alternative & Exception Flows
* **Exception Flow A: Network Pipeline Transmission Failure**
* At step [5], if network communications timeout or socket breaks occur, the workspace locks the finalized JSON package into a local encrypted offline buffer, changes the session status tag to "Pending Sync", and presents a clear connectivity warning alert.
---
## 3. PlantUML Visual Model
```plantuml
@startuml
left to right direction
skin rose
actor "Diagnostic Radiologist" as Rad
actor "Hospital EMR System" as EMR << System >>
rectangle "VKIST MSK Workspace (FR-25)" {
usecase "Finalize & Sign Electronic Record" as UC_Core
}
Rad --> UC_Core
UC_Core ..> EMR : Sync standardized structural JSON data
@enduml
```
```
```

282
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/UC_CONTEXT.md Normal file
View File

@@ -0,0 +1,282 @@
# CONTEXT.md for the Usecase Discovery : FR-25
- The requirement: FR-25 == ULTS-Đánh giá và phân cấp mức độ viêm màng hoạt dịch (Synovitis Grading)
- Explain why the se should care on this usecase in the design process
- **The Gap:** Lợi ích kỹ thuật & Giá trị cốt lõi của Use Case Phân cấp Viêm màng hoạt dịch đối với Kiến trúc Phần mềm (Missing Clinical rationale vs. Engineering value optimization for Synovitis Grading).
- **The Question:** Tại sao quy trình lâm sàng chuẩn hóa này lại đảm bảo tính chính xác khi phân cấp (`Synovitis Grading`) và tại sao một Kỹ sư Phần mềm (SE) phải đặc biệt quan tâm đến Use Case này khi thiết kế sản phẩm?
- **The Hint:** Để xây dựng một sản phẩm Y tế (Healthcare AI Product) thành công, chúng ta không được coi Use Case này chỉ là một tính năng CRUD hay hiển thị ảnh đơn thuần. Hiểu rõ bản chất toán học/vật lý của quy trình giúp SE thiết kế cơ chế lưu trữ dữ liệu (Data Schema), cấu hình Pipeline xử lý ảnh AI và tối ưu hóa trải nghiệm UIX không bị lỗi logic giải phẫu.
- **The Recommendations:** Dưới đây là câu trả lời phân tích sâu dưới góc nhìn của một Kỹ sư Hệ thống / Lập trình viên:
### PHẦN 1: Tại sao quy trình này đảm bảo việc phát hiện và phân cấp chính xác? (Góc nhìn Data Pipeline & Signal Processing)
Nếu coi cơ thể người là một hệ thống phần cứng và máy siêu âm là một module quét dữ liệu ngoại vi (Hardware Scanner), quy trình 6 bước lâm sàng chính là các điều kiện tiền đề để **đảm bảo tính toàn vẹn của tín hiệu (Signal Integrity)** và ngăn chặn **nhiễu dữ liệu (Data Corruption)**:
1. **Khử nhiễu biên (Eliminating Boundary Noise - Bước 1):** việc gập đầu gối 20°–30° tương đương với việc thực hiện lệnh `Format / Standardize` bề mặt quét. Nó triệt tiêu hiện tượng *Bất đẳng hướng âm học (Acoustic Anisotropy)* – vốn là một dạng nhiễu tín hiệu vật lý khiến mô khỏe mạnh bị biến đổi thành các pixel đen giả lập tổn thương.
2. **Cố định Hệ tọa độ (Fixing Coordinate System - Bước 2):** Đặt đầu dò dọc (`Longitudinal`) giúp mô hình AI thu được một contract dữ liệu ảnh tĩnh có cấu trúc giải phẫu phân tầng rõ ràng (`Multi-layered Frame`). Đỉnh xương bánh chè hoạt động như một điểm mốc $X, Y = (0,0)$ cố định để hệ thống chạy Edge Detection chuẩn xác.
3. **Phân tích Đa luồng song song (Multi-threading Analytics - Bước 3 & 4):**
- **Luồng B-Mode (Cấu trúc Hình học):** Trích xuất độ dày mô (`float thickness_mm`) $\rightarrow$ Phản ánh dung lượng thiệt hại vật lý tĩnh (Structural Damage).
- **Luồng Power Doppler (Lưu lượng Biến động):** Trích xuất mật độ màu của dòng máu (`float vascular_percentage`) $\rightarrow$ Phản ánh lưu lượng dữ liệu thời gian thực đang chạy (Active Inflammation).
4. **Tránh lỗi nén hệ thống (Avoiding Signal Throttling):** Việc lướt nhẹ tay đầu dò (minimal pressure) giữ cho luồng truyền dẫn tín hiệu mạch máu không bị bóp nghẹt (Throttling), tránh việc hệ thống tính toán sai lệch điểm số hoạt tử/viêm mạch dẫn đến kết quả âm tính giả.
### PHẦN 2: Tại sao Kỹ sư Phần mềm (SE) phải đặc biệt quan tâm đến Use Case này?
Từ góc nhìn sản phẩm và kiến trúc hệ thống của dự án `VKIST_ULTRASOUND`, đây không phải là một tính năng bổ sung, mà chính là **Core Core Business Logic (Lõi nghiệp vụ quyết định)** vì các lý do sau:
### 1. Định hình Data Model (Schema) cho toàn bộ hệ thống
Nếu không hiểu quy trình này, bạn sẽ thiết kế cơ sở dữ liệu bị thiếu trường dữ liệu nghiêm trọng. Điểm số `Synovitis Grade` không thể lưu dưới dạng một trường `int grade` đơn giản. Dữ liệu y khoa chuẩn hóa bắt buộc phải là một đối tượng phức hợp (Compound Object Model):
JSON
```
{
"patient_id": "BN-10023",
"scan_metadata": {
"joint": "KNEE",
"side": "RIGHT",
"plane": "suprapat-long",
"patient_flexion_degree": 25
},
"extracted_metrics": {
"synovial_thickness_mm": 4.2,
"power_doppler_area_percentage": 34.5
},
"severity_classification": {
"suggested_grade": 2,
"confirmed_grade": 2,
"is_overridden_by_doctor": false
}
}
```
### 2. Kích hoạt State Machine & Pipeline xử lý của AI (Mô tả trong tài liệu VKIST)
Theo tài liệu kiến trúc của hệ thống, Use Case này là điểm kết thúc (`Final Destination`) của một Pipeline phân nhánh phức tạp. Khi ảnh DICOM/Siêu âm được đẩy lên hệ thống:
- **Mô hình 1 (ConvNeXt):** Kiểm tra góc chụp. Nếu và chỉ nếu kết quả trả về đúng `sup_up_long`, hệ thống mới kích hoạt State tiếp theo.
- **Mô hình 2 (EfficientNet/MedViT):** Kiểm tra trạng thái phân loại nhị phân `Has Inflammation = True/False`.
- **Mô hình 3 (MedSAM/UNet):** Tiến hành phân đoạn vùng ảnh (Segmentation) tạo Mask đè màu để tính toán diện tích pixel bị tổn thương, từ đó tự động map ra điểm số Phân cấp từ 0 đến 3.
Nếu Use Case này bị lỗi hoặc UIX thiết kế không khớp, toàn bộ Pipeline AI trị giá hàng nghìn giờ huấn luyện phía sau sẽ mất hoàn toàn giá trị sử dụng thực tế.
### 3. Giải quyết bài toán Tải trọng hệ thống và Kiệt sức lâm sàng (Clinical Exhaustion)
Tại các bệnh viện công tuyến trung ương của Việt Nam (Bạch Mai, Bệnh viện E), một bác sĩ (UP5) phải xử lý >100 ca/ca trực.
- Nếu không có phần mềm: Bác sĩ phải đổi ghế, chuyển ứng dụng, gõ tay kết quả vào hệ thống EMR thủ công $\rightarrow$ Nút thắt cổ chai gây delay hệ thống (Latency).
- Khi có Use Case này được tự động hóa trên Dashboard: AI tính toán diện tích, trả về gợi ý bậc viêm ngay trên canvas xem ảnh, bác sĩ chỉ mất đúng 1 click chuột để xác nhận và Sync tự động sang Database tổng. Bạn đang giúp bệnh viện giảm thời gian xử lý một ca từ 5 phút xuống còn 30 giây, trực tiếp tối ưu hóa thông lượng (Throughput) cho toàn bộ hạ tầng y tế.
- **The Alignment Check:** Với góc nhìn bóc tách hệ thống và phân tích Pipeline tín hiệu/AI như trên, bạn đã thấy rõ được bài toán kiến trúc mình cần giải quyết ở Use Case này chưa, hay có điểm nào cần làm sáng tỏ thêm trước khi chúng ta vẽ sơ đồ Use Case bằng PlantUML?
- Explain Why doctor are caring so much on this usecase
- **The Gap:** Hiểu rõ động lực lâm sàng và giá trị chẩn đoán thực tế của Bác sĩ (Missing Clinical Drivers and Real-World Diagnostic Insights for Synovitis Grading).
- **The Question:** Tại sao Bác sĩ Chẩn đoán hình ảnh (UP5) lại đặc biệt quan tâm đến Use Case Phân cấp Viêm màng hoạt dịch (`Synovitis Grading`), và chỉ số này tiết lộ điều gì cốt lõi trong hành trình chẩn đoán, điều trị của bệnh nhân?
- **The Hint:** Trong y khoa, bản thân hình ảnh siêu âm xám chỉ là dữ liệu thô (raw data). Kết quả phân cấp từ Use Case này chính là **thông tin có cấu trúc (structured insights)** giúp bác sĩ trả lời câu hỏi cốt lõi của lâm sàng: Bệnh nhân này đang bị tàn phá khớp ở mức độ nào, tổn thương này là mạn tính (sẹo mô) hay cấp tính (đang bùng phát), và phác đồ điều trị bằng thuốc hoặc can thiệp ngoại khoa nào là chính xác nhất.
- **The Recommendations:** Dưới đây là bóc tách chi tiết lý do vì sao bác sĩ cần Use Case này, được phân tích rõ ràng để một Kỹ sư Phần mềm nắm bắt trọn vẹn nghiệp vụ (Domain Knowledge):
### 1. Phân biệt Giữa "Tổn thương Cũ" (Mạn tính) và "Đợt Viêm Cấp" (Đang bùng phát)
- **Ý nghĩa lâm sàng:** Khi nhìn vào ảnh siêu âm đen trắng (B-mode), bác sĩ thấy một vùng màng hoạt dịch dày lên (ví dụ: dày 4mm). Tuy nhiên, ảnh đen trắng đơn thuần **không thể** cho biết vùng phì đại đó là vết sẹo cũ từ 3 năm trước (mô xơ đã ổn định) hay là vùng mô đang liên tục sưng tấy, ăn mòn sụn khớp.
- **Use Case tiết lộ điều gì:** Bằng cách kết hợp luồng dữ liệu của **Power Doppler**, Use Case này bóc tách và định lượng chính xác mật độ mạch máu tăng sinh (`Hypervascularity`).
- *Dày mô + Không có tín hiệu Doppler (Grade 1):* Tổn thương cũ, chỉ cần theo dõi hoặc vật lý trị liệu.
- *Dày mô + Tín hiệu Doppler dày đặc (Grade 3):* Ổ viêm đang hoạt động cực kỳ dữ dội. Hệ thống miễn dịch của bệnh nhân đang tấn công nhầm vào chính các tế bào khớp gối, giải phóng hàng loạt enzyme ăn mòn sụn và xương. Bác sĩ cần phải can thiệp ngay lập tức bằng thuốc ức chế miễn dịch mạnh (như Corticoid hoặc DMARDs) để chặn đứng dòng thác phá hủy này.
### 2. Điểm Số Quyết Định Phác Đồ Điều Trị (Actionable Clinical Metric)
Điểm số Phân cấp từ 0 đến 3 không phải là một cái tag hiển thị cho đẹp, nó hoạt động giống như một **luồng điều hướng logic (Decision Tree)** quyết định trực tiếp hành động lâm sàng của bác sĩ:
- **Grade 0 (Bình thường):** Chuyển bệnh nhân sang chế độ phòng ngừa, xuất viện.
- **Grade 1 (Nhẹ):** Chỉ định điều trị nội khoa bảo tồn ở mức độ thấp (Dùng thuốc kháng viêm không Steroid - NSAIDs, thay đổi lối sống, tập vật lý trị liệu với bác sĩ PT - UP6).
- **Grade 2 (Vừa):** Cân nhắc tiêm thuốc nội khớp (tiêm Corticoid trực tiếp vào ngách khớp gối để dập dịch viêm tại chỗ) kết hợp điều trị thuốc đặc hiệu.
- **Grade 3 (Nặng/Nghiêm trọng):** Rút dịch khớp (Arthrocentesis) để giảm áp lực, chỉ định nhập viện điều trị tích cực, hoặc chuyển tuyến ngoại khoa để thực hiện phẫu thuật nội soi cắt màng hoạt dịch (Synovectomy) nhằm cứu lấy sụn khớp trước khi gối bị biến dạng hoàn toàn không thể phục hồi.
### 3. Thước Đo Khách Quan Để Đánh Giá Hiệu Quả Thuốc (Treatment Monitoring Dashboard)
- **Nỗi đau của Bác sĩ:** Khi điều trị các bệnh tự miễn như Viêm khớp dạng thấp, bệnh nhân phải uống thuốc ròng rã nhiều tháng trời. Nếu bác sĩ chỉ hỏi bệnh nhân *"Bác có bớt đau không?"*, câu trả lời sẽ cực kỳ chủ quan và không chính xác (do ngưỡng chịu đau của mỗi người khác nhau và có hiệu ứng giả dược).
- **Use Case tiết lộ điều gì:** Use Case này cung cấp một **Standardized Baseline (Mốc chuẩn hóa)** để so sánh liên tục qua các mốc thời gian (Time-series Analysis).
- *Tháng 1:* Bệnh nhân đến khám $\rightarrow$ Hệ thống chấm **Grade 3** (Màng hoạt dịch dày 6mm, Doppler phủ 65% area).
- *Tháng 3 (Sau 2 tháng uống thuốc):* Bệnh nhân tái khám $\rightarrow$ Hệ thống chấm **Grade 1** (Màng hoạt dịch giảm còn 2.5mm, Doppler chỉ còn vài chấm cô lập).
$\rightarrow$ Phần mềm tiết lộ cho bác sĩ một bằng chứng số liệu toán học tuyệt đối: **Phác đồ thuốc hiện tại đang hoạt động hiệu quả**, tiếp tục duy trì liều lượng. Ngược lại, nếu điểm số vẫn là Grade 3, hệ thống cảnh báo bác sĩ rằng bệnh nhân đang kháng thuốc, phải đổi sang loại thuốc sinh học đắt tiền hơn ngay lập tức.
### 4. Triệt Tiêu Biến Thiên Giữa Các Bác Sĩ (Eradicating Inter-observer Variability)
- **Thực trạng tại bệnh viện:** Việc phân cấp siêu âm thủ công phụ thuộc rất nhiều vào mắt nhìn chủ quan và kinh nghiệm của từng người. Bác sĩ A (15 năm kinh nghiệm) nhìn ảnh đoán là Grade 2, nhưng Bác sĩ B (mới ra trường 1 năm) lại chấm là Grade 3 vì thấy túi dịch có vẻ to. Sự lệch pha này gây nguy hiểm cho tính đồng nhất của phác đồ điều trị.
- **Use Case tiết lộ điều gì:** Khi có AI hỗ trợ trích xuất độ dày vùng ngách trên xương bánh chè (`suprapatellar recess`) và tính tỷ lệ pixel màu Doppler một cách tự động, hệ thống đóng vai trò như một **bộ kiểm tra điều kiện logic khách quan (Deterministic Gatekeeper)**. Nó đưa ra một mức điểm gợi ý dựa trên thuật toán tính toán diện tích chuẩn y khoa, giúp đồng bộ hóa chất lượng chẩn đoán tại bệnh viện. Bác sĩ dù già hay trẻ đều nhìn thấy một cơ sở số liệu minh bạch để đưa ra quyết định cuối cùng.
- **The Alignment Check:** Qua bóc tách dưới góc nhìn lâm sàng này, bạn đã hiểu vì sao kết quả đầu ra của Use Case này (`Grade 0-3`) lại đóng vai trò là "trái tim mạch máu" cho toàn bộ Dashboard điều trị phía sau chưa, hay bạn muốn chúng ta đào sâu thêm vào điểm nào trước khi thiết kế các tương tác UIX?
- The System suggest what currently being missed from FR and need to define in the UC:
- **The Gap:** Ambiguous System & Actor Interaction Boundaries inside the Grading Workflow (Thiếu tường minh về ranh giới tương tác giữa Hệ thống và Bác sĩ).
- **The Question:** How exactly should the doctor **interact** with the system's automated AI calculation when adjusting or validating the suggested severity score (e.g., from Grade 2 to Grade 3)? - The answer of this
The precise, clinically accurate baseline workflow executed by a Diagnostic Radiologist (UP5) consists of the following 6 sequential phases:
- **Step 1 (Patient Posture Standardization):** The clinician places the patient in a supine position with the target knee supported by a bolster in **20°–30° of slight flexion**. This stretches the extensor mechanism (the **Quadriceps/Patellar Tendon)** and eliminates diagnostic tracking errors caused by acoustic anisotropy.
- Explain with simplification for Software Engineer
- **The Clinical Action:** The patient lies flat, knee bent exactly 20°–30° over a cushion.
- **The Software Engineer Analogy:** **Setting up consistent environment variables and running an initialization handshake.**
- **Deep Jargon Breakdown:**
- **Extensor Mechanism - Quadriceps/Patellar Tendon:** Think of this as a mechanical rubber band system (quadriceps muscle → tendon →kneecap → shin bone). When the leg is completely straight, this system sags and wrinkles. Bending it 20°–30° stretches it taut, creating a flat, predictable surface line.
- **Acoustic Anisotropy (The Crucial Hardware Bug):** This is a structural physical hardware limitation of ultrasound waves. If the sound beam hits a tendon at a perfect 90° right angle, it bounces back bright white (**Echoic**). If the probe tilts even 5° offline because the tendon is curved/sagging, the wave scatters sideways, and the tissue suddenly registers on-screen as pitch black (**Hypoechoic**), mimicking a fake fluid tear or inflammatory lesion.
- **Why this matters for your UI/Product Design:** This step is your raw input data sanity check. If the patient isn't positioned right, the ultrasound picture is filled with visual artifact bugs (garbage in, garbage out). Your system needs to know it is processing a standardized 20°–30° landscape view.
- **Step 2 (Longitudinal Probe Alignment):** The clinician positions a high-frequency linear transducer probe over the midline of the **suprapatellar recess** (sagittal plane), aligning the distal edge over the upper pole of the patella to capture the clear multi-layered layout of the quadriceps tendon.
- Explain with simplification for SE
- **The Clinical Action:** The linear probe is placed lengthwise right down the middle of the upper knee, overlapping the top edge of the kneecap.
- **The Software Engineer Analogy:** **Pointing your API client path to the exact parent database index to unpack a nested multi-layered object arrays.**
- **Deep Jargon Breakdown:**
- **Suprapatellar Recess:** This is the precise target memory location—a pouch-like joint cavity hiding right above the kneecap (**Supra** = above, **Patella** = kneecap) underneath the deep tissue layers.
- **Sagittal Plane:** A vertical front-to-back cross-section cut. If your application was a 3D video game engine, this is viewing the joint asset precisely from the orthogonal **Side View Viewport**, rather than looking from the front or top down.
- **Why this matters for your UI/Product Design:** This gives the system its coordinate system reference frame. In this view, your AI algorithm can run edge detection along standard anatomical landmarks, treating the top edge of the patella as a rock-solid structural zero-point anchor on a 2D canvas.
- **Step 3 (B-Mode Structural Metric Capture):** Using standard Grey Scale (B-mode), the radiologist identifies the hypoechoic tissue area resting between the *prefemoral fat pad* and the *suprapatellar fat pad*. They visually calculate the maximum vertical distance of joint capsule distension/thickening using the ultrasound console's physical calipers.
- Explain for SE
- **The Clinical Action:** The doctor switches to a black-and-white image, identifies the space between two fat patches, and hits two points on the console to calculate the space thickness.
- **The Software Engineer Analogy:** **Running a 2D Bounding Box Segmentation model to extract a quantitative `float` metric (distance in mm) between two fixed system nodes.**
- **Deep Jargon Breakdown:**
- **B-Mode (Brightness Mode):** This is the baseline structural image format. It transforms reflected sound wave amplitudes into live pixel intensity map arrays (high reflection = white pixels; zero reflection/fluid fluid pools = dark black pixels).
- **Hypoechoic Tissue Area:** Any region that absorbs or passes sound waves easily instead of reflecting them, rendering as a dark grey or black signal pool. Inflamed synovial tissue fluid sits in this category.
- **Prefemoral & Suprapatellar Fat Pads:** These are your permanent upper and lower hardware guardrail markers. The suprapatellar pouch sits wedged right between them like an expandable buffer queue.
- **Why this matters for your UI/Product Design:** This is **REQ-RAD-02** in your requirement documentation. The doctor uses manual calipers to measure this space. Your product UI can introduce a digital bounding path box or automated point-to-point drawing tool overlay to automatically extract this distance variable, completely stripping away the manual console math step.
- **Step 4 (Power Doppler Vascularity Mapping):** The clinician activates the Power Doppler mode on the console, optimizing the wall filter and PRF settings. They carefully hover the probe with **minimal contact pressure** to avoid compressing low-velocity synovial capillaries, visually counting or calculating the percentage area occupied by active blood flow signals inside the suprapatellar landscape.
- Explain for SE
- **The Clinical Action:** The doctor switches on the color overlay feature, tweaks the sensitivity filters, and hovers the probe extremely lightly without pressing down into the skin.
- **The Software Engineer Analogy:** **Activating a live telemetry tracer module with a low-pass noise filter to map active server data traffic volume while avoiding an external physical choke/throttling event.**
- **Deep Jargon Breakdown:**
- **Power Doppler Mode:** A specialized signal tracking sub-routine. Instead of mapping structural tissue borders, it tracks shifts in frequency caused by moving targets (red blood cells). It highlights these regions with bright, glowing color maps overlaid right on top of the black-and-white structural layer.
- **Wall Filter & PRF (Pulse Repetition Frequency):** These are variable noise gates. If configured wrong, minor hand tremors will bleed into the visual feed as massive colored pixels (**Clutter Artifact Noise**).
- synpvia Capillary Compression Edge Case: If the doctor applies heavy hand force, they manually flatten the tiny micro-blood vessels inside the knee. This physically blocks blood flow, wiping out the signal completely on screen and returning a false negative trace.
- **Why this matters for your UI/Product Design:** This maps directly to your **Hypervascularity parameter**. Your interface can assist by calculating the ratio of bright color pixels to the total area of the segmented pouch, converting a subjective visual guess into a precise numerical percentage readout.
- **Step 5 (Semi-Quantitative Grade Synthesis):** The clinician combines both structural metrics mentally against standard musculoskeletal classification tiers: - THE VKIST ML-Module current stop in here
- *Grade 0 (None):* Completely flat layers; no hypoechoic separation or vascular flow signals.
- *Grade 1 (Mild):* Thin hypoechoic line running parallel to the femoral bone path; single or minimal isolated vascular blood flow spots.
- *Grade 2 (Moderate):* Evident hypoechoic expansion pushing the fat pads apart, but lines remain flat; active vascular flow spots occupying less than 50% of the calculated synovial area.
- *Grade 3 (Severe):* Clear convex or distinct bulging capsule distortion extending outward; intense confluent flow signals covering more than 50% of the calculated synovial landscape.
- Explain for SE
- **The Clinical Action:** The doctor looks at both parameters (the pouch thickness + the active color blood flow maps) and maps them to a standard clinical severity tier level (0 to 3).
- **The Software Engineer Analogy:** **Evaluating raw aggregated metric values against a core business logic conditional switch block (`switch(severityGrade)`) to determine system status codes.**
- **Deep Tiers Demystified via Code Logic:**
- **Grade 0 (Healthy Baseline):**
```jsx
if (synovialThickness === 0 && hypervascularityScore === 0) return "Grade 0: Normal Space";
```
- **Grade 1 (Mild Inflammation):** Space is filled with a thin, parallel line of tissue expansion; trace color dots show up.JavaScript
```
if (synovialThickness > 0 && hypervascularityScore <= 0.10) return "Grade 1: Mild Distension";
```
- **Grade 2 (Moderate Inflammation):** The tissue swells enough to visibly push the flanking fat pads apart, and the active blood flow color blocks cover up to half of the pouch container zone.JavaScript
```
if (synoviumDistended === true && hypervascularityScore < 0.50) return "Grade 2: Moderate Pouch Deflection";
```
- **Grade 3 (Severe Inflammation):** The pouch balloons into a curved, outward bulging geometric form; intense, connected color maps take over more than half of the space landscape.JavaScript
```
if (capsuleShape === 'convex_bulge' || hypervascularityScore >= 0.50) return "Grade 3: Critical Structural Flare";
```
- **Step 6 (Manual Multi-Silo Transcription):** The clinician freezes the optimal reference frames on the hardware console, manually assigns a final severity index label, moves away from the ultrasound machine hardware screen to a desktop workstation PC, and types out the structural text variables into the hospital's Electronic Medical Record (EMR) text block.
- Explain for SE
- **The Clinical Action:** The doctor freezes the machine display screen, manually records a final tier index number, stands up, switches chairs to a secondary office computer, logs in, and re-types the exact observations by hand into a text window box.
- **The Software Engineer Analogy:** **A total lack of system database synchronization. Hand-copying raw log data variables from a separate terminal window and typing them line-by-line into a separate decoupled microservice application.**
- **Why this matters for your UI/Product Design:** This is the massive core workflow bottleneck. The goal of your upcoming workspace design is to build an interactive, unified web interface bridge. The AI processes the image data parameters natively, renders an automated classification tag proposal directly inside the primary viewing frame, and updates the shared patient record database with 0 manual transcript entries or physical context-switching loops.
- Additional - from the answer in the `Question` we can model the planUML code solution
!image.png
```jsx
@startuml
' Settings
left to right direction
skin rose
' Actors
actor "Diagnostic Radiologist (UP5)" as Rad
actor "Hospital EMR System" as EMR << System >>
actor "VKIST AI Pipeline" as AI << System >>
' System Boundary
rectangle "VKIST MSK Workspace - Synovitis Grading Engine" {
' Core Viewing & Extraction Use Cases
usecase "Load Patient Ultrasound Session" as UC_Load
usecase "Extract Joint Tissue Metrics" as UC_Extract
' AI Suggestion Processing
usecase "Compute Automated Severity Suggestion" as UC_AI_Compute
usecase "Display Suggestion Tag & Canvas Overlays" as UC_Display
' Clinician Interaction & Decision Loop
usecase "Review Suggested Synovitis Grade (0-3)" as UC_Review
usecase "Manually Override Severity Grade" as UC_Override
usecase "Sign & Finalize Diagnostic Conclusions" as UC_Finalize
' Data Sync Hand-off
usecase "Synchronize Patient Record" as UC_Sync
}
' Relationships & Flow Boundaries
Rad --> UC_Load
Rad --> UC_Review
Rad --> UC_Finalize
' AI Pipeline Interactions
UC_Load ..> UC_Extract : <<include>>
UC_Extract --> AI : Transmit raw image streams
AI --> UC_AI_Compute : Process thickness & Doppler maps
UC_AI_Compute ..> UC_Display : <<include>>
' Review and Override Loop
UC_Display ..> UC_Review : <<include>>
UC_Override .up.> UC_Review : <<extend>> (If clinician disagrees with AI)
Rad --> UC_Override
' Finalization and Sync Hand-offs
UC_Finalize ..> UC_Sync : <<include>>
UC_Sync --> EMR : Push standardized JSON structural data
@enduml
```
→ For the Synovist Grading the interaction between the clinician & system may occur 4 potential case: —> 4 possible interactions
```jsx
+-----------------------------------------------------------------------+
| HUMAN-AI CONCURRENT STATES |
+-----------------------------------+-----------------------------------+
| QUADRANT 2 | QUADRANT 1 |
| Automation Override Risk | True Agreement |
| | |
| AI: Grade 3 (Accurate) | AI: Grade 2 (Accurate) |
| Human: Grade 1 (Oversight) | Human: Grade 2 (Confident) |
| Risk: Severe Disease Missed | Risk: None (Happy Path) |
+-----------------------------------+-----------------------------------+
| QUADRANT 4 | QUADRANT 3 |
| Double-Blind Failure | Clinician Subservience Risk |
| | |
| AI: Grade 2 (Boundary Error) | AI: Grade 3 (Hallucinated) |
| Human: Grade 1 (Biased Error) | Human: Grade 1 (Accurate) |
| Risk: Cascading System Error | Risk: Over-treatment Danger |
+-----------------------------------+-----------------------------------+
```
THE ML-stack use in this scenarios:
- the grading ML-stack (VKIST-model) → always use (it’s the machine process on the raw-signal from device)
- the LLM Critic & Actor for acting as explainer on the results of the grading stack (de-blackbox) + conversation with the clinics for pathologic analysis <with RAG> + critic-suggestion (this LLM shall have to loaded with SKILL / multi-agent system)
- the LLM-RAG-Referee for prevent bias & blindness of both-side (actor & grader & clinical)
| **Referee Role** | **Problem Solved** | **Mechanism** |
| --- | --- | --- |
| **1. Unbiased Arbiter** | **Conflict & Bias:** Prevents the LLM from hallucinating to match the clinician's incorrect bias (Confirmation Bias). | Operates as a **Session-State Arbiter**: It ignores conversation history and focuses purely on comparing the raw metrics (`GradCAM maps`, `Doppler indices`) against clinical definitions. |
| **2. Domain Guardian** | **Knowledge Obsolescence:**Prevents the system from using outdated medical standards (e.g., guidelines from 2020 instead of 2025). | Operates as a **Knowledge-Retrieval Guardian**: It triggers when the system detects high semantic entropy, fetching the *latest* approved academic guidelines to ensure all explanations remain clinically valid. |
The Actor:
- the UP-5 user working with the hardware
4 scenarios can consider

173
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UseCase/full_usecase_planuml.md Normal file
View File

@@ -0,0 +1,173 @@
# VKIST MSK Workspace (FR-25): Full System Use Case Specification
This document provides a comprehensive, unified, and standard-aligned specification of the **VKIST MSK Workspace (FR-25)** use-case model. It acts as the definitive guide to the overall system-level architecture, showing how all 15 core use cases are structurally organized, how they connect across operational pipelines, and how they implement the safety-critical human-AI decision-making frameworks.
The use-case design is structured around a **4-Quadrant Human-AI Interaction Framework**, designed to optimize diagnostic speed while defending against cognitive biases (such as automation bias and clinician subservience) in high-throughput clinical environments.
---
## 1. Primary System Actors
The platform coordinates interactions between the clinical specialist and multiple local, air-gapped system components:
1. **UP5 (Diagnostic Radiologist):** The primary human actor. A Vietnamese clinical specialist processing musculoskeletal (MSK) ultrasound scans, responsible for evaluating AI suggestions, annotating images, and signing final diagnostic records.
2. **MSK-Vision-Grader System:** The edge-close & server-distribute computer vision inference runner. It ingests raw DICOM image arrays, extracts structural parameters, and generates automated synovitis grading (Grades 0–3) along with bounding boxes and Grad-CAM activation heatmaps.
3. **LLM Explainer:** A localized language model (e.g., PhoGPT or MedGemma) that runs on bare-metal hospital GPUs to generate clinical Chain-of-Thought (CoT) reasoning paragraphs justifying model predictions.
4. **Hospital EMR System (EMR):** The air-gapped hospital intranet electronic medical record repository, serving as the immutable sink for signed reports and ground-truth overrides.
5. **LLM RAG-Referee-Arbitrator:** An on-premise Vector DB-backed QA model that queries static Vietnamese Ministry of Health (MOH) clinical guidelines to resolve human-AI disagreements with objective evidence.
---
## 2. Complete Traceability Matrix
The following table homogenizes all 15 use cases from `Sprint_1_2_UseCase_DB.csv` and details their core system goals:
| UC-ID | Title [Verb + Noun] | Primary Actor | System Goal | Interaction Type | Pipeline / Quadrant |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **UC-48376** | Load Patient Scan Session | UP5, MSK-Vision-Grader | Ingest raw ultrasound frame arrays and initialize session state with spatial calibrations. | System-to-System, User-to-System | Data Ingest Pipeline |
| **UC-47988** | Review Suggested Synovitis Grade (0-3) | UP5 | Evaluate proposed synovitis classification metrics and structural visual overlays on the viewport. | User-to-System | Clinical Review Pipeline |
| **UC-92006** | Finalize & Sign Electronic Record | UP5, Hospital EMR System | Authenticate, cryptographically seal, and sync verified diagnostic reports down to storage infrastructure. | System-to-System, User-to-System | Sync & Finalization Pipeline |
| **UC-25776** | Generate GradCAM & CoT Explanation Panel | UP5, LLM Explainer | Present clear, pixel-linked visuospatial explanations and multi-modal clinical reasoning for high-trust verification. | User-to-System | Quadrant 1 (True Agreement) |
| **UC-02423** | Log High-Trust Concur Block | Hospital EMR System | Secure the human-AI alignment log trace within the final diagnostic report payload. | System-to-System | Quadrant 1 (True Agreement) |
| **UC-22159** | Trigger Conversational Circuit Breaker | UP5 | Intercept premature finalization if telemetry reveals friction, hesitation, or cognitive blind-spots. | User-to-System | Quadrant 2 (Automation Override) |
| **UC-55146** | Facilitate Socratic Reasoning Dialogue | UP5, LLM Explainer | Engage the specialist in a targeted, conversational double-check loop regarding controversial markers. | User-to-System | Quadrant 2 (Automation Override) |
| **UC-74821** | Monitor Context Drift via BERT Sub-Layer | UP5 | Continuously parse communication tokens to identify logical contradictions or semantic drift during clinical debates. | User-to-System | Quadrant 2 (Automation Override) |
| **UC-65473** | Arbitrate Evidence via RAG-Referee | UP5, LLM RAG-Referee-Arbitrator | Query static, authoritative clinical knowledge bases to resolve human-machine disagreements with objective evidence. | User-to-System | Quadrant 2 (Automation Override) |
| **UC-25637** | Expose Pixel-Level Activation Logic | UP5 | Reveal fine-grained layer weights and activation responses when the human specialist challenges an automated prediction. | User-to-System | Quadrant 3 (Clinician Subservience) |
| **UC-60739** | Isolate Visual Noise/Artifacts | UP5 | Provide manual brush and selection overlays to mask out acoustic shadows, bone scattering, or artifacts. | User-to-System | Quadrant 3 (Clinician Subservience) |
| **UC-62864** | Commit Validated Ground-Truth Record | Hospital EMR System | Secure the human-corrected ground-truth dataset variant while appending expert-validated reports to the EMR. | System-to-System | Quadrant 3 (Clinician Subservience) |
| **UC-35956** | Activate Clinical Investigation Mode | UP5 | Switch the system into a strict, template-driven manual examination mode when low vision confidence aligns with missing references. | User-to-System | Quadrant 4 (Double Blind Failure) |
| **UC-47796** | Execute Structured Morphology Annotation | UP5 | Force the manual plotting of anatomical coordinates and morphological anomalies using a strict, un-biased framework. | User-to-System | Quadrant 4 (Double Blind Failure) |
| **UC-01580** | Serialize Session to Telemetry Queue | Hospital EMR System | Route anomalous case data directly to engineering telemetry streams while bypassing standard EMR databases. | System-to-System | Quadrant 4 (Double Blind Failure) |
---
## 3. PlantUML Architectural Model
The following diagram defines the physical and logical boundaries of the **VKIST MSK Workspace System (FR-25)**. It maps actor associations, internal system boundaries, and precise functional relationships (`<<include>>` and `<<extend>>` stereotypic dependencies).
```plantuml
@startuml
skinparam packageStyle rectangle
left to right direction
' ##########################################
' ACTORS DEFINITION
' ##########################################
actor "UP5\n(Diagnostic Radiologist)" as up5
actor :MSK-Vision-Grader\nSystem: as msk <<system>>
actor :LLM\nExplainer: as llm_exp <<system>>
actor :Hospital EMR System: as emr <<system>>
actor :LLM RAG-Referee\nArbitrator: as llm_rag <<system>>
' ##########################################
' VKIST MSK WORKSPACE SYSTEM BOUNDARY
' ##########################################
rectangle "VKIST MSK Workspace System (FR-25)" {
' --- Core Ingestion & Viewing Use Cases ---
usecase "UC-48376\nLoad Patient Scan Session" as uc_48376
usecase "UC-47988\nReview Suggested Synovitis Grade (0-3)" as uc_47988 #Khaki
usecase "UC-92006\nFinalize & Sign Electronic Record" as uc_92006
' --- Quadrant 1: True Agreement ---
usecase "UC-25776\nGenerate GradCAM & CoT Explanation Panel" as uc_25776
usecase "UC-02423\nLog High-Trust Concur Block" as uc_02423
' --- Quadrant 2: Automation Override ---
usecase "UC-22159\nTrigger Conversational Circuit Breaker" as uc_22159
usecase "UC-55146\nFacilitate Socratic Reasoning Dialogue" as uc_55146
usecase "UC-74821\nMonitor Context Drift via BERT Sub-Layer" as uc_74821
usecase "UC-65473\nArbitrate Evidence via RAG-Referee" as uc_65473
' --- Quadrant 3: Clinician Subservience ---
usecase "UC-25637\nExpose Pixel-Level Activation Logic" as uc_25637
usecase "UC-60739\nIsolate Visual Noise/Artifacts" as uc_60739
usecase "UC-62864\nCommit Validated Ground-Truth Record" as uc_62864
' --- Quadrant 4: Double Blind Failure ---
usecase "UC-35956\nActivate Clinical Investigation Mode" as uc_35956
usecase "UC-47796\nExecute Structured Morphology Annotation" as uc_47796
usecase "UC-01580\nSerialize Session to Telemetry Queue" as uc_01580
}
' ##########################################
' RELATIONSHIPS & ASSOCIATIONS
' ##########################################
' --- UP5 Actor Connections ---
up5 --> uc_47988 : Reviews suggested grading
up5 --> uc_48376 : Manually triggers load
up5 --> uc_65473 : Interacts with guideline reference
up5 --> uc_02423 : Signs with direct AI consensus
up5 --> uc_92006 : Executes digital signature
up5 --> uc_47796 : Documents manual finding & diagnosis
' --- MSK-Vision-Grader System Connections ---
msk --> uc_47988 : Generates prediction score
uc_48376 --> msk : Delivers raw image tensors
msk --> uc_25776 : Generates localized Grad-CAM layers
msk --> uc_22159 : Flags classification hesitation/uncertainty
' --- LLM Explainer Connections ---
llm_exp --> uc_25776 : Generates step-by-step clinical CoT
llm_exp --> uc_55146 : Generates Socratic discussion checks
' --- Hospital EMR System Connections ---
uc_02423 --> emr : Stores sealed consensus log
uc_92006 --> emr : Synchronizes verified medical reports
uc_01580 --> emr : Stores isolated development packet
' --- LLM RAG-Referee Arbitrator Connections ---
llm_rag --> uc_65473 : Performs retrieval on MOH guidelines
' --- Use Case to Use Case Interdependencies ---
' Extend Paths
uc_35956 -.-> uc_47988 : <<extend>>\nTriggered by low-confidence scan\n& empty guidelines
uc_25637 -.-> uc_47988 : <<extend>>\nTriggered when clinician\ncontests AI prediction
' Include Paths (Quadrant 3)
uc_25637 -.-> uc_60739 : <<include>>
uc_60739 -.-> uc_62864 : <<include>>
' Include Paths (Quadrant 2)
uc_22159 -.-> uc_55146 : <<include>>
uc_22159 -.-> uc_74821 : <<include>>
' Extend Paths (Quadrant 2 Socratic Loop)
uc_65473 -.-> uc_74821 : <<extend>>\nTriggered if semantic drift\nor impasse is caught
' Include Paths (Quadrant 4)
uc_47796 -.-> uc_01580 : <<include>>
@enduml
```
---
## 4. Architectural Analysis of Functional Relationships
### 4.1 Stereotyped Dependecies
- **`<<include>>` Dependencies:**
- **`UC-25637` includes `UC-60739`:** When the clinical specialist contests the AI suggestion and the system exposes pixel-level activation logic, it structurally includes the manual toolset to isolate and paint over acoustic shadows and bone scattering artifacts.
- **`UC-60739` includes `UC-62864`:** Successful isolation of physical ultrasound noise always includes committing a validated, high-value ground-truth dataset variant directly to storage for downstream model retraining.
- **`UC-22159` includes `UC-55146` & `UC-74821`:** If the workspace's behavioral trackers detect high cognitive hesitation (intercepting normal pathways), it halts progression and launches both the Socratic conversational panel and the context-drift tracking sub-layer concurrently.
- **`UC-47796` includes `UC-01580`:** When in clinical investigation mode, finalizing a manually plotted annotation and morphologic coordinate dataset immediately triggers telemetry serialization to route debugging data out to development queues.
- **`<<extend>>` Dependencies:**
- **`UC-25637` extends `UC-47988`:** Revealing pixel-level layer weights is not a default step; it only extends the basic grading review if the doctor explicitly challenges or modifies the AI-proposed classification score.
- **`UC-65473` extends `UC-74821`:** Querying authoritative local Vector databases and injecting MOH guidelines extends the context-drift monitoring if the BERT checker detects a logical contradiction, an impasse, or severe drift in the clinical dialogue.
- **`UC-35956` extends `UC-47988`:** The system disables automated diagnostics and switches the entire viewport layout to clinical investigation mode (Escalation) only if model classification confidence falls below 60% and no guidelines map to the anomalies.
---
## 5. Homogenization of Business Logics & Clinical Drivers
By synchronizing the Use Case IDs and naming conventions across the **Use Case Database (`Sprint_1_2_UseCase_DB.csv`)**, the **System Design Specification (`SOFTWARE_SYSTEM_DESIGN_FR_25.md`)**, and this **Architectural Model**, we have solidified key business rules:
1. **The Role of the Diagnostic Radiologist (`UP5`):** Explicitly unified as the single human clinician in the workspace loop. The historical database typo identifying the actor of `UC-47796` as "UNK" is fully resolved under the canonical role of `UP5`.
2. **True Socratic Agreement Pipeline (`UC-22159` -> `UC-65473`):** Resolves the risk of automation bias. The conversational circuit breaker is technically backed by a real-time BERT text classifier that checks for clinical semantic drift against the raw image and can escalate directly to local Vector RAG modules containing MOH clinical guidelines.
3. **Continuous Retraining Pipeline (`UC-25637` -> `UC-62864`):** Turns clinical overrides into architectural assets. When `UP5` overrides the AI classification, they paint an SVG mask over the artifacts (reverberations/shadows). Saving this mask along with the ground-truth correction allows for localized, high-value model retraining on local-hospital acoustic variations.
4. **Air-Gapped Telemetry Routing (`UC-47796` -> `UC-01580`):** Enforces Circular 46/2018/TT-BYT compliance. Highly anomalous cases or double-blind failures are stripped of standard patient EMR references and serialized directly into dedicated debugging logs on the local server, protecting primary medical data lines while providing raw materials for engineering diagnosis.

215
workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/User-Research-Result.md Normal file
View File

@@ -0,0 +1,215 @@
# User-Research Result
⇒ DEFINING THE PROJECT-SCOPE:
Develop an interactive **`musculoskeletal care and education platform`** that transforms standard DICOM X-rays into a **`collaborative workspace`**. The system **`empowers clinicians with continuous education, diagnostic support, and objective clinical checks`**, while **`actively educating patients about their locomotive health to foster a true partnership throughout their treatment journey.`**
**⇒ End-user I have identified in this project (The Pilot-Project) scope shall include as follow:**
- The User Profile & User Persona ? - Given the User-Profile as below within the domain of healthcare in general (these are matter in NFRs)
### User-Profile 1: Healthcare Senior Expert
- **Who they are:** PhD, Specialist II, senior department heads, professors, clinical directors, and national-level experts.
- **Age range:** about 40–60+.
- **Domain proficiency / responsibility:** highest domain depth; they own complex diagnosis, surgery, protocol setting, teaching, research, and escalation decisions.
- **Working environment:** central or urban referral hospitals with the highest case complexity, the heaviest consult load, and the strongest pressure to standardize quality across many juniors.
- **What they know:** specialty medicine, clinical standards, institutional policy, and how to manage hard cases with incomplete information.
- **What they do not know:** ML model behavior, deployment constraints, validation methodology, and how to operationalize AI into workflow without disruption.
- **Attitude toward AI/ML:** cautious but open if it improves safety, speed, or teaching quality; skeptical of black-box outputs and unproven demos.
- **Pain points AI should help with:** triage prioritization, guideline consistency, overload reduction, second-opinion support, and research/teaching summarization.
- **Hindrances in solution design:** liability concerns, low tolerance for workflow friction, demand for explainability, and strong resistance to tools that look like “extra work.”
- **Role in Dev/R&D:** decision-maker, clinical validator, and pilot sponsor; not the best first user for UX discovery, but essential for approval and governance.
- **How to approach them:** start from patient safety, evidence, efficiency, and institutional benefit; bring concise demos, local data, and clear failure-mode handling.
### User-Profile 2: Professional Clinician
- **Who they are:** MD, Master’s, Specialist I physicians, consultants, and mid-career clinicians.
- **Age range:** about 30–45.
- **Domain proficiency / responsibility:** strong clinical decision-making, specialty care, supervision of routine clinicians, and participation in departmental operations.
- **Working environment:** major cities and provincial hospitals; high volume, mixed complexity, heavy outpatient/inpatient balance, and constant multitasking.
- **What they know:** practical evidence-based medicine, standard workflows, referrals, diagnostic pathways, and how hospital systems actually behave.
- **What they do not know:** deep ML mechanics, model drift, data governance nuance, and how to audit AI outputs in a rigorous way.
- **Attitude toward AI/ML:** pragmatic and curious; they will adopt if it saves time and reduces repetitive work, but they quickly lose trust if the tool is unstable or slow.
- **Pain points AI should help with:** chart review, note drafting, imaging/radiology support, guideline lookup, coding/admin burden, and triage support.
- **Hindrances in solution design:** fragmented systems, poor interoperability, time pressure, incomplete data, and the need to justify decisions upward.
- **Role in Dev/R&D:** power users, domain testers, and feedback bridge between leadership and frontline users.
- **How to approach them:** focus on time saved, accuracy, integration with current workflow, and measurable outcomes; avoid abstract “AI transformation” language.
### User-Profile 3: Practitioner
- **Who they are:** college/intermediate-degree clinicians, nurses, assistants, and routine care providers.
- **Age range:** about 22–35.
- **Domain proficiency / responsibility:** routine care, procedures, monitoring, handoff, and protocol execution rather than independent complex diagnosis.
- **Working environment:** provincial, district, and some commune-level settings; constrained staffing, high patient throughput, and fewer specialist backups.
- **What they know:** operational care, standard procedures, basic triage, record keeping, medication handling, and patient communication.
- **What they do not know:** advanced diagnostics, edge-case management, system design, or how to judge whether AI recommendations are statistically reliable.
- **Attitude toward AI/ML:** mixed but practical; they like tools that reduce repetitive tasks and help them work faster, but they worry about complexity and blame if something goes wrong.
- **Pain points AI should help with:** patient queue management, reminders, checklisting, basic decision support, documentation assistance, and training support.
- **Hindrances in solution design:** low digital confidence in some sites, limited device availability, unstable connectivity, and insufficient time for training.
- **Role in Dev/R&D:** frontline reality check; they expose whether the tool actually works in crowded, low-resource settings.
- **How to approach them:** keep interfaces simple, mobile-friendly, low-click, and aligned with routine tasks; demonstrate value in under one minute.
#### User-Profile 4: Support Staff & Patients
- **Who they are:** vocational/basic-level workers, assistants, clerks, pharmacy support, and commune/district support staff.
- **Age range:** about 18–30+ depending on role.
- **Domain proficiency / responsibility:** foundational care support, dispensing, scheduling, registration, logistics, and basic patient flow handling.
- **Working environment:** district/commune level, often with staff shortages, limited equipment, and very high dependency on manual coordination.
- **What they know:** local workflow, patient flow, administrative routines, inventory, and practical daily operations.
- **What they do not know:** clinical reasoning, advanced data interpretation, or how AI should be validated in medicine.
- **Attitude toward AI/ML:** mostly utilitarian; they like anything that reduces repetitive admin work, but they fear systems that increase confusion or slow service.
- **Pain points AI should help with:** registration, queue routing, reminder systems, inventory support, duplicate entry reduction, and scheduling.
- **Hindrances in solution design:** low training time, little tolerance for complex setup, language/interface issues, and dependence on supervisor approval.
- **Role in Dev/R&D:** workflow witnesses; they reveal hidden process bottlenecks and administrative failure points.
- **How to approach them:** use concrete use cases, local language, visual flows, and very short onboarding; do not assume technical familiarity.
- The User Profile (key-attribute) for these end-user in this product context includes (more focus on FRs)
- [**→ The results was developed based on Gemini-DeepResearch given the methodology of Online Ethnography as follow:**](https://gemini.google.com/share/a4e65f2f47c8)
| Platform Type | Selected Target Groups/Channels | Primary User Base Identified | Ethnographic Value & Observed Behaviors |
| --- | --- | --- | --- |
| **Professional Forums** | ykhoa.net, Vietnam Orthopaedic Association (VOA) portal | Radiologists, Surgeons, Medical Students, Rural Physicians | Discussions on uncompensated workloads, mHealth resistance in rural areas, formal professional networking, CME tracking. |
| **Patient Forums** | Webtretho | Mothers, Adult Family Caregivers, Female Patients | Highlighting the primacy of family-centric healthcare decision-making, peer-to-peer sharing of alternative/folk remedies, high anxiety expression. |
| **Facebook Groups** | Chẩn Đoán Hình Ảnh Online, Trung tâm Chấn thương chỉnh hình Tâm Anh, Thoát vị đĩa đệm | Radiologists, Orthopedic Surgeons, Patients | Clinicians sharing edge-case DICOMs for peer review. Patients posting raw X-rays seeking asynchronous online consultations. |
| **YouTube Channels** | cdhaonline, USAC, ACC Chiropractic, Bác sĩ Trần Văn Phúc Official | Sonographers, Patients seeking conservative treatments | Visual tutorials for MSK ultrasound, patient consumption of non-pharmacological treatment videos (sciatica, knee pain). |
### **User Profile 5: The Diagnostic Radiologist (Bác sĩ Chẩn đoán hình ảnh)**
- **Who they are** within the MSK workflow is foundational; they are the primary data generators and the initial analytical layer. Diagnostic Radiologists in the Vietnamese public sector are highly specialized medical doctors tasked with interpreting complex, multi-modal imaging (X-ray, CT, MRI) and producing the definitive reports that guide all subsequent orthopedic or rheumatological interventions. They operate exactly at the critical intersection of deep human anatomy, pathological manifestation, and advanced digital imaging technology.
- **Age range** for this demographic typically spans from 28 to 55 years old. This broad range encompasses highly tech-fluent, digitally native junior attendings who have trained entirely on digital screens, up to senior department heads who have had to actively transition their cognitive models from legacy analog film-based interpretation to modern digital PACS environments over the last critical decade.
- **Domain proficiency / responsibility** for these users lies in rapid, highly accurate pattern recognition across various tissue densities and skeletal structures. They are explicitly responsible for detecting micro-fractures, subtle degenerative joint changes, early-stage bone tumors, and complex structural anomalies within the MSK system. Furthermore, in modernized environments like Bach Mai or Viet Duc, they are increasingly burdened with the responsibility of monitoring patient radiation dose exposure, a complex safety metric now deeply integrated into modern PACS software implementations.
- **Working environment** `constraints are severe.` They predominantly work in high-stress, low-ambient-light reading rooms situated within severely overloaded central and provincial hospitals. Their work is highly asynchronous and entirely detached from direct, physical patient interaction. They face immense cognitive load due to the sheer, overwhelming volume of daily scans generated by a public healthcare system where patients often bypass primary care facilities to visit central hospitals directly, leading to massive backlogs.
- **What they know** is exhaustive and deeply technical. They possess a profound understanding of skeletal anatomy, radiological physics, and pathological manifestations on high-resolution digital monitors. They know the intimate intricacies of complex DICOM viewers, including windowing, leveling, multi-planar reconstruction (MPR), and maximum intensity projections (MIP). They are intimately familiar with the limitations of specific imaging modalities and the technical artifacts that can obscure or mimic diagnoses.
- **What they do not know** represents a critical clinical gap. They typically do not know the patient's full longitudinal clinical history or the nuanced, subjective experiences of the patient's localized pain, primarily because the clinical order notes provided by referring public sector physicians are often exceedingly brief due to extreme hospital overload. Furthermore, they are often unaware of the specific downstream surgical or conservative treatment decisions made by the orthopedic surgeons unless a formal multi-disciplinary case review is specifically initiated.
- **Attitude toward AI/ML** among Vietnamese radiologists is a complex, evolving mixture of cautious optimism and defensive professional skepticism. The highly publicized and successful deployment of AI applications like VinBrain's DrAid for liver cancer screening and COVID-19 triage—which have won prestigious international awards and proven highly effective in real-world triage—has established a strong, tangible baseline of trust in algorithmic capabilities. They view AI highly favorably when it functions as an automated, invisible "second reader" that accurately highlights anomalies, quantifies tedious measurements, or triages obvious normal versus critical abnormal scans to help manage their overwhelming workload. However, profound resistance manifests if the AI is perceived as an opaque "black box" that disrupts established mental models without providing transparent, explainable reasoning.
- **Pain points AI should help with** center entirely on cognitive fatigue and volume management. The primary pain point is the severe visual fatigue that leads to the risk of missing secondary, subtle findings (incidentalomas) due to the necessity of rapid patient throughput. AI must step in to automate highly tedious, repetitive measurements—such as joint space narrowing quantification in osteoarthritis or complex Cobb angles for scoliosis—and provide immediate professional objective checks. Furthermore, AI should actively assist in standardizing reports to reduce the heavy cognitive burden of continuous dictation and manual typing.
- **Hindrances in solution design** are heavily rooted in behavioral economics and legacy system performance. A critical ethnographic hindrance observed in forums like ykhoa.net is the profound fear of uncompensated workload. If the proposed collaborative platform introduces features that require the radiologist to answer direct, text-based queries from patients or spend excessive time manually validating AI outputs, the system will face universal rejection in the public sector. Additionally, interface latency is a severe technical hindrance; any collaborative tool that slows down the rendering of massive, gigabyte-sized DICOM files will immediately disrupt their highly optimized, fast-paced diagnostic workflow.
- **Role in Dev/R&D** processes is paramount; they serve as the ultimate ground-truth validators. In the R&D phase, their expertise is strictly required for accurately annotating MSK datasets, defining the specific clinical relevance of algorithmic edge cases, and rigorously evaluating the ergonomic efficiency of the DICOM viewing workspace. Their continuous feedback is absolutely paramount in finely tuning the AI's sensitivity-to-specificity ratio to prevent alert fatigue.
- **How to approach & percieve them (as Product-Dev Team)** requires a strategy of deep professional respect and workflow preservation. The product development team must approach radiologists as overwhelmed, elite experts whose primary and most scarce currency is time. They must never be perceived as luddites or obstacles to digital innovation, but rather as the vital gatekeepers of clinical safety. Engagement and UX research should be focused entirely on invisible workflow optimization, strongly emphasizing how the platform will actively reduce their cognitive load and protect them from malpractice liabilities via AI-backed objective checks, rather than framing the platform as a disruptive tool meant to alter their fundamental diagnostic philosophy.
### **User Profile 7: The Rheumatologist & Orthopedic Surgeon (Bác sĩ Cơ xương khớp / Chấn thương chỉnh hình)**
- **Who they are** dictates the final clinical outcome. `These clinical specialists are the ultimate consumers of the diagnostic imaging data and the primary architects of the patient's comprehensive treatment plan.` Orthopedic surgeons focus heavily on mechanical and surgical interventions for acute trauma, severe degenerative diseases, and complex congenital anomalies, while rheumatologists manage chronic, systemic autoimmune conditions affecting the MSK system. They are the definitive authoritative figures in the patient's healthcare journey.
- **Age range** is typically clustered between `30 and 60 years old.` Senior surgeons and veteran department heads hold immense, systemic influence over departmental procurement decisions and the formal adoption of new clinical pathways, while younger, highly digital attendings are significantly more likely to engage directly with novel digital patient consultation platforms and mobile health applications.
- **Domain proficiency / responsibility** is vast and encompassing. They are highly proficient in complex clinical diagnosis, advanced surgical biomechanics, systemic pharmacology, and long-term, multi-variable disease management. Their massive responsibility encompasses `synthesizing fragmented patient histories`, `physical examination findings,` and varied, highly technical radiological data to `formulate a definitive, actionable treatment strategy.` Ultimately, they bear the `complete clinical, ethical, and legal responsibility for the patient's surgical or therapeutic outcomes.`
- **Working environment** is notoriously highly fragmented and intensely pressured. Their daily environment is violently split between the sterile concentration of the operating theater, bustling and chaotic outpatient clinics, and crowded inpatient wards. In major public hospitals like Bach Mai, outpatient clinics are characterized by severe, systemic overcrowding, where a single senior doctor may be forced to see well over a hundred individual patients in a single grueling shift, necessitating incredibly rapid, highly decisive consultations that leave almost no time for extended dialogue.
- **What they know** is highly pragmatic. They intimately `know the practical, actionable clinical implications` of specific radiological findings. They know precisely which structural abnormalities require immediate, aggressive surgical intervention, which can be managed conservatively with physical therapy, and the specific surgical approaches required. They possess a deep, practical understanding of patient psychology, recognizing that their patients are often highly anxious, vulnerable, `and highly susceptible to community misinformation.`
- **What they do not know** highlights the necessity of the collaborative platform. They often lack the deep, pixel-level technical expertise of the dedicated radiologist regarding complex, multi-layered imaging artifacts or subtle MRI physics. `More significantly, and dangerously, they frequently do not know what the patient is actively doing outside the hospital walls—specifically, if the desperate patient is pursuing highly dangerous folk remedies, unregulated herbal treatments, or inappropriate, aggressive physical manipulations that could severely exacerbate their delicate condition.`
- **Attitude toward AI/ML** is strictly pragmatic and highly outcome-oriented`. They are notably less interested in basic AI that merely identifies an obvious femur fracture (which they can easily see from across the room)` and are vastly more interested in complex AI that provides `deep predictive analytics.` For example, they **desire algorithms forecasting the exact rate of cartilage degeneration in knee osteoarthritis or** predicting the **statistical likelihood of hardware failure in spinal fusions based on localized bone density metrics**. Crucially, they view `AI as a massive potential force multiplier for patient education, provided it visually translates complex DICOM data into beautifully simple formats the patient can instantly understand, thereby saving precious consultation minutes.`
- **Pain points AI should help with** are heavily centered around time deficits. The most critical pain point is the absolute `lack of time for comprehensive, empathetic patient education during severely overloaded clinical shifts`. AI `must explicitly help by automatically generating visually intuitive, patient-friendly, 3D summaries of the MSK issues directly from the complex DICOM workspace.` Furthermore, they desperately `need the platform to automatically aggregate highly fragmented patient data (historical X-rays, recent MRIs, scattered lab results) into a single, unified, rapid-consumption dashboard to exponentially expedite their clinical decision-making process.`
- **Hindrances in solution design** revolve around communication boundaries. A major, system-killing hindrance is the risk of the platform inadvertently encouraging patients to continuously message the busy doctor for minor, non-clinical queries. The ethnographic data shows the fear of an uncompensated, unmanageable volume of digital communication is profound among Vietnamese clinicians. If the proposed collaborative workspace functions too much like a standard, open-ended messaging app (like Zalo or Messenger), it will be aggressively abandoned. The communication flow must be heavily structured and tightly gated.
- **Role in Dev/R&D** requires strategic clinical oversight. They are absolutely crucial in defining the core clinical logic and the hierarchical, prioritized display of information within the platform's UI. They must strictly dictate what specific information is clinically relevant enough to be prominently displayed on the primary dashboard and what secondary data should be relegated to background menus. In R&D, they define the acceptable clinical thresholds for the AI's predictive models and dictate the required authoritative tone of the patient-facing educational modules.
- **How to approach & percieve them (as Product-Dev Team)** requires positioning the product as a shield. The product development team must perceive these senior doctors as the entire system's core orchestrators who are operating under extreme, punishing time deficits. The UX approach should emphatically emphasize the platform's ability to act as a "clinical force multiplier." Design discussions should entirely center on how the interactive workspace can automate tedious patient education, definitively dispel dangerous, culturally prevalent folk medicine myths , and heavily streamline multi-disciplinary case reviews without adding a single minute or a single extra click to their currently exhausted workflow.
****
### **~~User Profile 6: The MSK Sonographer (Bác sĩ Siêu âm Cơ xương khớp)~~**
- **Who they are** within the clinical ecosystem represents a highly specialized, dynamic subset of diagnostics. MSK Sonographers in Vietnam are often distinct from general dark-room radiologists; they frequently operate as specialized clinicians or general practitioners who have undergone extensive, highly specific supplementary training to master the dynamic, real-time imaging of the musculoskeletal system. They physically operate the high-frequency ultrasound probes to intimately evaluate soft tissues, tendons, ligaments, and superficial bone structures in real-time motion.
- **Age range** for this highly active profile is typically `25 to 50` years old. This group includes a significantly large cohort of younger, ambitious medical professionals actively seeking continuing medical education (CME) to differentiate their clinical skill sets, a trend heavily evidenced by the high demand and `rapid enrollment in structured online` and offline training courses offered by institutions like Pham Ngoc Thach University of Medicine and Medic Medical Center.
- **Domain proficiency / responsibility** is uniquely tactile, highly kinetic, and heavily operator-dependent. Their primary proficiency lies in real-time functional assessments, such as directly observing tendon gliding or impingement during active patient movement. `They must possess a profound, innate spatial understanding to instantly translate two-dimensional, grainy ultrasound slices into comprehensive three-dimensional anatomical comprehension.` They are also frequently responsible for `precision-guiding interventional procedures, such as targeted joint injections or aspirations.`
- **Working environment** constraints are physical and chaotic. Unlike radiologists isolated in quiet, dark reading rooms, sonographers work directly at the patient's bedside, in bustling emergency departments, or in highly trafficked dedicated ultrasound clinics. Their environment is inherently fast-paced, highly `interactive`, and requires continuous, complex physical maneuvering of both the bulky ultrasound equipment and the patient's body. They operate in a unique space where immediate, `continuous verbal communication with the patient regarding pain localization is standard practice`.
- **What they know** is rooted in soft-tissue dynamics. They possess deep, specialized knowledge of soft-tissue pathologies, inflammatory markers visible via `Power Doppler,` and the dynamic, mechanical relationships between muscles, tendons, and joints. They explicitly know how to manually manipulate acoustic windows with the probe to actively bypass bone and gas artifacts. They intimately understand the immediate physical limitations and specific pain thresholds of the patient currently lying on their examination table.
- **What they do not know** is the deeper structural context. They inherently lack the comprehensive, multi-system, deep-tissue overview provided by an MRI or CT scan. They cannot visualize deep bone marrow pathologies or assess the complete structural integrity of deep, complex joints (like the central hip) that are inaccessible to high-frequency ultrasound waves. Crucially, because ultrasound is so subjective, they are highly dependent on their own mechanical skill, meaning they often do not know how their real-time findings perfectly correlate with universally standardized baselines without subsequent external validation.
- **Attitude toward AI/ML** is largely nascent but highly receptive to real-time, assistive technologies. Because MSK ultrasound is so heavily operator-dependent and challenging to master, there is a strong, articulated desire within the community for AI tools that can provide on-the-fly, augmented-reality style anatomical labeling, automate the tedious measurement of tendon thickness during dynamic movement, or standardize the grading of complex inflammatory signals (e.g., synovial hypertrophy in rheumatoid arthritis).
- **Pain points AI should help with** revolve around standardization and documentation. The primary pain point is the extreme inter-operator variability inherent in ultrasound diagnostics. `AI must help by enforcing standardized image capture protocols`, providing real-time quality assurance of the acquired `images before the patient leaves the table, and offering automated comparative analysis against the patient's previous scans to track disease progression objectively.` Additionally, AI must desperately assist in generating automated, highly structured preliminary reports based directly on the captured images to `drastically reduce post-examination administrative typing time.`
- **Hindrances in solution design** are heavily dominated by the physical constraints of the ultrasound examination itself. A sonographer's hands are perpetually occupied (one firmly manipulating the probe, the other adjusting the machine console), and their eyes are strictly locked on the ultrasound monitor. Therefore, any collaborative platform that requires extensive keyboard input, complex mouse navigation away from the primary viewing area, or disruptive screen toggling during the live examination will be physically unviable and immediately rejected in a clinical setting.
- **Role in Dev/R&D** requires physical simulation. In the R&D process, MSK sonographers are absolutely critical for the live usability testing of the platform's interface within a physical, dynamic, bedside environment. They are essential for defining the strict parameters of real-time AI visual overlay features, rigorously ensuring that the added visual interface does not accidentally obscure critical, subtle diagnostic data on the monitor.
- **How to approach & percieve them (as Product-Dev Team)** demands a focus on ergonomics. The product team must explicitly perceive sonographers as highly kinetic, physically engaged users. The UX approach must aggressively prioritize hands-free (e.g., `voice-activated or pedal-driven`) or highly streamlined, `single-tap interactions.` The team should focus collaborative discussions on how the new platform can act as an invisible, silent assistant that automatically captures, precisely labels, and seamlessly integrates their isolated ultrasound findings into the broader MSK collaborative workspace alongside the static X-rays and MRIs, effectively bridging the data gap between dynamic and static imaging modalities.
### [**User Profile 6: The Physical Therapist / PhysioTherapy (Chuyên Viên Vật Lý Trị Liệu)**](https://gemini.google.com/share/4399a5d9c85d)
- Who They Are & Age Range
- **The Downstream Executor:** They are allied health professionals who operate strictly under physician-dictated prescriptions, meaning our system's Role-Based Access Control (RBAC) must legally prevent them from modifying primary medical diagnoses while giving them full autonomy over physical therapy application workflows.
- **Highly Stratified Educational Tiers:** Approximately 53% to 54.9% of the user base holds entry-level vocational certificates or 3-year diplomas (Tier 1) with low clinical autonomy, while the remaining cohort consists of 4-year [B.Sc](http://b.sc/). or rare postgraduate practitioners (Tier 2) who handle advanced clinical reasoning. Less than 1% of the entire active field holds a Master's degree or higher.
- **The Youth Avalanche Demographic:** This workforce is exceptionally young, with 36% to 40% falling into the 20 to 29 age bracket, and 41.7% between 30 and 39. Less than 10% to 14% of active practitioners are over the age of 40.
- **Gender-Variable Physical Mechanics:** Females comprise 60% to 62% of the workforce in general urban hospital units, but the user base shifts to 78.9% male in high-intensity environments like military field hospitals. Your frontend design must feature scalable touch targets and layout adaptability to support varying hand sizes and physical environments.
- **The Digital Native Vulnerability Paradox:** While their youth makes them highly tech-literate and fast adopters of cloud-based collaborative platforms, their lack of long-term clinical experience makes them highly prone to early-career physical burnout.
- Domain Proficiency / Responsibility
- **Hardware and Modality Calibration:** They are highly proficient in calibrating and operating physical treatment agents including TENS, NMES, Shortwave Diathermy, and therapeutic ultrasound machines.
- **High-Exertion Manual Interventions:** They routinely execute physically taxing techniques such as joint mobilizations, deep tissue manipulation, trigger point releases, and intensive stretching protocols.
- **Kinetic Patient Handling:** They are responsible for the heavy physical labor of lifting, transferring, and repositioning immobile, post-surgical, or neurological patients.
- **Chaotic Context Switching:** Their workflow requires them to switch instantly between intense cognitive patient assessments, fine-tuning hardware configuration parameters, and performing exhausting physical manual therapy.
- Working Environment
- **The Resource-Constrained Public Sector:** The majority of your users operate in general hospitals characterized by extreme patient volumes, high ambient noise, and cramped treatment rooms often smaller than 20 square meters. Stationary desktop workstations are scarce, shared by dozens of staff members, and physically isolated in department corners.
- **The State-of-the-Art Private Sector:** A smaller subset works in international or specialized sports clinics featuring advanced, combined therapy units, spacious layouts, and lower patient-to-therapist ratios that afford the time for deep data interaction.
- **Austere and Remote Settings:** Some practitioners operate in military field installations or rural clinics with severe spatial constraints and highly volatile, low-bandwidth network infrastructure.
- What They Know
- **Granular Musculoskeletal Biomechanics:** They possess an expert, native understanding of human skeletal anatomy, muscle origins, insertions, innervations, and compound kinetic chains.
- **Physiological Tissue Dynamics:** They understand exactly how different sound wave frequencies, heat agents, and electrical currents interact with and alter biological tissue elasticity.
- **Acute Tactile Literacy:** They have highly conditioned palpatory skills, meaning they can instantly detect underlying structural changes, muscle guarding, and tissue density abnormalities purely through manual physical touch.
- What They Do Not Know
- **Raw Radiological Imaging Literacy:** Unless they hold specialized postgraduate certifications, reading raw, grayscale imaging data, recognizing subtle bone pathomechanics on an X-ray, or interpreting artifact anomalies on a scan is entirely outside their foundational education.
- **Formal Evidence-Based Practice (EBP) Architecture:** The vast majority have received zero academic training in research methodologies. They do not know how to construct standardized PICO search strings or navigate academic index databases like Medline.
- **AI Mathematical Frameworks:** Computational models, computer vision neural networks, and algorithmic prediction logic are completely opaque to them, meaning they perceive any unexplained AI output as an untrustworthy "black box".
- **Integrated Longitudinal Records:** Due to systemic hospital data silos, they operate without any automated visibility into a patient's cross-departmental records, lab results, or concurrent medical prescriptions.
- Attitude Toward AI/ML
- **Defensiveness Against Clinical Devaluation:** Due to local market saturation and low entry-level compensation, younger therapists harbor economic anxiety about being commoditized. If our AI delivers authoritarian, rigid treatment mandates that bypass their personal clinical judgment, they will view the app as a threat and hostilely reject it.
- **Appetite for Objective Validation Tools:** Conversely, they are highly receptive to features that provide empirical, quantifiable feedback (such as automatically calculating structural changes over a 6-week protocol) because it gives them undeniable data to validate their clinical expertise to skeptical doctors and patients.
- **Acceptance Contingent on Transparancy:** They will only trust machine learning suggestions if the interface utilizes Explainable AI (XAI) principles, explicitly displaying the underlying clinical metrics behind a recommendation.
- Pain Points AI Should Help With
- **The Information Bottleneck:** Vietnamese Physiotherapists struggle to accurately target internal tissue pathologies during therapy because doctors rarely share full digital DICOM imaging data down the chain, providing only brief text prescription sheets, leading to semi-blind therapeutic execution via estimated surface anatomy and reduced treatment efficacy.
- **The WMSD Crisis:** Vietnamese Physiotherapists struggle to maintain their own physical health and career longevity because constant manual strain and repetitive high-intensity clinical interventions overload their bodies, leading to an alarming 76.4% prevalence rate of painful, debilitating Work-Related Musculoskeletal Disorders.
- **Crippling Time Poverty:** Vietnamese Physiotherapists struggle to implement evidence-based clinical practices and complete manual charting because extreme caseload pressures force them to treat 11 to 20+ patients per single daily shift, leading to severe operational time constraints, administrative exhaustion, and zero available time for typing medical records.
- **`The Cross-Domain Literacy Gap`:** Vietnamese Physiotherapists struggle to accurately interpret diagnostic findings and seamlessly communicate with prescribing physicians because their training in kinetic biomechanics completely mismatches the physician’s world of raw radiological data, a barrier compounded by a massive 84% foreign language deficit and zero formal training in clinical statistics, leading to severe inter-departmental communication barriers, a reliance on subjective guesswork, and highly ineffective or contraindicated treatment suggestions.
- Hindrances in Solution Design
- **The Severe Foreign Language Barrier:** A massive 84% of Vietnamese PTs cite reading professional literature in foreign languages as their primary professional barrier, with only 25% reporting adequate English reading skills. Any unlocalized English UI elements or untranslated clinical documentation will result in total system failure.
- **The "Informal Peer" Workflow Loop:** When facing a complex clinical decision, 96% rely on personal experience, 93% rely on informal chats with nearby peers, and 86% rely on old textbooks. They almost never utilize formal digital research dockets.
- **Physical UI Contamination:** Because their hands are continuously covered in conductive ultrasound transmission gels, massage oils, or sweat, precise multi-touch menus and complex text inputs are completely unusable during patient sessions.
- Role in Dev/R&D
- **Physical Usability Grounding:** They must be utilized in ethnographic shadowing and beta testing to ensure our interface supports knuckle taps, gestures, or stylus interactions that function seamlessly when hands are covered in gel.
- **FRONTEND CLINICAL VALIDATION:** They act as our real-time feedback loop, manually flagging when automated AI protocol recommendations conflict with a patient's physical pain tolerance or structural presentation.
- How to Approach & Perceive Them (as Product-Dev Team)
- **The "Clinical Athlete" Engineering Model:** Never design this software as if it is for a stationary desktop user. You must treat the PT as a highly kinetic, physically exhausted movement athlete who requires an interface optimized for extreme speed, low cognitive friction, and rapid physical access.
- **The Ergonomic Value Proposition:** Frame the entire platform to the client not as a data tracking utility, but as an **intelligent digital exoskeleton** engineered specifically to absorb their administrative workload, protect their bodies from chronic injury, and visually elevate their clinical standing.
---
### Out-of-Domain Glossary (Physiotherapy & MSK Jargon)
### 1. Core Clinical Infrastructure & Data Types
- **DICOM (Digital Imaging and Communications in Medicine):** The international file format standard for medical imaging. A single DICOM file contains uncompressed high-fidelity image data bundled with heavy, embedded metadata tables detailing patient demographics, scanning coordinates, and precise machine calibration arrays.
- **MSK (Musculoskeletal):** The complex anatomical framework comprising muscles, bones, cartilage, joints, ligaments, tendons, and bursa that support structure and enable physical locomotion.
- **EBP (Evidence-Based Practice):** A medical decision-making framework requiring clinicians to systematically integrate the highest quality current published scientific research with their personal clinical expertise and the unique preferences of the patient.
- **PICO Formulation:** A standardized syntax used to convert complex, vague clinical problems into clean, structured queries. It isolates variables into: **P**atient/Problem, **I**ntervention, **C**omparison, and **O**utcome.
### 2. Physical Therapy Modalities & Hardware Targets
- **Therapeutic Ultrasound:** A physical therapy device that emits high-frequency sound waves (0.8 to 3 MHz) directly into tissue via a handheld transducer to generate deep localized heat, dilate blood vessels, and increase collagen elasticity. Note: Unlike diagnostic ultrasound, it cannot generate an image on a screen.
- **Diagnostic Ultrasound (Sonography):** An imaging modality used by doctors to capture and display real-time, dynamic grayscale representations of soft tissue boundaries, structural inflammation, and fluid accumulation.
- **TENS (Transcutaneous Electrical Nerve Stimulation):** A modality that delivers low-voltage electrical currents via skin-surface electrodes to stimulate sensory nerves, effectively jamming the neural pathways that transmit pain signals to the brain.
- **NMES (Neuromuscular Electrical Stimulation):** A device that passes electrical currents directly into a muscle belly to force involuntary muscle contractions, commonly utilized to reverse muscle atrophy or re-train pathways after neurological trauma.
- **Shortwave Diathermy (SWD):** A high-frequency electromagnetic modality that uses deep wave currents to apply uniform therapeutic heat to extensive, deep-seated muscle masses and joint structures.
- **Extracorporeal Shockwave Therapy:** A machine that emits high-energy acoustic shock waves into chronic, calcified soft tissues to intentionally cause localized micro-trauma, forcing the body to restart its natural healing and inflammatory cascades.
### 3. Manual Techniques & Structural Frameworks
- **Joint Mobilization:** A skilled, passive manual therapy technique where a PT applies targeted, graded physical forces at specific angles to glide, slide, or distract a patient's joint structures to restore normal structural motion.
- **PNF (Proprioceptive Neuromuscular Facilitation):** An advanced therapeutic stretching framework that alternatingly triggers muscle contraction and passive relaxation against manual resistance to override standard neurological muscle-tightness reflexes.
- **Palpatory Literacy:** The highly trained ability of a healthcare professional to identify underlying structural pathologies, knots, density variances, and fluid effusions solely via physical fingertip touch and manual assessment.
- **RUSI (Rehabilitative Ultrasound Imaging):** The practice of using real-time ultrasound imaging during a physical therapy session as a visual biofeedback tool so both the therapist and the patient can immediately see if deep postural stabilization muscles are firing correctly.
- **Anisotropic Artifact:** A physics-based visual error on an ultrasound scan where a completely healthy, uniform tendon appears falsely dark, hypoechoic, or "torn" simply because the acoustic beam did not strike the tissue fibers at a perfect 90-degree perpendicular angle.
- **WMSDs (Work-Related Musculoskeletal Disorders):** Inflammation or structural damage to muscles, nerves, tendons, or ligaments that is directly caused, accelerated, or aggravated by repetitive work tasks, sustained poor ergonomics, or heavy physical lifting.
---
### **User Profile 8: The MSK Patient & Family Caregiver (Bệnh nhân Cơ xương khớp & Người nhà)**
- **Who they are** represents the most vulnerable and most populous user segment. This profile comprehensively encompasses individuals suffering from chronic or acute locomotive disorders, ranging from severe, mobility-limiting osteoarthritis to debilitating, acute herniated discs, alongside their immediate, highly involved family members. In the specific Vietnamese socio-cultural context, serious medical decisions are practically never made in isolation by the individual; adult children frequently and aggressively navigate the complex healthcare system on behalf of their elderly parents, while parents aggressively seek the absolute best care for their children, driven by deep, unwavering cultural imperatives.
- **Age range** is bifurcated. The primary patients themselves are predominantly middle-aged to elderly (45 to 80+ years old), firmly representing the demographic most biologically afflicted by degenerative MSK diseases. However, the primary active users of the digital platform are very often their younger, more agile family caregivers (20 to 45 years old) who actually possess the required digital literacy to effectively navigate complex hospital apps, successfully book "green lane" digital appointments, and actively participate in digital social media health forums to crowdsource opinions.
- **Domain proficiency / responsibility** regarding formal medical science is generally very low. However, they often possess high, albeit heavily skewed, experiential knowledge based on vast amounts of anecdotal evidence frantically gathered from community networks, massive online forums like Webtretho, or specialized, highly active Facebook groups. Their primary, exhausting responsibility is managing daily, chronic pain, attempting to adhere to complex treatment protocols (often poorly due to misunderstanding), and physically navigating the logistical nightmares of public hospital attendance.
- **Working environment** is the home, the pharmacy, and the crowded hospital waiting room. Their environment sharply contrasts with the highly structured clinical setting. Their primary interaction with the healthcare system is deeply characterized by exceptionally long wait times, profound anxiety, and a pervasive feeling of disenfranchisement within the massive, impersonal machinery of central hospitals. They exist in a daily information ecosystem completely saturated with highly conflicting information regarding the efficacy of modern surgical medicine versus traditional, highly accessible remedies.
- **What they know** is highly localized and experiential. They intimately know the exact nature of their own pain, their specific mobility limitations, and the severe financial strain their chronic condition places on the entire family unit. They explicitly know how to aggressively seek out alternative solutions when left frustrated by the extreme brevity of public hospital consultations, often turning in desperation to slick chiropractic videos on YouTube or utilizing unregulated folk healers operating within their local communities.
- **What they do not know** poses a severe health risk. They fundamentally do not understand the underlying biomechanical realities of their specific conditions. They absolutely do not know how to read a standard X-ray or MRI, seeing only confusing, intimidating shades of gray. Crucially, they often do not understand the severe, irreversible risks associated with unscientific treatments, such as the distinct potential for permanent paralysis from incorrect, aggressive acupressure or massive spinal infection from applying raw leaves directly to spinal regions. They also deeply struggle to comprehend the realistic limitations of surgical interventions, often erroneously expecting immediate, permanent, pain-free cures.
- **Attitude toward AI/ML** is largely unformed, highly malleable, but exceptionally susceptible to the precise UI framing of the technology. If the AI is expertly presented as a high-tech, highly objective authority that visually validates their human doctor's hurried diagnosis, it can significantly and immediately increase institutional trust. Because ethnographic data proves many patients already actively seek second opinions on Facebook groups by desperately posting their raw scans , an AI tool integrated into a patient portal that provides an immediate, highly understandable, beautifully rendered visual analysis of their DICOM images would be viewed as highly empowering, deeply reassuring, and vastly superior to social media crowdsourcing.
- **Pain points AI should help with** are driven by fear of the unknown. The overwhelming pain point is profound confusion and anxiety stemming directly from a lack of comprehensible, visually accessible information. AI must explicitly help by transforming terrifying, complex DICOM scans into clear, color-coded, interactive 3D anatomical models that explicitly illustrate their specific injury or degeneration in laymen's terms. The platform must actively provide localized, deeply culturally contextualized educational content that patiently explains *why* specific medical treatments are necessary and explicitly *why* specific, popular folk remedies like leaf-wrapping are actively dangerous.
- **Hindrances in solution design** are heavily rooted in digital inequity. The digital divide is the most profound, systemic hindrance. Elderly patients exhibit significant, stubborn resistance and a literal inability to adopt new mobile technologies, often actively preferring traditional, highly inefficient "arrive early and wait" methods over interacting with modern digital scheduling apps, directly undermining efficiency efforts like the "luồng xanh". Furthermore, if the platform's educational material is heavily text-based or overly academic in tone, it will be immediately ignored in favor of highly engaging, visually stimulating, but medically inaccurate, social media video content. The necessary reliance on a proxy user (the younger caregiver) vastly complicates the technical design of direct-to-patient privacy, data security, and consent architectures.
- **Role in Dev/R&D** demands emotional intelligence from the researchers. Patients and their caregivers must be central to the rigorous evaluation of the platform's accessibility, emotional resonance, and comprehensibility. Their required role in R&D involves deep usability testing of the patient portal, specifically ensuring that the AI-translated educational visuals are actually lowering clinical anxiety rather than inadvertently increasing it by displaying terrifyingly realistic pathology. They provide critical, irreplaceable feedback on the emotional tone of the entire user interface.
- **How to approach & percieve them (as Product-Dev Team)** requires profound empathy and accessible design principles. The product development team must perceive this vast profile with deep empathy, explicitly recognizing them as highly vulnerable users frantically navigating a complex, high-anxiety ecosystem. The UX approach must aggressively prioritize extreme, uncompromising simplicity, absolute visual clarity, and highly robust accessibility features (e.g., massive font scaling, high-contrast modes, voice-over capabilities). The team must strategically view the younger caregiver as the primary digital conduit to the elderly patient, thereby requiring the design of sophisticated dual-access interface architectures that allow entire families to collaboratively view, discuss, and understand the educational outputs securely generated from the clinical workspace.
- The Multi-hat Scenarios (where 1 doctors shall involve multiple-hats of professional is usual in Vietnam)
---

1
workspace/sprint_1_2/Design_Material/LEGACY/VKIST_ML/codebase-vkist-ultrasound-legacy Submodule

Submodule workspace/sprint_1_2/Design_Material/LEGACY/VKIST_ML/codebase-vkist-ultrasound-legacy added at 8b2758928a

578
workspace/sprint_1_2/Design_Material/LEGACY/VKIST_ML/docs/Instruction_Manunal_API_Doc_Setup_pilot.md Normal file
View File

@@ -0,0 +1,578 @@
# KNEE ULTRASOUND ANALYSIS API: TÀI LIỆU KỸ THUẬT & HƯỚNG DẪN SỬ DỤNG
**Phiên bản:** 1.0 | **Ngày:** 03/2026
**Framework:** FastAPI + PyTorch | **Python:** 3.10+
---
## 1. Tổng quan hệ thống
Knee Ultrasound Analysis API được xây dựng bằng FastAPI, chuyên phục vụ tác vụ phân tích ảnh siêu âm đầu gối. Hệ thống tích hợp nhiều mô hình Học máy sâu (Deep Learning) nhằm tự động hóa quy trình phân loại mặt cắt, phát hiện dấu hiệu viêm, phân đoạn cấu trúc giải phẫu và đo lường kích thước tổn thương định lượng.
### 1.1 Các chức năng chính
* **Phân loại góc chụp siêu âm (Angle Classification):** Tự động nhận dạng mặt cắt/góc chụp từ ảnh đầu vào bao gồm các nhãn: `med-lat`, `post-trans`, `sup-trans-flex`, và `sup-up-long`.
* **Phát hiện viêm (Inflammation Detection):** Xác định sự hiện diện của tình trạng viêm khớp gối qua hai góc chụp chính là `sup-up-long` và `post-trans`.
* **Phân đoạn ảnh ngữ nghĩa (Segmentation):** Tách biệt các cấu trúc giải phẫu đích (dịch khớp, gân, xương, màng hoạt dịch...) thành các phân vùng mặt nạ màu riêng biệt.
* **Đo độ dày tự động (Thickness Measurement):** Tự động tính toán khoảng cách hình học theo đơn vị milimét ($mm$) giữa các phân vùng mô mềm đã được phân đoạn (chỉ áp dụng đối với mặt cắt góc `sup-up-long`).
* **Đánh giá mức độ viêm (Severity Analysis):** Xếp hạng thang điểm mức độ nghiêm trọng của viêm từ cấp độ 0 (Rất nhẹ) đến cấp độ 3 (Nặng) dựa trên tỷ lệ diện tích dịch khớp và sự tăng sinh màng hoạt dịch.
### 1.2 Luồng xử lý dữ liệu tổng thể (Pipeline Processing)
Khi nhận tập tin ảnh từ máy trạm (Client), hệ thống sẽ thực hiện phân nhánh xử lý logic động dựa trên kết quả của khối phân loại góc chụp:
| Góc chụp phát hiện | Quy trình xử lý chi tiết trong Backend pipeline |
| --- | --- |
| **`post-trans`** | Phân loại góc $\rightarrow$ Phát hiện viêm $\rightarrow$ Phân đoạn ảnh POST $\rightarrow$ Trả kết quả JSON & Mask.|
| **`sup-up-long`** | Phân loại góc $\rightarrow$ Phát hiện viêm $\rightarrow$ Phân đoạn ảnh SUP $\rightarrow$ Đo độ dày mô $\rightarrow$ Đánh giá mức độ nặng $\rightarrow$ Trả kết quả.|
| **`med-lat`** or **`sup-trans-flex`** | Chỉ thực hiện phân loại góc $\rightarrow$ Trả kết quả trực tiếp (Bỏ qua nhánh phân đoạn & đo lường).|
```plantuml
@startuml
skinparam PackageStyle rect
skinparam BackgroundColor #FFFFFF
skinparam ArrowColor #2C3E50
title KIẾN TRÚC ĐIỀU HƯỚNG PIPELINE BACKEND (FASTAPI)
start
:Nhận ảnh siêu âm thô (Multipart HTTP Post);
:Chạy mô hình Phân loại Góc chụp (Angle Classification);
if (Góc chụp nhận diện được là gì?) then (post-trans)
:Chạy mô hình Phát hiện Viêm;
:Chạy mô hình Phân đoạn góc POST (Deeplabv3 ResNet101);
:Kết xuất Ảnh Overlay Mask & Metadata;
elseif (sup-up-long) then (sup-up-long)
:Chạy mô hình Phát hiện Viêm;
:Chạy mô hình Phân đoạn góc SUP (Tùy chọn: Deeplabv3 / UNet3+ / vv.);
:Tính toán độ dày tự động (Thickness Measurement);
:Tính toán điểm Severity (Severity Score Analysis);
:Kết xuất Ảnh Overlay Mask & Thống kê định lượng;
else (med-lat / sup-trans-flex)
:Ghi nhận nhãn góc chụp;
note right: Không cấu hình phân đoạn\ncho các mặt cắt này
endif
:Đóng gói Response JSON (Success=True);
:Trả kết quả về cho Client Application;
stop
@enduml
```
---
## 2. Hướng dẫn cài đặt & Triển khai môi trường
### 2.1 Yêu cầu hệ thống tối thiểu
| Thành phần cấu phần | Thông số kỹ thuật yêu cầu tối thiểu |
| --- | --- |
| **Hệ điều hành** | Ubuntu 20.04+ / Windows 10+ / macOS 12+ |
| **Môi trường Python** | Phiên bản 3.10 cố định |
| **Bộ nhớ RAM** | 16 GB trở lên |
| **Bộ xử lý đồ họa (GPU)** | NVIDIA GPU hỗ trợ nền tảng CUDA 12.4 (Khuyến nghị để tối ưu tốc độ) |
| **Dung lượng VRAM** | Tối thiểu 8 GB (Khuyến nghị 16 GB nếu chạy song song đồng thời nhiều mô hình)|
| **Ổ cứng lưu trữ** | Tối thiểu 15 GB dung lượng trống (Dành cho bộ cài đặt và file weights `.pth`) |
| **Bộ công cụ bổ trợ** | CUDA Toolkit 12.4 & cuDNN 9.x tương thích tương ứng|
### 2.2 Khởi tạo môi trường ảo
Tải mã nguồn dự án từ kho lưu trữ Git:
```bash
git clone https://github.com/itvkist/vkist-ultrasound.git
cd vkist-ultrasound
```
Khuyến nghị thiết lập môi trường bằng **Conda** nhằm quản lý và cô lập các gói phụ thuộc:
```bash
conda create -n vkist-ultrasound python=3.10 -y
conda activate vkist-ultrasound
```
*Hoặc khởi tạo nhanh bằng mô-đun thư viện chuẩn `venv` nếu hệ thống chưa cài đặt Anaconda*:
```bash
# Trên nền tảng hệ điều hành Linux / macOS
python3.10 -m venv venv
source venv/bin/activate
# Trên nền tảng hệ điều hành Windows
venv\Scripts\activate
```
### 2.3 Cài đặt các gói thư viện phụ thuộc (Dependencies)
Thực hiện cài đặt các thư viện lõi quy định trong tệp cấu hình:
```bash
pip install -r requirements.txt
```
Trong trường hợp nhân của khung phần mềm PyTorch không nhận diện được phần cứng CUDA, tiến hành ghi đè cài đặt thủ công phiên bản biên dịch GPU:
```bash
pip install torch==2.5.0+cu124 torchvision==0.20.0+cu124 --index-url https://download.pytorch.org/whl/cu124
```
> ⚠️ **LƯU Ý QUAN TRỌNG VỀ PACKAGE NATTEN:**
> Dòng cấu hình cài đặt gói `natten==0.17.3+torch250cu124` mặc định đã bị gắn chú thích (`#` comment out) trong tệp `requirements.txt`. Nếu bạn sử dụng các kiến trúc mạng Transformer nâng cao yêu cầu gói này, bắt buộc cài đặt thủ công qua liên kết phân phối bánh xe (wheels) chính thức:
> `pip install natten==0.17.3+torch250cu124 -f https://shi-labs.com/natten/wheels/`
>
>
### 2.4 Cấu trúc cây thư mục dự án chuẩn
Để đảm bảo hệ thống FastAPI khởi chạy chính xác và tự động nạp các tệp trọng số mô hình, cấu trúc cây thư mục dự án cần được sắp xếp như sau:
```text
project/
├── app.py # Trình khởi chạy máy chủ chính - FastAPI Server
├── requirements.txt # Danh sách các gói thư viện phụ thuộc hệ thống
├── arch/ # Thư mục mã nguồn chứa định nghĩa kiến trúc mạng Custom
│ ├── efficientfeedback.py # Định nghĩa mạng EfficientFeedbackNetwork
│ └── unet3plus_att.py # Định nghĩa mạng phân đoạn UNet3Plus_Attention
├── models/ # Thư mục lưu trữ tệp trọng số nhị phân (.pth)
│ ├── best_convnext_tiny.pth
│ ├── best_densenet.pth
│ ├── best_resnet50.pth
│ ├── best_efficientnet_b2.pth
│ ├── best_swin_v2_s.pth
│ ├── efficientnet_b0_ultrasound_2_class.pth
│ ├── best_model_Deeplav3.pth
│ ├── unet_resnet101.pth
│ ├── efficientfeedback.pth
│ ├── unet3plus_att.pth
│ └── best_model_deeplabv3_resnet101_seed_16.pth
├── templates/ # Các tài nguyên phục vụ giao diện Web tích hợp
│ ├── index.html
│ ├── css/
│ └── js/
├── uploads/ # Thư mục lưu trữ tạm ảnh thô đầu vào (Tự động khởi tạo)
└── results/ # Thư mục lưu trữ ảnh kết quả phân đoạn (Tự động khởi tạo)
```
### 2.5 Khởi động máy chủ dịch vụ
Thực thi lệnh chạy máy chủ tại thư mục gốc:
```bash
python app.py
```
**Mô phỏng nhật ký màn hình console khi máy chủ khởi chạy thành công:**
```độc_thoại
[INFO] Loading deep learning weights safely to memory...
[INFO] Device successfully mapped: cuda (NVIDIA GeForce RTX 4090)
[INFO] FastAPI Application core initialized.
[INFO] Uvicorn server running on http://localhost:8000 (Press CTRL+C to quit)
```
* **Giao diện Web UI kiểm thử trực quan:** `http://localhost:8000`
* **Tài liệu API tương tác tự động (Swagger UI):** `http://localhost:8000/docs`
---
## 3. Tài liệu đặc tả API (API Reference)
### 3.1 Trạng thái hoạt động (Health Check)
* **Endpoint:** `GET /api/health`
* **Chức năng:** Kiểm tra tính sẵn sàng phục vụ của cụm dịch vụ API Backend.
* **Định dạng dữ liệu phản hồi (Response JSON):**
```json
{
"status": "healthy"
}
```
### 3.2 Phân tích ảnh siêu âm chính - `POST /api/analyze`
Mã hóa dữ liệu đầu vào dưới dạng tệp tin `multipart/form-data` để gửi tới mạng mạng nơ-ron xử lý.
#### Các tham số yêu cầu (Request Parameters)
| Tham số cấu hình | Phương thức truyền | Kiểu dữ liệu | Giá trị mặc định | Định nghĩa chức năng chi tiết |
| --- | --- | --- | --- | --- |
| **`image`** | Multipart Form | Binary File | *Bắt buộc* | Tệp tin ảnh siêu âm đầu gối cần xử lý (Hỗ trợ mở rộng định dạng: `.jpg`, `.png`, `.bmp`).|
| **`angle_model`** | Query String | String | `convnext` | Tên định danh mô hình đảm nhận tác vụ phân loại góc chụp.|
| **`inflammation_model`** | Query String | String | `efficientnet_b0` | Mô hình phát hiện tình trạng viêm (Hiện tại cố định cấu hình mạng).|
| **`segment_model_sup`** | Query String | String | `deeplabv3` | Mô hình phân đoạn cấu trúc giải phẫu dành cho mặt cắt góc `sup-up-long`.|
| **`segment_model_post`** | Query String | String | `deeplabv3_resnet101` | Mô hình phân đoạn cấu trúc giải phẫu dành cho mặt cắt góc `post-trans`.|
#### Danh sách định danh mô hình khả dụng trong hệ thống
| Phân nhóm Task | Tên tham số truyền vào | Kiến trúc mạng nơ-ron gốc | Mô tả đặc tính đầu ra |
| --- | --- | --- | --- |
| **Phân loại Góc chụp** | `convnext` | ConvNeXt Tiny | Phân cấp phân loại ra 4 lớp nhãn đầu ra.|
| | `densenet` | DenseNet-121 | Mạng kết nối dày đặc.|
| | `resnet50` | ResNet-50 | Kiến trúc mạng dư thừa tiêu chuẩn.|
| | `efficientnet_b2` | EfficientNet-B2 | Tối ưu hóa đa quy mô tài nguyên mạng.|
| | `swin` | Swin Transformer V2-S | Kiến trúc Attention cửa sổ dịch chuyển.|
| **Phân đoạn góc SUP** | `deeplabv3` | DeepLabV3 ResNet-50 | Trích xuất đặc trưng đa tỷ lệ với 7 lớp đầu ra.|
| | `unet_resnet101` | UNet + ResNet-101 | Kiến trúc Encoder-Decoder kết hợp ResNet.|
| | `efficientfeedback` | EfficientFeedbackNetwork | Thiết kế tùy biến riêng có liên kết phản hồi dữ liệu.|
| | `unet3plus` | UNet3+ with Attention | Cơ chế Attention kết hợp kết nối toàn diện Full-scale.|
| **Phân đoạn góc POST** | `deeplabv3_resnet101` | DeepLabV3 ResNet-101 | Cấu trúc chuyên sâu phân đoạn góc nhìn mặt sau.|
#### Cấu trúc dữ liệu JSON phản hồi (Response Body Schema)
```json
{
"success": true,
"filename": "d3b07384-d113-4ec8-a141-8664b07fb8d3.jpg",
"images": {
"original": "/uploads/d3b07384-d113-4ec8-a141-8664b07fb8d3.jpg",
"segmented": "/results/seg_d3b07384-d113-4ec8-a141-8664b07fb8d3.jpg"
},
"models_used": {
"angle_model": "convnext",
"inflammation_model": "efficientnet_b0",
"segmentation_model": "deeplabv3"
},
"angle": {
"class": "sup-up-long",
"confidence": 98.45
},
"inflammation": {
"detected": true,
"confidence": 94.20
},
"segmentation": {
"angle_type": "sup",
"classes_detected": ["background", "effusion", "fat", "femur", "synovium", "tendon"],
"color_legend": {
"background": [0, 0, 0],
"effusion": [255, 0, 0],
"synovium": [255, 0, 255]
}
},
"measurement": {
"thickness_mm": 6.87,
"thickness_px": 100,
"location_x": 256
},
"severity": {
"level": 3,
"severity": "Nặng",
"combined_score": 18.4,
"effusion": {
"pixels": 25400,
"ratio": 0.096,
"thickness": 6.87
},
"synovium": {
"pixels": 12500,
"ratio": 0.047
}
}
}
```
#### Ví dụ mã triển khai gọi dịch vụ (Client Invocations)
* **Sử dụng lệnh Client cURL CLI:**
```bash
curl -X POST "http://localhost:8000/api/analyze?angle_model=convnext&segment_model_sup=deeplabv3" \
-F "image=@/data/medical/knee_sample.jpg"
```
* **Triển khai ứng dụng gọi qua script Python (Requests):**
```python
import requests
url = "http://localhost:8000/api/analyze"
query_parameters = {
"angle_model": "swin",
"segment_model_sup": "unet3plus"
}
target_image_path = "path/to/clinical_knee.jpg"
with open(target_image_path, "rb") as image_file:
payload = {"image": image_file}
api_response = requests.post(url, params=query_parameters, files=payload)
parsed_result = api_response.json()
print("Phân loại góc:", parsed_result["angle"]["class"])
print("Số liệu đo lường hình học:", parsed_result.get("measurement"))
```
---
## 4. Các thông số cấu hình lõi hệ thống
### 4.1 Hằng số hệ thống trong `app.py`
| Tên định danh hằng số | Giá trị mặc định | Diễn giải chức năng kỹ thuật |
| --- | --- | --- |
| `UPLOAD_FOLDER` | `'uploads'` | Đường dẫn cục bộ lưu trữ file ảnh thô nhận từ máy trạm.|
| `RESULTS_FOLDER` | `'results'` | Đường dẫn lưu ảnh màu sau phân đoạn (Color Mask Overlayed).|
| `TEMPLATES_FOLDER` | `'templates'` | Thư mục chứa mã nguồn giao diện phân tích Web UI.|
| `PIXEL_TO_MM` | $\frac{45.0}{655.0} \approx 0.0687$ | Hệ số chuyển đổi từ độ phân giải pixel sang kích thước thực tế ($mm$). Phụ thuộc cố định vào cấu hình đầu ra của phần cứng máy quét siêu âm.|
| `DEFAULT_MEASURE_IDS` | `[1, 5]` | Danh sách mảng chứa ID nhãn lớp cấu trúc giải phẫu kích hoạt thuật toán đo độ dày: `1 = effusion` (Dịch khớp), `5 = synovium` (Màng hoạt dịch).|
| `device` | `cuda` hoặc `cpu` | Khối phần cứng thực thi tính toán đồ họa (Tự động thiết lập dựa trên tính khả dụng của driver NVIDIA).|
### 4.2 Cấu hình Pipeline tiền xử lý và biến đổi ma trận ảnh (Transforms)
Hệ thống phân tách ảnh đầu vào thành các luồng biến đổi riêng biệt trước khi nạp vào tensor mô hình tùy thuộc vào mục tiêu xử lý chuyên biệt:
| Luồng xử lý Pipeline ảnh | Kích thước chuyển đổi (Resize) | Quy định chuẩn hóa phân phối ma trận (Normalization) |
| --- | --- | --- |
| **Phân loại góc & Phát hiện viêm** | <br>$224 \times 224$ pixel | Áp dụng phân phối phân cấp:<br> $\text{mean} = [0.485, 0.456, 0.406]$, <br> $\text{std} = [0.229, 0.224, 0.225]$ |
| **Phân đoạn cấu trúc (Segmentation)** | <br>$512 \times 512$ pixel | Không áp dụng chuẩn hóa phân phối (Chỉ thực thi hàm chuyển đổi tensor `ToTensor()`) |
---
## 5. Ràng buộc kỹ thuật & Quy tắc thiết kế hệ thống
### 5.1 Quản lý và giải phóng tài nguyên bộ nhớ GPU (VRAM Leak Warning)
Trong phiên bản hiện tại, logic xử lý nội tại của API kích hoạt các hàm `load_angle_model()`, `load_inflammation_model()`, và `load_segmentation_model_*()` trực tiếp bên trong vòng đời của mỗi phiên request nhận về. Hành vi này ép buộc GPU liên tục nạp lại dữ liệu tệp `.pth` vào VRAM cho mỗi giao dịch HTTP, sinh ra độ trễ (Overhead) I/O lớn và tiềm ẩn nguy cơ tràn bộ nhớ hệ thống. Khi triển khai môi trường Production, bắt buộc phải tái cấu trúc chuyển các hàm này thành Singleton dịch vụ (Tải một lần duy nhất lúc khởi động tiến trình Web Server).
### 5.2 Ràng buộc phi tuyến tính của tham số vật lý `PIXEL_TO_MM`
Hằng số quy đổi $\text{PIXEL\_TO\_MM} = \frac{45.0}{655.0}$ là một giá trị được cấu hình cứng (Hardcoded) trong mã nguồn, đặc trưng duy nhất cho một dòng máy siêu âm lâm sàng có tỷ lệ hiển thị $45mm$ tương đương với độ phân giải vùng quét $655\text{ px}$. Khi hệ thống thu thập ảnh siêu âm từ các thiết bị chuẩn đoán hình ảnh khác, hoặc thay đổi độ phân giải ảnh xuất ra, số liệu đo khoảng cách tổn thương sẽ sai lệch nghiêm trọng nếu hằng số này không được hiệu chuẩn lại thông qua ma trận nội quan của máy quét mới.
### 5.3 Quy tắc ánh xạ phân lớp (Class Remapping Matrix) đối với mô hình Custom
Hai mô hình tùy biến sâu phục vụ mặt cắt góc nhìn phía trên bánh chè (`UNet3+` và `EfficientFeedback Network`) được huấn luyện trên tập dữ liệu đặc thù sở hữu thứ tự cấu trúc mảng nhãn đầu ra lệch pha hoàn toàn so với kiến trúc phân cấp chuẩn của hệ thống. Để thống nhất dữ liệu trả về cho Client, khối Backend API thực hiện cơ chế tự động chuyển đổi chỉ mục mảng (Index Remapping) theo bảng đặc tả logic dưới đây:
| Chỉ mục Mô hình gốc (Output Model Index) | Chỉ mục chuẩn hóa hệ thống (Standard System Index) | Tên nhãn lớp giải phẫu tương ứng (Anatomical Label Class) |
| --- | --- | --- |
| `0` | `0` | **`background`** (Nền ảnh không chứa cấu trúc) |
| `1` | `2` | **`fat`** (Lớp mô mỡ dưới da) |
| `2` | `6` | **`tendon`** (Cấu trúc gân cơ) |
| `3` | `1` | **`effusion`** (Vùng tụ dịch khớp gối ổ viêm) |
| `4` | `4` | **`femur`** (Ranh giới cấu trúc xương đùi) |
| `5` | `5` | **`synovium`** (Màng hoạt dịch bao quanh khớp) |
| `6` | `3` | **`fat-pat`** (Tổ chức mỡ Hoffa) |
### 5.4 Cơ chế tự động dọn dẹp tập tin tồn đọng (Garbage Collection Task)
Các tập tin ảnh thô tải lên thư mục `uploads/` và ảnh xử lý nhị phân kết xuất lưu trong `results/` được ghi dưới dạng định danh chuỗi không trùng lặp UUID và lưu trữ vô thời hạn trên đĩa cứng hệ thống. Hệ thống lõi của ứng dụng không tích hợp cơ chế tự động giải phóng (Auto-deletion) các tệp cũ. Khi chạy vận hành dài hạn trong hệ thống y tế thực tế, bắt buộc phải cấu hình thêm Background Task (sử dụng thư viện Asyncio) hoặc thiết lập dịch vụ Cronjob của hệ điều hành để dọn dẹp định kỳ tránh cạn kiệt dung lượng ổ đĩa lưu trữ.
---
## 6. Giải pháp mở rộng tính năng mã nguồn (Backend Optimization Guide)
### 6.1 Tăng tốc độ phản hồi bằng Cơ chế Caching Mô hình Toàn cục
Thay thế kiến trúc nạp tải mô hình cũ bằng một kho lưu trữ Cache tĩnh trong bộ nhớ RAM, tối ưu hóa thời gian xử lý request từ mức giây xuống mức mili-giây:
```python
# Cấu hình biến lưu trữ toàn cục ở đầu tệp app.py
global_model_cache = {}
def get_cached_angle_model(selected_model_name: str):
cache_lookup_key = f"angle_classification_{selected_model_name}"
if cache_lookup_key not in global_model_cache:
# Thực hiện nạp trọng số mô hình từ đĩa cứng lần đầu tiên
global_model_cache[cache_lookup_key] = load_angle_model(selected_model_name)
return global_model_cache[cache_lookup_key]
# Áp dụng logic tương tự cho get_inflammation_model(), get_seg_model_sup(), get_seg_model_post()
```
### 6.2 Thêm mới một kiến trúc phân loại góc chụp (Ví dụ: Vision Transformer - ViT)
Để tích hợp một mạng nơ-ron mới vào hệ thống xử lý, tuân thủ nghiêm ngặt quy trình 3 bước sau:
* **Bước 1:** Bổ sung khối xử lý điều kiện rẽ nhánh logic vào hàm khởi tạo mô hình `load_angle_model()`:
```python
elif model_name == 'vit':
from torchvision.models import vit_b_16
# Khởi tạo mạng mạng ViT không nạp trọng số mặc định ImageNet
model = vit_b_16(weights=None)
# Tái cấu trúc tầng phân loại tuyến tính cuối cùng tương thích với 4 lớp nhãn đầu gối
model.heads[0] = nn.Linear(model.heads[0].in_features, 4)
# Tải tệp trọng số huấn luyện cục bộ từ thư mục mô hình
checkpoint_tensor = torch.load('models/best_vit_b16.pth', map_location=device, weights_only=False)
model.load_state_dict(checkpoint_tensor)
```
* **Bước 2:** Di chuyển tệp trọng số huấn luyện nhị phân của mạng (`best_vit_b16.pth`) vào chính xác không gian lưu trữ của thư mục `/models/`.
* **Bước 3:** Ứng dụng phía Client có thể kích hoạt mạng mới bằng cách truyền giá trị định danh qua tham số URL: `/api/analyze?angle_model=vit`.
### 6.3 Xử lý luồng dữ liệu phân đoạn song song đồng thời (Batch Processing API)
Tối ưu hóa năng lực phục vụ của Server đối với bài toán nhận diện hàng loạt ảnh cùng lúc từ phòng khám bằng endpoint xử lý không đồng bộ:
```python
from fastapi import errors, status
from fastapi.responses import JSONResponse
from typing import List
@app.post('/api/analyze_batch', status_code=status.HTTP_200_OK)
async def analyze_batch_images(images: List[UploadFile] = File(...)):
import asyncio
# Đóng gói các tác vụ phân tích ảnh đơn lẻ vào một danh sách hàng đợi task không đồng bộ
async_tasks_queue = [analyze_single_image_pipeline(img) for img in images]
# Kích hoạt thực thi đồng thời trên luồng phần cứng thông qua gather cơ chế
compiled_batch_results = await asyncio.gather(*async_tasks_queue)
return JSONResponse({
"results": compiled_batch_results,
"processed_count": len(compiled_batch_results)
})
```
### 6.4 Bản đóng gói container hóa ứng dụng (Production Dockerfile)
Đóng gói toàn bộ ML Stack bao gồm trình điều khiển GPU NVIDIA CUDA để triển khai đồng bộ trên các hạ tầng Cloud hoặc máy chủ On-Premise của bệnh viện:
```dockerfile
# Sử dụng Base Image chứa sẵn môi trường CUDA 12.4 và cuDNN 9 của NVIDIA
FROM nvidia/cuda:12.4.0-cudnn9-runtime-ubuntu22.04
# Cài đặt môi trường Python 3.10 và các gói hệ thống cốt lõi
RUN apt-get update && apt-get install -y \
python3.10 \
python3-pip \
git \
&& rm -rf /var/lib/apt/lists/*
# Thiết lập không gian làm việc nội bộ bên trong container
WORKDIR /app
# Sao chép và cài đặt danh sách các thư viện Python
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Sao chép toàn bộ mã nguồn ứng dụng vào Container
COPY . .
# Lắng nghe và kích hoạt ứng dụng Web Server FastAPI
CMD ["python", "app.py"]
```
* **Lệnh khởi dựng Image hệ thống:** `docker build -t medical-api-service .`
* **Lệnh kích hoạt Container chia sẻ tài nguyên phần cứng GPU vật lý:**
```bash
docker run --gpus all -p 8000:8000 -v $(pwd)/models:/app/models medical-api-service
```
### 6.5 Bộ chuyển đổi tiếp nhận trực tiếp luồng dữ liệu ảnh y tế chuẩn DICOM
Mở rộng chức năng cho phép hệ thống API đọc trực tiếp tệp tin ảnh gốc dạng `.dcm` trích xuất trực tiếp từ các thiết bị siêu âm chuẩn lâm sàng trong bệnh viện mà không cần qua bước chuyển đổi định dạng thủ công:
```python
import pydicom
from PIL import Image
import io
@app.post('/api/analyze_dicom')
async def analyze_dicom_file(file: UploadFile = File(...)):
# Đọc luồng byte nhị phân trực tiếp từ tệp DICOM tải lên
dicom_dataset = pydicom.dcmread(file.file)
# Trích xuất ma trận pixel thô từ thẻ DICOM Pixel Data
raw_pixel_array = dicom_dataset.pixel_array
# Chuyển đổi ma trận mảng Numpy sang định dạng ảnh PIL tương thích với Pipeline biến đổi
converted_image_pil = Image.fromarray(raw_pixel_array).convert('RGB')
# Chuyển tiếp ảnh đã đổi định dạng vào luồng xử lý tự động nội bộ của API
analysis_output_json = await execute_core_analysis_pipeline(converted_image_pil)
return analysis_output_json
```
---
## Phụ lục: Đặc tả Dữ liệu định lượng lâm sàng
### Phụ lục A: Bảng phân định mã màu mặt nạ phân đoạn ngữ nghĩa (Color Map Legend)
1. Cấu trúc Mặt cắt mặt trên bánh chè - Góc SUP (`sup-up-long`)
Góc SUP tập trung khoanh vùng các lớp mô mềm phía trước đầu gối phục vụ thuật toán tính toán độ dày dịch tụ.
| Từ khóa nhãn (Key) | Cấu trúc giải phẫu đích | Mã màu hiển thị (RGB) | Trực quan hóa màu sắc |
| --- | --- | --- | --- |
| `background` | Nền ảnh siêu âm | `[0, 0, 0]` | ⬛ Đen (Không chứa dữ liệu) |
| `effusion` | Vùng dịch khớp tụ ổ viêm | `[255, 0, 0]` | 🟥 Đỏ |
| `fat` | Tổ chức mô mỡ dưới da | `[255, 255, 0]` | 🟨 Vàng |
| `fat-pat` | Khối mỡ Hoffa | `[0, 255, 255]` | 🟦 Lam sáng |
| `femur` | Cấu trúc bề mặt xương đùi | `[0, 255, 0]` | 🟩 Xanh lá |
| `synovium` | Lớp màng hoạt dịch tăng sinh | `[255, 0, 255]` | 🟪 Tím |
| `tendon` | Vùng bó gân cơ | `[0, 0, 255]` | 🟦 Xanh dương |
> 🔄 **QUY TẮC CHUYỂN ĐỔI CHUYỂN GÓC (SUP $\rightarrow$ POST):**
> Khi hệ thống chuyển đổi trạng thái phân tích sang mặt cắt phía sau khớp gối (Góc `POST`), ma trận thuật toán phân đoạn sẽ tự động tái cấu trúc màu sắc ngữ nghĩa: Vùng tổn thương chứa **`effusion`** (màu đỏ) sẽ chuyển trạng thái biểu diễn thành **`baker's cyst`** (Kén Baker), và tổ chức cấu trúc vùng **`fat-pat`** (màu lam sáng) sẽ hoán đổi ý nghĩa thành vùng **`muscle`** (Cơ bắp vùng khoeo).
>
>
2. Cấu trúc Mặt cắt mặt sau vùng khoeo chân - Góc POST (`post-trans`)
| Từ khóa nhãn (Key) | Cấu trúc giải phẫu đích | Mã màu hiển thị (RGB) | Trực quan hóa màu sắc |
| --- | --- | --- | --- |
| `background` | Nền ảnh siêu âm | `[0, 0, 0]` | ⬛ Đen |
| `baker's cyst` | Tổ chức kén hoạt dịch vùng khoeo (Baker) | `[255, 0, 0]` | 🟥 Đỏ |
| `fat` | Lớp mô mỡ | `[255, 255, 0]` | 🟨 Vàng |
| `muscle` | Các nhóm cơ bắp vùng sau gối | `[0, 255, 255]` | 🟦 Lam sáng |
| `femur` | Cấu trúc xương đùi sau | `[0, 255, 0]` | 🟩 Xanh lá |
| `synovium` | Màng hoạt dịch mặt sau | `[255, 0, 255]` | 🟪 Tím |
| `tendon` | Hệ thống gân cơ mặt sau | `[0, 0, 255]` | 🟦 Xanh dương |
---
### Phụ lục B: Thang điểm đánh giá mức độ nghiêm trọng của ổ viêm (Clinical Severity Score)
Hệ thống chấm điểm toán học tự động căn cứ trên trọng số diện tích và độ dày phân tách để đưa ra kết luận mức độ bệnh lý lâm sàng thông qua phương trình tuyến tính tổng hợp:
$$\text{combined\_score} = \text{effusion\_score} \times 0.6 + \text{synovium\_score} \times 0.4$$
Dựa trên kết quả giá trị của biến số $\text{combined\_score}$, hệ thống tự động phân cấp thành 4 ngưỡng trạng thái lâm sàng tương ứng:
* **Mức 0 - Rất nhẹ ($\text{score} < 3$):** Trạng thái ổ dịch khớp và cấu trúc màng hoạt dịch nằm hoàn toàn trong giới hạn sinh lý bình thường của cơ thể.
* **Mức 1 - Nhẹ ($\text{score}$ từ $3$ đến $7.9$):** Xuất hiện hiện tượng tụ dịch khớp lớp mỏng, màng hoạt dịch có dấu hiệu tăng sinh nhẹ cấu trúc màng.
* **Mức 2 - Trung bình ($\text{score}$ từ $8$ đến $15$):** Lượng dịch tụ khớp gối ở mức độ vừa phải, màng hoạt dịch bắt đầu phì đại và tăng sinh rõ nét.
* **Mức 3 - Nặng ($\text{score} > 15$):** Lớp tụ dịch khớp gối dày kích thước lớn, màng hoạt dịch tăng sinh phì đại mạnh, lan rộng diện tích cấu trúc giải phẫu xung quanh.

267
workspace/sprint_1_2/Design_Material/LEGACY/VKIST_ML/docs/PILOT_TECH_DESC.md Normal file
View File

@@ -0,0 +1,267 @@
Dưới đây là toàn bộ nội dung tài liệu về **Công nghệ siêu âm khớp gối (PILOT)** đã được làm sạch, đồng bộ hóa cấu trúc và làm giàu thông tin (enrichment). Các hình ảnh mất mát và sơ đồ quy trình đã được mã hóa chi tiết bằng ngôn ngữ **PlantUML** cùng với các mô tả dữ liệu cấu trúc trực quan nhằm phục vụ tối ưu cho việc huấn luyện, tích hợp hoặc phát triển hệ thống backend của kỹ sư AI/ML stack.
---
# CÔNG NGHỆ SIÊU ÂM KHỚP GỐI (PILOT)
**Tác giả:** Nguyễn Đăng Hà
**Đơn vị phát triển:** VKIST (Viện Khoa học và Công nghệ Việt Nam - Hàn Quốc)
---
## 1. Giới thiệu chung & Mục tiêu nghiên cứu
### Giới thiệu chung
* Tràn dịch khớp gối là một trong những biểu hiện lâm sàng xuất hiện thường gặp của các bệnh lý liên quan đến cơ - xương - khớp.
* Việc nhận diện chính xác và đánh giá chi tiết mức độ viêm khớp gối có ý nghĩa vô cùng quan trọng đối với quá trình điều trị cũng như phục hồi chức năng của bệnh nhân.
* Hiện nay, phương pháp siêu âm được xem là giải pháp hiệu quả hàng đầu để đánh giá tình trạng này nhờ vào các đặc tính: an toàn, hoàn toàn không xâm lấn và tiết kiệm tối đa chi phí cho người bệnh.
### Mục tiêu nghiên cứu của dự án
1. Xây dựng một quy trình chuẩn hóa trong siêu âm chẩn đoán và thiết lập một cơ sở dữ liệu hình ảnh lớn (Large Dataset) chuyên biệt về tràn dịch khớp gối.
2. Nghiên cứu và phát triển phần mềm ứng dụng Trí tuệ nhân tạo (AI) giúp hỗ trợ các bác sĩ lâm sàng chẩn đoán nhanh chóng, hiệu quả tình trạng tràn dịch khớp gối.
3. Tiến hành thử nghiệm lâm sàng, kiểm thử và đánh giá độ chính xác của thuật toán AI trên các tập dữ liệu thực tế thu thập tại Bệnh viện E.
---
## 2. Quy trình xử lý dữ liệu và Kiến trúc hệ thống (Pipeline AI)
Hệ thống xử lý ảnh siêu âm được thiết kế theo một chuỗi pipeline tuần tự từ ảnh thô (Raw Image) đầu vào cho đến khi kết xuất báo cáo định lượng. Dưới đây là sơ đồ kiến trúc luồng dữ liệu của hệ thống:
```plantuml
@startuml
skinparam handwritten false
skinparam monochrome false
skinparam packageStyle rect
skinparam shadowing true
title SƠ ĐỒ PIPELINE XỬ LÝ ẢNH SIÊU ÂM KHỚP GỐI (AI BACKEND)
start
:Ảnh siêu âm đầu gối thô (Raw Image Input);
note right: Tải lên từ client thông qua Web UI
partition "Khối Tiền Xử Lý (Preprocessing Block)" {
:Tiền xử lý dữ liệu ảnh siêu âm;
note right: Chuẩn hóa kích thước, lọc nhiễu, cân bằng độ tương phản
}
partition "Khối Phân Loại (Classification Block)" {
:Phân loại góc chụp (Scan View Classification);
note right: Nhận diện mặt cắt: L SUPRAPAT LONG, L POST TRANS, vv.
}
partition "Khối Nhận Diện & Phân Đoạn (Detection & Segmentation Block)" {
:Nhận biết tình trạng viêm;
if (Phát hiện thấy có viêm?) then (Có viêm)
:Khoanh vùng viêm (Lesion Segmentation);
note right: Sử dụng các mô hình: DeepLabV3, MedSAM, UltraSAM
else (Không viêm)
:Kết luận: Bình thường;
detach
endif
}
partition "Khối Định Lượng & Phân Tích (Quantitative Analytics Block)" {
:Phân tích mức độ viêm;
note right: Tính toán diện tích vùng viêm,\ntỷ lệ phần trăm pixel viêm, quan hệ không gian với mô gân
}
:Kết xuất kết quả (Output Analytics & Report);
note right: Trả về file JSON kết quả, ảnh phân đoạn \nvà lưu trữ vào cơ sở dữ liệu hệ thống
stop
@enduml
```
---
## 3. Các Mô hình Deep Learning áp dụng trong hệ thống
Mô hình AI được chia tách thành ba nhiệm vụ chính: Phân loại mặt cắt ảnh siêu âm, Phát hiện viêm (biến cố cố định) và Phân đoạn ngữ nghĩa (Semantic Segmentation) các vùng giải phẫu tổn thương.
### 3.1. Mô hình Phân loại Góc chụp (Scan View Classification - `angle_model`)
* **Nhiệm vụ:** Tự động nhận diện và phân loại cấu trúc tư thế đặt đầu dò siêu âm.
* **Mô hình mặc định:** `convnext`
* **Các kiến trúc hỗ trợ:**
* **ConvNeXt Tiny:** Cấu hình gồm 4 lớp đầu ra (Mặc định).
* **DenseNet-121:** Trích xuất đặc trưng sâu nhờ cơ chế kết nối dày đặc.
* **ResNet-50:** Kiến trúc mạng phần dư chuẩn hóa giúp tối ưu hóa quá trình hội tụ.
* **EfficientNet-B2:** Cân bằng tối ưu giữa hiệu năng và tài nguyên tính toán.
* **Swin Transformer V2-S:** Mô hình dựa trên cơ chế Attention dịch chuyển cửa sổ, nâng cao khả năng học đặc trưng toàn cục.
* **Các mặt cắt mục tiêu chính:**
* `L SUPRAPAT LONG` (Mặt cắt dọc trên xương bánh chè khớp gối trái).
* `L POST TRANS` (Mặt cắt ngang phía sau khớp gối trái).
### 3.2. Mô hình Phát hiện Viêm (Inflammation Detection - `inflammation_model`)
* **Nhiệm vụ:** Tự động phát hiện và đánh giá tình trạng viêm (hiện cố định trong hệ thống).
* **Mô hình mặc định:** `efficientnet_b0`
### 3.3. Mô hình Khoanh vùng & Phân đoạn tổn thương (Segmentation Models)
Hệ thống cho phép tùy chọn linh hoạt các kiến trúc mạng tiên tiến nhằm khoanh vùng chính xác các cấu trúc giải phẫu và ổ viêm theo từng nhóm góc chụp:
#### 3.3.1. Nhóm Phân đoạn SUP (Mặt cắt dọc trên xương bánh chè - `segment_model_sup`)
| Tên Mô Hình (Giá trị truyền vào) | Kiến trúc kĩ thuật & Vai trò trong hệ thống |
| --- | --- |
| **deeplabv3** | Kiến trúc DeepLabV3 ResNet-50 — 7 lớp (Mặc định). Phân đoạn phân cấp chuẩn giúp nhận diện ranh giới vùng mô mềm phức tạp. |
| **unet_resnet101** | Kiến trúc UNet kết hợp với encoder ResNet-101 mạnh mẽ, tối ưu việc khôi phục chi tiết không gian ảnh. |
| **efficientfeedback** | Kiến trúc EfficientFeedbackNetwork (tùy chỉnh), tăng cường cơ chế phản hồi đặc trưng để làm mịn biên tổn thương. |
| **unet3plus** | Kiến trúc UNet3+ kết hợp cơ chế Attention (tùy chỉnh), tối ưu khả năng kết nối bỏ qua full-scale cho ảnh siêu âm. |
#### 3.3.2. Nhóm Phân đoạn POST (Mặt cắt ngang phía sau - `segment_model_post`)
| Tên Mô Hình (Giá trị truyền vào) | Kiến trúc kĩ thuật & Vai trò trong hệ thống |
| --- | --- |
| **deeplabv3_resnet101** | Kiến trúc DeepLabV3 ResNet-101 — 7 lớp (Mặc định). Chuyên biệt cho việc phân đoạn góc post-trans, tối ưu hóa độ chính xác biên tổn thương vùng khoeo sau gối. |
*(Lưu ý: Các mô hình MedSAM và UltraSAM không xuất hiện trong danh mục cấu hình kỹ thuật của phiên bản Pilot 2025 này, nên đã được thay thế bằng các mô hình thực tế hệ thống đang hỗ trợ bao gồm UNet và EfficientFeedback).*
### 3.3. Cơ chế phân tích định lượng mức độ viêm (Severity Analytics)
Sau khi mô hình phân đoạn (ví dụ: DeepLabV3) đưa ra mặt nạ phân đoạn (Segmentation Mask) , hệ thống thực hiện thuật toán đếm pixel để đưa ra báo cáo tự động:
* **Phân cấp độ viêm:** Hệ thống tự động phân loại thành 3 mức độ từ nhẹ đến nặng bao gồm: **Viêm mức 1**, **Viêm mức 2**, và **Viêm mức 3** (Nặng).
* **Các chỉ số định lượng đầu ra (Output Metrics):**
* **Tỷ lệ vùng viêm:** $\text{Tỷ lệ \%} = \frac{\text{Tổng số pixel vùng viêm}}{\text{Tổng số pixel của toàn bộ ảnh}} \times 100\%$.
* **Phân tích quan hệ không gian (Spatial/Boundary Analysis):** Xác định vị trí tương quan của ổ viêm với các cấu trúc giải phẫu lân cận như: Vùng mô mỡ (`Fat`), Vùng gân (`Tendon`), Xương đùi (`Femur`).
* *Ví dụ phân tích hệ thống:* "Vùng viêm nằm giữa vùng gân chiếm tỷ lệ $14.4\%$ vùng xung quanh".
---
## 4. Đặc tả chức năng của Phần mềm Web (Web UI/UX Specification)
Phần mềm được xây dựng dưới dạng ứng dụng Web tích hợp (Integrated Ultrasound Analytics Platform) sở hữu các chức năng cụ thể sau:
* **Tải lên ảnh đầu vào:** Giao diện hỗ trợ Kéo & thả ảnh siêu âm trực tiếp hoặc nút chọn file ảnh từ máy tính.
* **Tiền xử lý tự động:** Tự động chuẩn hóa ảnh, khử nhiễu đầu vào.
* **Nhận diện tự động:** Xác định góc chụp/mặt cắt ảnh tự động thông qua khối phân loại.
* **Phân đoạn thông minh:** Tự động định vị, khoanh vùng tổn thương viêm bằng màu trực quan đè lên ảnh gốc (Overlay Mask).
* **Định lượng đa chỉ số:** Trả về độ tin cậy của mô hình ($\%$ Confidence), phân loại mức độ nặng, tính toán diện tích pixel tổn thương.
* **Tương tác lâm sàng:** Cho phép bác sĩ nhập ghi chú, nhận xét và các khuyến nghị điều trị trực tiếp trên giao diện.
* **Lưu trữ & Kết xuất:** Lưu trữ kết quả phân tích vào DB và cho phép xuất báo cáo, tải ảnh phân đoạn về máy.
---
## 5. Kết quả thử nghiệm dữ liệu thực tế tại Bệnh viện E
Hệ thống đã được đánh giá chéo giữa kết luận tự động của mô hình AI và chẩn đoán lâm sàng thực tế của các bác sĩ chuyên khoa tại Bệnh viện E mang lại kết quả có độ tương quan rất cao:
Bảng so sánh dữ liệu thử nghiệm thực tế 1
### Bảng 1: So sánh dữ liệu thử nghiệm thực tế 1
| Tiêu chí | Kết luận tự động từ AI | Kết luận lâm sàng của Bác sĩ |
| :--- | :--- | :--- |
| **Ca bệnh 1** | - Phân loại: **Có viêm**<br>- Độ tin cậy: **94.5%**<br>- Mức độ: **Nặng**<br>- Tỷ lệ diện tích viêm: **6.95%**<br>- Mô tả không gian: Vùng viêm lan rộng, nằm giữa vùng gân (chiếm 37.2% vùng xung quanh). | **Khớp gối phải:** Màng hoạt dịch dày, có dịch kích thước ~6.8mm, xuất hiện gai xương nhỏ khe đùi chày trong ngoài khớp.<br><br>**Khớp gối trái:** Màng hoạt dịch dày, có dịch ~11mm (dịch đồng nhất).<br><br>**KẾT LUẬN:** Viêm màng hoạt dịch, tràn dịch khớp gối hai bên kèm thoái hóa khớp gối hai bên. |
| **Ca bệnh 2** | - Phân loại: **Có viêm**<br>- Độ tin cậy: **95.1%**<br>- Mức độ: **Nặng**<br>- Tỷ lệ diện tích viêm: **7.54%**<br>- Mô tả không gian: Vùng viêm lan rộng, nằm giữa vùng gân (chiếm 12.4% vùng xung quanh). | (Đồng nhất dữ liệu chẩn đoán lâm sàng tương tự ca bệnh 1 cho thấy độ tương quan cao về mặt định lượng của mô hình đối với các ca tràn dịch mức độ nặng). |
---
### Bảng 2: So sánh dữ liệu thử nghiệm thực tế 2
| Tiêu chí | Kết luận tự động từ AI | Kết luận lâm sàng của Bác sĩ |
| :--- | :--- | :--- |
| **Đánh giá Khớp Gối Phải** | - Trạng thái: **Có viêm**<br>- Độ tin cậy: **86.5%**<br>- Mức độ: **Nặng**<br>- Tỷ lệ vùng viêm: **6.77%**<br>- Vùng viêm nằm giữa vùng gân (24.6% vùng bao quanh). | - Màng hoạt dịch dày, có dịch kích thước **10mm** (tính chất dịch đồng nhất).<br>- Xuất hiện gai xương tại vị trí khe đùi chày ngoài khớp.<br>- Bề mặt sụn khớp đều, tuy nhiên cấu trúc âm không đồng nhất.<br>- Không có hình ảnh kén khoeo. |
| **Đánh giá Khớp Gối Trái** | - Trạng thái: **Có viêm**<br>- Độ tin cậy: **91.7%**<br>- Mức độ: **Nặng**<br>- Tỷ lệ vùng viêm: **15.96%**<br>- Vùng viêm nằm giữa vùng gân (30.5% vùng bao quanh). | - Màng hoạt dịch dày, ghi nhận có ít dịch.<br>- Xuất hiện gai xương tại khe đùi chày trong ngoài khớp.<br>- Bề mặt sụn khớp đều, cấu trúc âm không đồng nhất.<br>- Không có hình ảnh kén khoeo. |
| **KẾT LUẬN CHUNG** | *(AI hỗ trợ định lượng diện tích tổn thương chuyên sâu)* | **Hình ảnh:** Viêm màng hoạt dịch khớp gối hai bên, Tràn dịch khớp gối phải kèm theo Thoái hóa khớp gối hai bên. |
## 6. Hướng dẫn cài đặt và Triển khai mã nguồn Backend (ML Stack Deployment)
Dành cho coding agent vận hành hoặc deploy môi trường ứng dụng:
### 6.1. Yêu cầu hệ thống (Prerequisites)
* **Hệ điều hành hỗ trợ:** Ubuntu / Windows.
* **Trình quản lý gói:** Anaconda / Miniconda.
* **Hỗ trợ phần cứng:** CUDA Toolkit được cài đặt sẵn (Bắt buộc nếu cấu hình sử dụng GPU tăng tốc suy luận).
### 6.2. Các bước triển khai chi tiết
**Bước 1: Tải mã nguồn từ kho lưu trữ (Git Clone)**
```bash
# Thực hiện clone thư mục chứa dự án từ Git Server hệ thống
git clone https://vkist-hub.com/itvkist/vkist-ultrasound.git
# Di chuyển vào thư mục và cập nhật nếu đã tồn tại phiên bản trước đó
cd vkist-ultrasound
git pull
```
**Bước 2: Khởi tạo môi trường ảo và Cài đặt các thư viện phụ thuộc**
```bash
# Tạo môi trường ảo conda mới chạy Python phiên bản ổn định 3.10
conda create -n vkist-ultrasound python=3.10 -y
# Kích hoạt môi trường ảo vừa tạo
conda activate vkist-ultrasound
# Tiến hành cài đặt tất cả các dependencies phụ thuộc nằm trong file requirements
pip install -r requirements.txt
```
**Bước 3: Khởi chạy ứng dụng Web Server Backend**
```bash
# Chạy file khởi tạo ứng dụng chính
python app.py
```
>
> **Thông tin triển khai thành công:** Sau khi dòng lệnh thực thi hoàn tất, phần mềm cục bộ sẽ khởi chạy và lắng nghe kết nối tại địa chỉ URL mặc định: `http://localhost:8000`.
>
>

256
workspace/sprint_1_2/Design_Material/LEGACY/VKIST_ML/docs/VKIST_ULTRASOUND_INTRODUCE_SPEC.md Normal file
View File

@@ -0,0 +1,256 @@
# VKIST ULTRASOUND - TÀI LIỆU HƯỚNG DẪN & GIỚI THIỆU DỰ ÁN
---
## 1. Giới thiệu chung
VKIST Ultrasound là hệ thống hỗ trợ chẩn đoán viêm khớp gối tiên tiến ứng dụng Trí tuệ nhân tạo (AI). Hệ thống giúp bác sĩ phân tích hình ảnh siêu âm một cách tự động, từ việc nhận diện chính xác góc chụp đến việc đo đạc các chỉ số bệnh lý phức tạp. Qua đó, giải pháp này giúp tối ưu hóa quy trình khám chữa bệnh, giảm thiểu sai sót chủ quan và nâng cao hiệu suất làm việc tại các cơ sở y tế.
---
## 2. Quy trình xử lý toàn diện (AI Pipeline Workflow)
Hệ thống vận hành theo một quy trình khép kín, tự động phân nhánh logic dựa trên tính chất hình ảnh đầu vào:
1. **Tiếp nhận & Tiền xử lý ảnh:** Tải ảnh siêu âm thô lên hệ thống. AI tự động áp dụng thuật toán tăng cường tương phản CLAHE để làm rõ nét các cấu trúc giải phẫu bị mờ hoặc nhiễu.
2. **Phân loại góc chụp (Angle Classification):** Tự động xác định tư thế chụp/mặt cắt nhằm kích hoạt nhánh pipeline phân tích chuyên biệt.
3. **Phát hiện Viêm (Inflammation Detection):** Đánh giá sơ bộ sự hiện diện của dịch khớp hoặc tình trạng tăng sinh màng hoạt dịch.
4. **Phân vùng & Đo đạc (Segmentation & Measurement):** Tách biệt các lớp mô giải phẫu (xương, dịch, màng, gân...) và tự động xác định độ dày tổn thương tại các vùng trọng yếu.
5. **Đánh giá mức độ nặng (Severity Scoring):** Tính toán chỉ số tổng hợp để phân cấp mức độ viêm khớp.
6. **Quản lý hồ sơ & Báo cáo:** Lưu trữ dữ liệu chuẩn hóa vào hệ thống nội bộ và kết xuất phiếu kết quả khám bệnh dạng PDF.
Dưới đây là sơ đồ luồng logic của hệ thống được thiết kế bằng **PlantUML** giúp lập trình viên backend dễ dàng triển khai:
```plantuml
@startuml
skinparam handwritten false
skinparam monochrome false
skinparam packageStyle rect
skinparam shadowing true
title SƠ ĐỒ ĐIỀU HƯỚNG LOGIC PIPELINE - VKIST ULTRASOUND AI
start
:Tiếp nhận ảnh siêu âm từ Web UI;
:Áp dụng thuật toán tiền xử lý CLAHE (Tăng cường độ nét);
:Mô hình Phân loại góc chụp (Angle Model);
note right: Tích hợp ConvNeXt / Swin / DenseNet
if (Góc chụp hợp lệ?) then (Không thuộc góc Sup_up_long / Post_trans)
:Hiển thị nhãn góc chụp (ví dụ: Med-Lat Long);
:Thông báo lỗi: Góc chụp đầu vào không hỗ trợ xử lý tiếp;
stop
else (Hợp lệ)
:Mô hình Phát hiện viêm (EfficientNet-B0);
if (Trạng thái ổ khớp?) then (Không viêm)
:Hiển thị trạng thái KHÔNG VIÊM trên giao diện;
:Cho phép nhập thông tin và lưu trữ cơ bản;
else (Có viêm)
:Hiển thị trạng thái CÓ VIÊM;
if (Góc chụp phát hiện?) then (Post_trans)
:Chạy phân đoạn vùng tổn thương (DeepLabV3-ResNet101);
:Khoanh vùng, gắn nhãn màu Nang Baker (Baker's Cyst);
else (Sup_up_long / Suprapat)
:Chạy phân đoạn vùng tổn thương (DeepLabV3-ResNet50);
partition "Thuật toán Đo đạc thông minh" {
:Smart ROI (Tập trung 1/3 khu vực giữa);
:Continuous Segment Search (Tìm đoạn dịch liên tục dài nhất);
:Xác định độ dày ổ dịch/màng hoạt dịch (mm);
}
:Tính điểm toán học phân cấp Mức độ bệnh (Cấp 0 -> 3);
endif
fi
endif
split
:Nhập thông tin bệnh nhân & Chẩn đoán lâm sàng;
:Lưu trữ cấu trúc thư mục nội bộ (patients/);
split again
:Xuất phiếu kết quả khám bệnh dạng PDF (report.pdf);
end split
stop
@enduml
```
---
## 3. Các Tính năng Chi tiết & Mô hình học máy
### 3.1. Hệ thống Mô hình AI Đa dạng (Multi-Model Architecture)
* **Khối Phân loại Góc chụp:** Tích hợp các kiến trúc mạng mạng nơ-ron tiên tiến (SOTA) bao gồm ConvNeXt-Tiny (đạt độ chính xác tuyệt đối 100% trên tập kiểm thử) , Swin Transformer, và DenseNet. Hệ thống mặc định sử dụng ConvNeXt làm lõi phân loại chính đầu tiên cho mọi ảnh.
* **Khối Phân vùng (Semantic Segmentation):** Hỗ trợ linh hoạt các mô hình DeepLabV3+ (hoặc DeepLabV3-ResNet50 với độ chính xác 91.67%), UNet3+ Attention, và EfficientFeedback. Các cấu trúc này được tối ưu hóa sâu nhằm nhận diện chính xác đường biên ranh giới màng hoạt dịch phức tạp.
### 3.2. Tính năng Đo đạc Thông minh (Smart Measurement)
Nhánh xử lý góc `Sup_up_long` tích hợp hai thuật toán hình học độc quyền nhằm loại bỏ sai số đo đạc:
* **Smart ROI:** Hệ thống tự động khoanh vùng và tập trung phân tích vào khu vực 1/3 chính giữa của vùng nghi ngờ, nơi có giá trị và chỉ số chẩn đoán lâm sàng cao nhất.
* **Continuous Segment Search:** Thuật toán tự động tìm kiếm đoạn mặt nạ (mask) liên tục dài nhất. Cơ chế này đảm bảo kết quả tính toán độ dày của màng và dịch khớp phản ánh đúng thực tế, khách quan và không bị ảnh hưởng bởi nhiễu ảnh cục bộ.
### 3.3. Phân cấp Mức độ Bệnh (Severity Classification)
Hệ thống tính toán chỉ số kết hợp giữa diện tích dịch khớp tụ và mức độ tăng sinh màng hoạt dịch để phân định thành 4 cấp độ bệnh lý rõ ràng:
| Cấp độ viêm | Phân loại lâm sàng | Đặc điểm cấu trúc hình ảnh siêu âm |
| --- | --- | --- |
| **Cấp 0** | Rất nhẹ | Lượng dịch khớp nằm trong giới hạn sinh lý bình thường.|
| **Cấp 1** | Nhẹ | Lớp dịch khớp mỏng, xuất hiện tăng sinh màng hoạt dịch mức độ nhẹ.|
| **Cấp 2** | Trung bình | Lượng dịch khớp và màng hoạt dịch tăng sinh phì đại rõ rệt.|
| **Cấp 3** | Nặng | Ổ dịch khớp dày, màng hoạt dịch phát triển mạnh và xâm lấn sâu.|
---
## 4. Đặc tả Giao diện & Hướng dẫn Vận hành Hệ thống
Giao diện Web UI của ứng dụng được thiết kế phân cấp tối giản theo bố cục 3 luồng dọc: **Bảng trái (Cấu hình Mô hình)** $\rightarrow$ **Bảng giữa (Tải ảnh & Hiển thị)** $\rightarrow$ **Bảng phải (Nhập dữ liệu & Xem kết quả phân tích)**.
### Quy trình vận hành 4 bước dành cho Bác sĩ:
#### Bước 1: Cấu hình Mô hình AI (Left Panel)
* Trước khi tiến hành tải ảnh siêu âm, bác sĩ có thể linh hoạt tùy chọn thuật toán AI mong muốn cho từng block tác vụ tại bảng điều khiển bên trái. Hệ thống đã được cấu hình mặc định sẵn các mô hình tối ưu nhất.
#### Bước 2: Tải ảnh siêu âm lên hệ thống (Middle Panel)
* Bác sĩ thực hiện kéo thả tập tin ảnh trực tiếp vào vùng nhận diện hoặc nhấn nút `"Chọn ảnh"`.
* Ngay sau khi tệp tin được nạp, hệ thống sẽ tự động kích hoạt toàn bộ Pipeline phân tích ngầm theo luồng xử lý tự động.
#### Bước 3: Đọc kết quả phân tích tự động từ AI (Right Panel & Modal Popup)
Hệ thống tự động hiển thị kết quả trực quan dựa trên nhãn mặt cắt nhận diện được:
*
**Trường hợp góc chụp không hỗ trợ (ví dụ: `Med-Lat Long`):** Hệ thống lập tức xuất nhãn cảnh báo màu tím `"GÓC CHỤP: Med-Lat Long"` và dừng tiến trình xử lý tiếp theo.
*
**Trường hợp góc mặt sau `Post_trans`:** Hệ thống kiểm tra tình trạng viêm. Nếu có viêm, ảnh phân đoạn sẽ hiển thị màu overlay trực quan khoanh vùng chính xác ổ tổn thương **Nang Baker** (Baker's cyst) kèm bảng chú thích màu sắc mô giải phẫu tương ứng.
*
**Trường hợp góc mặt trước `Sup_up_long`:** Hệ thống tiến hành phân đoạn, hiển thị đường lưới đo đạc thông minh. Đồng thời tính toán chi tiết độ dày ổ dịch bằng đơn vị milimét ($mm$) và đưa ra chẩn đoán mức độ viêm chính xác.
#### Bước 4: Lưu trữ hồ sơ dữ liệu & Xuất bản phiếu khám lâm sàng
* Bác sĩ thực hiện điền đầy đủ thông tin vào form biểu mẫu bệnh nhân ở bảng bên phải (Trong đó hai trường dữ liệu **Mã bệnh nhân** và **Họ và tên** là bắt buộc). Ghi nhận thêm nhận xét lâm sàng cá nhân vào ô "Chẩn đoán của bác sĩ".
* Nhấn nút `"Lưu dữ liệu"` để hệ thống đóng gói và lưu trữ nội bộ vào máy chủ.
* Nhấn nút `"Xuất phiếu khám (PDF)"` để tải về máy mẫu phiếu in kết quả y khoa chính thức trả cho bệnh nhân.
---
## 5. Đặc tả Kiến trúc Lưu trữ Dữ liệu Đầu ra
### 5.1. Cấu trúc cây thư mục lưu trữ hồ sơ bệnh nhân (Storage Structure)
Khi bác sĩ nhấn chọn chức năng lưu trữ dữ liệu , hệ thống tự động khởi tạo cấu trúc thư mục phân cấp động theo mốc thời gian thực tại phân vùng `patients/` nhằm tránh trùng lặp thông tin:
```text
patients/
└── <Mã_Bệnh_Nhân>_<Họ_Và_Tên_Không_Dấu>/
└── <NamThangNgay>_<GioPhutGiay>/
├── info.txt # Tệp tin cấu trúc lưu trữ siêu dữ liệu định lượng của ca bệnh
├── original.png # File hình ảnh siêu âm gốc (hoặc ảnh đã tăng cường CLAHE)
├── segmented.png # File ảnh overlay mặt nạ phân đoạn màu từ AI mô hình
└── report.pdf # File phiếu kết quả chẩn đoán y khoa chính thức xuất cho bệnh nhân
```
*Ví dụ thực tế:* `patients\BN0001_Nguyen_Van_A\20260505_170011\`
### 5.2. Định dạng cấu trúc tệp dữ liệu `info.txt`
Tệp tin `info.txt` đóng vai trò lưu trữ toàn bộ thông tin tối giản, giúp hệ thống hoặc các agent xử lý số liệu có thể dễ dàng phân tích (parse) dữ liệu mà không cần đọc file PDF:
```text
--- THÔNG TIN BỆNH NHÂN ---
Mã bệnh nhân: BN0001
Họ tên: Nguyễn Văn A
Giới tính: Nam
Tuổi: 88
Ghi chú lâm sàng: Tràn dịch và có thể viêm
--- KẾT QUẢ PHÂN TÍCH AI ---
Góc chụp: sup-up-long (99.93%)
Viêm nhiễm: Có (94.44%)
Độ dày màng: 6.53 mm (95 px)
Vị trí x: 420
Mức độ: Trung bình
Mô tả: Dịch khớp trung bình (51px), màng hoạt dịch tăng sinh vừa
```
(Ghi chú: Nội dung trên được ánh xạ chính xác từ các chỉ số định lượng thu được qua mô hình phân đoạn hình học của hệ thống ).
### 5.3. Quy chuẩn nội dung phiếu kết quả y khoa `report.pdf`
Phiếu kết quả chẩn đoán hình ảnh dạng PDF được tạo tự động với cấu trúc bố cục chuẩn hóa y tế gồm 4 phần chính:
1.
**Thông tin Cơ sở & Tiêu đề:** Biểu trưng nhận diện VKIST, tên "TRUNG TÂM CHẨN ĐOÁN HÌNH ẢNH VKIST", địa chỉ "Khu Công nghệ cao Hòa Lạc, Thạch Thất, Hà Nội" kèm tiêu đề lớn **"PHIẾU KẾT QUẢ SIÊU ÂM KHỚP GỐI"**.
2. I. Thông tin bệnh nhân: Hiển thị chi tiết Họ tên, Giới tính, Mã BN, Tuổi của người bệnh.
3. II. Hình ảnh siêu âm: Chèn song song hai khung hình trực quan bao gồm `Hình 1: Ảnh gốc / Tăng cường` và `Hình 2: Ảnh phân đoạn AI` (có kèm sơ đồ lưới đo đạc và chú thích màu).
4. **III. Kết quả phân tích tự động (AI Metric):**
* Góc chụp dự đoán đạt tỷ lệ tương ứng (Ví dụ: `sup-up-long` - Độ tin cậy: `99.93%`).
* Tình trạng viêm ổ khớp (Ví dụ: `Có khả năng viêm` - Độ tin cậy: `94.44%`).
* Chỉ số đo đạc vật lý: Độ dày dịch & màng hoạt dịch tính toán được đạt mức `6.53 mm`.
* Đánh giá mức độ viêm tổng hợp: `Trung bình`.
* Chi tiết mô tả định lượng: Dịch khớp trung bình ($51\text{ px}$), màng hoạt dịch tăng sinh vừa ($95\text{ px}$).
5. IV. Chẩn đoán và kết luận của Bác sĩ: Trích xuất nguyên vẹn nội dung ghi chú lâm sàng do bác sĩ trực tiếp nhập vào hệ thống (Ví dụ: `"Tràn dịch và có thể viêm"`).

11
workspace/sprint_1_2/Design_Material/LEGACY/VKIST_ML/docs/arch_code_analysis.md Normal file
View File

@@ -0,0 +1,11 @@
# ML Model Architecture Report
| File | Architectures (code ranges) |
|------|-----------------------------|
| `ML/arch/unet3plus_att.py` | - **UNet3Plus_Attention** (87‑268)<br> &nbsp;&nbsp;- SelfAttention (7‑25)<br> &nbsp;&nbsp;- AttentionGate (28‑66)<br> &nbsp;&nbsp;- conv_block (69‑83) |
| `ML/arch/efficientfeedback.py` | - **EfficientFeedbackNetwork** (171‑239)<br> &nbsp;&nbsp;- convblock (9‑14)<br> &nbsp;&nbsp;- DecoderBlock (17‑35)<br> &nbsp;&nbsp;- ASPP_module (37‑66)<br> &nbsp;&nbsp;- CAM_Module (68‑86)<br> &nbsp;&nbsp;- S_Module (93‑131)<br> &nbsp;&nbsp;- FeedbackSpatialAttention (134‑151)<br> &nbsp;&nbsp;- StageAttentionwCAM (153‑168) |
| `ML/segment_anything/modeling/image_encoder.py` | - **ImageEncoderViT** (18‑119)<br> &nbsp;&nbsp;- PatchEmbed (389‑420)<br> &nbsp;&nbsp;- Block (122‑187)<br> &nbsp;&nbsp;- Attention (190‑254) |
| `ML/segment_anything/modeling/prompt_encoder.py` | - **PromptEncoder** (17‑181)<br> &nbsp;&nbsp;- PositionEmbeddingRandom (183‑226) |
| `ML/segment_anything/modeling/mask_decoder.py` | - **MaskDecoder** (17‑190)<br> &nbsp;&nbsp;- MLP (168‑190) |
| `ML/segment_anything/modeling/transformer.py` | - **TwoWayTransformer** (17‑108)<br> &nbsp;&nbsp;- TwoWayAttentionBlock (110‑183)<br> &nbsp;&nbsp;- Attention (186‑243) |
| `ML/segment_anything/modeling/sam.py` | - **Sam** (19‑181) *(no internal sub‑architectures; uses imported modules)* |

46
workspace/sprint_1_2/Design_Material/codebase/backend/spec/backend-spec.md Normal file
View File

@@ -0,0 +1,46 @@
# Backend Specification
## Purpose
Orchestrates API routers, role checks, Socratic circuit-breaker state evaluations, and coordinates ML inference, telemetry collection, and data persistence.
## Owner
Core Backend Team
## Boundary
FastAPI server, API routers, authentication middleware, circuit breaker engine, report generator, RAG coordinator, ledger logger, and connections to Postgres, S3, Redis, Triton, Qdrant, ladybugDB.
## Internal Design
- Built with FastAPI (Python) and Uvicorn for async HTTP server.
- Authentication middleware validates JWT tokens and enforces RBAC (roles: RO_RADIOLOGIST, RO_THERAPIST).
- Socratic circuit-breaker engine monitors interaction telemetry (hover duration, decision time, override magnitude) and triggers safety dialogs.
- Clinical Report Engine uses ReportLab to generate bilingual PDF reports per Circular 46/2018/TT-BYT.
- RAG Coordinator orchestrates Retrieval-Augmented Generation: dense vector lookup in Qdrant, graph traversal in ladybugDB, prompt enrichment, LLM generation on Triton (PhoGPT/MedGemma), and hallucination guarding.
- Ledger Logger appends immutable, cryptographically chained audit logs to Postgres via triggers preventing UPDATE/DELETE.
- Connections: Postgres (via SQLAlchemy), S3 (via boto3), Redis (via redis-py), Triton (via gRPC), Qdrant (via gRPC/HTTP), ladybugDB (via in-process C++ bindings).
- Model weights loaded at startup from internal registry; cached in memory.
- API endpoints layered: public clinical (sessions, analysis, reports, feedback) and internal/local safety (explanations, safety, drift, RAG, activations, annotations, ground-truth, escalation, morphology, telemetry).
## Interface Contract
See `bento/backend/spec/interface-contract.md`.
## Consumers
- frontend
## Breaking-change Policy
See `bento/backend/spec/interface-contract.md`.
## References
- NFR-7 (Real-Time UI Screen Refresh ≤200ms)
- NFR-10 (Generative Safety Guardrails)
- NFR-11 (Frontline Usability & Training)
- UC-48376 (Load Patient Scan Session)
- UC-47988 (Review Suggested Synovitis Grade)
- UC-25776 (Generate GradCAM & CoT Explanation Panel)
- UC-02423 (Log High-Trust Concur Block)
- UC_Q2_* (All Quadrant 2 safety workflows)
- UC_Q3_* (All Quadrant 3 subservience workflows)
- UC_Q4_* (All Quadrant 4 double-blind workflows)
- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Sections 1.2, 2.1-2.6)
- SOLUTION_ARCHITECTURE_SPEC.md (Sections 2.1-2.6)
- DATA_ENGINEERING_SPEC.md (Sections 4-12 for domain objects)
- CI_CD_DEPLOYMENT_PIPELINE.md (Section 9.2 for docker-compose)

46
workspace/sprint_1_2/Design_Material/codebase/backend/spec/interface-contract.md Normal file
View File

@@ -0,0 +1,46 @@
# Backend Interface Contract
## Purpose
Orchestrates API routers, role checks, Socratic circuit-breaker state evaluations, and coordinates ML inference, telemetry collection, and data persistence.
## Owner
Core Backend Team
## Provides
- api endpoints (session management, frame upload, analysis jobs, reporting, feedback, safety endpoints)
- model inference orchestration (dispatches to Triton, aggregates results)
- telemetry collection (edge-based behavioral summaries, audit logs)
- data persistence coordination (writes to Postgres, S3, Redis)
## Consumes
- data:storage-spec (Postgres DB, S3 object store, Redis cache)
- ml:inference-spec (Triton server for angle, inflammation, segmentation, severity)
- knowledge:guideline-spec (Qdrant vector DB, ladybugDB graph DB for grounded explanations)
## Consumers
- frontend
## Not Directly Consumable
- data internals (Postgres tables, S3 object layout, Redis keys)
- ml internals (Triton model details, GPU kernels)
- knowledge internals (Qdrant vectors, ladybugDB graph)
## Breaking-change Policy
- API versioning via path (e.g., /api/v1/).
- Backward compatibility maintained for one minor version.
- Deprecation notices issued in release notes.
- Model interface changes (input/output tensors) require version bump.
## References
- NFR-7 (Real-Time UI Screen Refresh ≤200ms)
- NFR-10 (Generative Safety Guardrails)
- NFR-11 (Frontline Usability & Training)
- UC-48376 (Load Patient Scan Session)
- UC-47988 (Review Suggested Synovitis Grade)
- UC-25776 (Generate GradCAM & CoT Explanation Panel)
- UC-02423 (Log High-Trust Concur Block)
- UC_Q2_* (All Quadrant 2 safety workflows)
- UC_Q3_* (All Quadrant 3 subservience workflows)
- UC_Q4_* (All Quadrant 4 double-blind workflows)
- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Sections 1.2, 2.1-2.6)
- SOLUTION_ARCHITECTURE_SPEC.md (Sections 2.1-2.6)

52
workspace/sprint_1_2/Design_Material/codebase/data/spec/data-spec.md Normal file
View File

@@ -0,0 +1,52 @@
# Data Model Specification
## Purpose
Manages persistent storage, caching, and object storage for clinical data including patient records, imaging studies, analysis results, and audit trails using PostgreSQL, Redis, and S3 with calibration services.
## Owner
Data / Domain Team
## Boundary
PostgreSQL database clusters, Redis cache instances, S3 buckets/object storage, database connection pools, cache invalidation strategies, and storage lifecycle management policies.
## Internal Design
- PostgreSQL 15 with TimescaleDB extension for temporal data
- Schema organization: patient, study, session, analysis, audit, calibration namespaces
- Connection pooling via PgBouncer for efficient database access
- Redis 7 for session caching, rate limiting, and temporary computation results
- S3 bucket structure: raw-imagery, processed-results, exports, backups with lifecycle policies
- Encryption-at-rest for sensitive data (PHI) using AES-256-GCM
- Automated backups with point-in-time recovery (PITR) capabilities
- Read replicas for query distribution and reporting workloads
- Calibration service: pixel-to-mm conversion factors stored per device/protocol
- Data retention policies: active data (2 years), archived data (7 years), purged data (>7 years)
- Migration system using Flyway for schema versioning
- Monitoring: query performance, connection pool utilization, replication lag
## Interface Contract
See `bento/data/spec/interface-contract.md`.
## Consumers
- backend:api-spec (for CRUD operations on patient/study/session data)
- backend:ledger-spec (for audit trail storage)
- ml:engine-spec (for model weights and training data)
- knowledge:spec (for exporting vectorizable content)
## Breaking-change Policy
- Database schema versioning via semantic versioning aligned with API versions
- Table/column additions: backward compatible (MINOR version)
- Table/column removals or type changes: require MAJOR version with migration path
- API contract changes follow backend interface contract policies
- Data migration scripts provided for breaking changes
- Deprecation notices for schema changes 60 days in advance
## References
- NFR-7 (Data Durability: 99.999999999% annual)
- NFR-8 (Recovery Time Objective ≤4 hours)
- NFR-9 (Storage Cost Efficiency)
- NFR-13 (Audit Trail Immutability)
- UC-48376 (Load Patient Scan Session)
- UC-92006 (Save Analysis Results)
- UC-01580 (Export Study Package)
- SOLUTION_ARCHITECTURE_SPEC.md (Section 2.3)
- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Section 5.2)

51
workspace/sprint_1_2/Design_Material/codebase/data/spec/interface-contract.md Normal file
View File

@@ -0,0 +1,51 @@
# Data Model Interface Contract
## Purpose
Manages persistent storage, caching, and object storage for clinical data including patient records, imaging studies, analysis results, and audit trails using PostgreSQL, Redis, and S3 with calibration services.
## Owner
Data / Domain Team
## Provides
- persistent-storage (ACID-compliant patient/study/session records)
- object-storage (binary imagery, masks, overlays, exported reports)
- caching-layer (session state, rate limiting counters, temp computation results)
- calibration-service (pixel-to-mm conversion factors per device/protocol)
- backup-and-recovery (point-in-time recovery, cross-region replication)
- data-export-functionality (DICOM, PDF, CSV formats)
## Consumes
- (None - foundational storage layer)
## Consumers
- backend:api-spec (patient/study/session CRUD operations, search)
- backend:ledger-spec (audit trail append-only storage)
- ml:engine-spec (model artifacts storage/retrieval, training datasets)
- knowledge:spec (guideline documents, vectorization source material)
- infra:spec (shared PostgreSQL/Redis instances for platform services)
## Not Directly Consumable
- internal table structures beyond published schemas
- connection pool tuning parameters
- Redis key naming conventions for internal caching
- S3 bucket policies beyond published access patterns
- backup encryption key management
- vacuum/analyze maintenance schedules
## Breaking-change Policy
- Database schema versioning via semantic versioning (MAJOR.MINOR.PATCH aligned with API)
- Additive changes (new tables/columns): backward compatible (MINOR version)
- Breaking changes (removed columns, type alterations): require MAJOR version
- Migration scripts provided for all breaking changes with rollback procedures
- Deprecation notices for schema changes issued 90 days in advance
- Storage interface changes (S3 prefixes, Redis keys) follow same versioning
- Consumers must opt-in to breaking changes via feature flags
## References
- NFR-7 (Data Durability: 99.999999999% annual)
- NFR-8 (Recovery Time Objective ≤4 hours)
- NFR-9 (Storage Cost Efficiency)
- NFR-13 (Audit Trail Immutability)
- UC-48376 (Load Patient Scan Session)
- UC-92006 (Save Analysis Results)
- UC-01580 (Export Study Package)

41
workspace/sprint_1_2/Design_Material/codebase/frontend/spec/frontend-spec.md Normal file
View File

@@ -0,0 +1,41 @@
# Frontend Specification
## Purpose
Provides interactive clinical workspace, runs edge models (LiteRT, MediaPipe), handles client-side encryption (WebCrypto), offline sync via IndexedDB/Service Worker, and renders UI viewport with graphics adapter fallback.
## Owner
Web Experience Team
## Boundary
PWA service worker, graphics adapter layer (IGraphicsViewport), local browser storage (IndexedDB), and UI components (React, Zustand).
## Internal Design
- Built as a Single Page Application (SPA) using React with TypeScript.
- State managed via Zustand store.
- Client-side encryption via WebCrypto API (AES-256-GCM) before local storage.
- Offline synchronization via Dexie.js (IndexedDB) and Service Worker that queues actions and retries on reconnection.
- Graphics rendering abstracted via IGraphicsViewport interface with WebGLThreeAdapter (Three.js) and CPUSpriteAdapter fallback.
- Edge ML executed in Web Workers: DICOM parser (cornerstone-core), LiteRT angle classifier (MobileNetV4), MediaPipe ROI pre-cropper.
- UI components render multi-layered canvas, workspace controls, diagnostic ribbons, and explanation panels.
- Communication with backend via HTTPS to NGINX gateway, JWT-based authentication, role-based access control (RBAC).
## Interface Contract
See `bento/frontend/spec/interface-contract.md`.
## Consumers
(None)
## Breaking-change Policy
See `bento/frontend/spec/interface-contract.md`.
## References
- NFR-1 (Collaborative Rendering Speed ≤3s)
- NFR-4 (Client Memory Footprint ≤150MB)
- NFR-14 (Legacy Hardware Compatibility)
- UC-48376 (Load Patient Scan Session)
- UC-47988 (Review Suggested Synovitis Grade)
- UC-25637 (Expose Pixel-Level Activation Logic)
- UC-60739 (Isolate Visual Noise/Artifacts)
- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Sections 2.4, 3.1, 3.2, 3.3)
- SOLUTION_ARCHITECTURE_SPEC.md (Section 2.4)
- PROJECT_VIS.md (Section 3.1, 3.2)

39
workspace/sprint_1_2/Design_Material/codebase/frontend/spec/interface-contract.md Normal file
View File

@@ -0,0 +1,39 @@
# Frontend Interface Contract
## Purpose
Provides interactive clinical workspace, runs edge models (LiteRT, MediaPipe), handles client-side encryption (WebCrypto), offline sync via IndexedDB/Service Worker, and renders UI viewport with graphics adapter fallback.
## Owner
Web Experience Team
## Provides
- ui viewport (interactive canvas, overlays, controls)
- edge ml (angle classification, inflammation detection, ROI pre-cropping)
- offline sync (local cache, sync queue, background synchronization)
## Consumes
- backend:api-spec (REST API endpoints for session, analysis, reporting, feedback)
- knowledge:guideline-spec (GraphRAG pipeline for grounded explanations, evidence arbitration)
## Consumers
(None)
## Not Directly Consumable
- backend internals (e.g., FastAPI route implementations, Triton model details)
- knowledge internals (Qdrant vectors, ladybugDB graph structure)
- data internals (Postgres schema, S3 object layout)
## Breaking-change Policy
- API versioning via path (e.g., /api/v1/).
- Backward compatibility maintained for one minor version.
- Deprecation notices issued in release notes.
- Breaking changes require major version bump.
## References
- NFR-1 (Collaborative Rendering Speed ≤3s)
- NFR-4 (Client Memory Footprint ≤150MB)
- NFR-14 (Legacy Hardware Compatibility)
- UC-48376 (Load Patient Scan Session)
- UC-47988 (Review Suggested Synovitis Grade)
- UC-25637 (Expose Pixel-Level Activation Logic)
- UC-60739 (Isolate Visual Noise/Artifacts)

42
workspace/sprint_1_2/Design_Material/codebase/frontend/subprojects/offline/spec/interface-contract.md Normal file
View File

@@ -0,0 +1,42 @@
# Offline Interface Contract
## Purpose
Provides offline caching and synchronization for the PWA frontend, enabling continued operation during network interruptions and seamless sync upon reconnection.
## Owner
Web Experience Team (same as frontend)
## Parent
frontend
Boundary
IndexedDB database via Dexie.js, Service Worker for background sync, and local queue for offline actions.
## Provides
- offline cache (IndexedDB storage of encrypted patient sessions, DICOM frames, annotation vectors)
- sync queue (Service Worker-intercepted pending actions)
- local persistence (survives browser reloads, network drops)
## Consumes
(None)
## Consumers
- frontend
## Not Directly Consumable
- frontend internals (e.g., React components, Zustand store)
- backend internals
## Breaking-change Policy
- Changes to IndexedDB schema require version migration scripts.
- Sync protocol changes are backward-compatible; old clients can still sync via tombstone markers.
## References
- NFR-8 (Local Network Fault Tolerance)
- NFR-4 (Client Memory Footprint)
- UC-48376 (Load Patient Scan Session)
- UC-47988 (Review Suggested Synovitis Grade)
- UC-25637 (Expose Pixel-Level Activation Logic)
- UC-60739 (Isolate Visual Noise/Artifacts)
- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Section 3.2)
- SOLUTION_ARCHITECTURE_SPEC.md (Section 3.2)

40
workspace/sprint_1_2/Design_Material/codebase/frontend/subprojects/offline/spec/offline-spec.md Normal file
View File

@@ -0,0 +1,40 @@
# Offline Specification
## Purpose
Provides offline caching and synchronization for the PWA frontend, enabling continued operation during network interruptions and seamless sync upon reconnection.
## Owner
Web Experience Team (same as frontend)
## Parent
frontend
Boundary
IndexedDB database via Dexie.js, Service Worker for background sync, and local queue for offline actions.
## Internal Design
- Dexie.js wrapper around IndexedDB with encrypted stores for patient sessions, frames, and annotation layers.
- Service Worker intercepts network requests (fetch, XMLHttpRequest) and caches responses; queues POST/PUT/PATCH actions when offline.
- On reconnection, Service Worker processes queued actions in order, with idempotent retries.
- Data stored in IndexedDB is encrypted via WebCrypto before writing; decrypted on read.
- Schema includes tables: sessions, frames, annotations, audit logs, calibration data.
- Versioning handled via Dexie.js version upgrades with migration scripts.
## Interface Contract
See `bento/frontend/subprojects/offline/spec/interface-contract.md`.
## Consumers
- frontend
## Breaking-change Policy
See `bento/frontend/subprojects/offline/spec/interface-contract.md`.
## References
- NFR-8 (Local Network Fault Tolerance)
- NFR-4 (Client Memory Footprint)
- UC-48376 (Load Patient Scan Session)
- UC-47988 (Review Suggested Synovitis Grade)
- UC-25637 (Expose Pixel-Level Activation Logic)
- UC-60739 (Isolate Visual Noise/Artifacts)
- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Section 3.2)
- SOLUTION_ARCHITECTURE_SPEC.md (Section 3.2)

31
workspace/sprint_1_2/Design_Material/codebase/infra/implementation/cicd/jenkin_run.sh Normal file
View File

@@ -0,0 +1,31 @@
# Install Docker image
docker network create jenkins
# install docker-integratable image
docker run --name jenkins-docker --rm --detach \
-p 8080:8080 -p 50000:50000 \
--restart=on-failure \
--privileged --network jenkins --network-alias docker \
--env DOCKER_TLS_CERTDIR=/certs \
--volume jenkins-docker-certs:/certs/client \
--volume jenkins-data:/var/jenkins_home \
--publish 2376:2376 \
docker:dind --storage-driver overlay2 \
-v jenkins_home:/var/jenkins_home jenkins/jenkins:lts
# install the docker images
docker run \
--name jenkins-blueocean \
--restart=on-failure \
--detach \
--network jenkins \
--env DOCKER_HOST=tcp://docker:2376 \
--env DOCKER_CERT_PATH=/certs/client \
--env DOCKER_TLS_VERIFY=1 \
--publish 8080:8080 \
--publish 50000:50000 \
--volume jenkins-data:/var/jenkins_home \
--volume jenkins-docker-certs:/certs/client:ro \
jenkins/jenkins:lts

16
workspace/sprint_1_2/Design_Material/codebase/infra/implementation/observability/docker-compose.yaml Normal file
View File

@@ -0,0 +1,16 @@
version: '3.8'
services:
prometheus:
image: prom/prometheus:latest
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
ports:
- "9090:9090"
grafana:
image: grafana/grafana:latest
ports:
- "3000:3000"
environment:
- GF_SECURITY_ADMIN_PASSWORD=admin

12
workspace/sprint_1_2/Design_Material/codebase/infra/implementation/observability/prometheus.yml Normal file
View File

@@ -0,0 +1,12 @@
global:
scrape_interval: 30s # Poll every 30 seconds instead of hammering it every 5s
scrape_timeout: 25s # Give it 25 full seconds to respond before timing out
scrape_configs:
- job_name: 'triton'
metrics_path: '/metrics'
scheme: 'https'
tls_config:
insecure_skip_verify: true
static_configs:
- targets: ['dtj-tran--triton-s3-service-unified-triton-server.modal.run']

17
workspace/sprint_1_2/Design_Material/codebase/infra/implementation/s3/angle_classify_convnext_tiny/config.pbtxt Normal file
View File

@@ -0,0 +1,17 @@
name: "angle_classify_convnext_tiny"
platform: "pytorch_libtorch"
max_batch_size: 8
input [
{
name: "input_image"
data_type: TYPE_FP32
dims: [ 3, 224, 224 ]
}
]
output [
{
name: "logits"
data_type: TYPE_FP32
dims: [ 4 ]
}
]

Some files were not shown because too many files have changed in this diff Show More