clqms-fe1/.serena/memories/plans/mvp-roadmap.md

CLQMS MVP Roadmap

Executive Summary

CLQMS (Clinical Laboratory Quality Management System) - A comprehensive laboratory information system for clinical diagnostics.

Current State

• ✅ Authentication & authorization
• ✅ Patient management (CRUD)
• ✅ Visit management with ADT tracking
• ✅ Order entry (create orders with specimens and tests)
• ✅ Master data management (contacts, locations, containers, organization, tests)
• ⚠️ Dashboard (static mock data)
• ❌ Results management (CRITICAL GAP)
• ❌ Report viewing (CRITICAL GAP)

MVP Goal

Enable end-to-end laboratory workflow: Patient → Visit → Order → Results → Report

---

Phase 1: Core Laboratory Workflow (CRITICAL - Weeks 1-3)

1.1 Results Management System

Priority: CRITICAL - Without results, this is not a laboratory system

API Endpoints Available:

• GET /api/results - List results (with filters by order_id, patient_id)
• GET /api/results/{id} - Get single result detail
• PATCH /api/results/{id} - Update result with auto-validation
• DELETE /api/results/{id} - Soft delete result

Features:

1. Results Entry Page

   • View results by order or patient
   • Batch entry mode for efficient data input
   • Auto-validation against reference ranges (L/H flags)
   • Support for different result types: NMRIC, RANGE, TEXT, VSET

2. Results Review & Verification

   • List results pending verification
   • Bulk verify results
   • Critical/high-low flag highlighting

3. Results History

   • Cumulative patient results view
   • Trend charts for numeric results
   • Delta checking (compare with previous results)

UI Components Needed:

• ResultsEntryPage.svelte
• ResultInputModal.svelte (handles different result types)
• ResultsByOrderView.svelte
• ResultsByPatientView.svelte
• CriticalResultsAlert.svelte

API Client:

• src/lib/api/results.js (NEW)

---

1.2 Report Generation & Viewing

Priority: CRITICAL - Final output of laboratory work

API Endpoints Available:

• GET /api/reports/{orderID} - Generate HTML lab report

Features:

1. Report Viewer

   • View HTML reports in browser
   • Print-friendly layout
   • PDF export capability (browser print to PDF)

2. Report Status Tracking

   • Track order status: ORD → SCH → ANA → VER → REV → REP
   • Visual status indicators

UI Components Needed:

• ReportViewerModal.svelte
• ReportPrintView.svelte

---

1.3 Live Dashboard

Priority: HIGH - Replace static data with real metrics

Features:

1. Real-time Metrics

   • Pending orders count (from orders API)
   • Today's results count (from results API)
   • Critical results count (filter results by flag)
   • Active patients count (from patients API)

2. Activity Feed

   • Recent orders created
   • Recent results received
   • Recent patients registered

Implementation:

• Update src/routes/(app)/dashboard/+page.svelte
• Add dashboard API endpoint if needed

---

Phase 2: Order Management Enhancement (Weeks 4-5)

2.1 Order Workflow Management

Priority: HIGH

Features:

1. Order Status Tracking

   • Visual pipeline: Ordered → Scheduled → Analysis → Verified → Reviewed → Reported
   • Bulk status updates

2. Order Details Enhancement

   • View specimens associated with order
   • View test results within order
   • Direct link to results entry from order

API Endpoints:

• POST /api/ordertest/status - Update order status (already available)
• GET /api/ordertest/{id}?include=details - Get order with specimens/tests

---

2.2 Specimen Tracking

Priority: MEDIUM

Features:

1. Specimen Management
   • View specimens by order
   • Update specimen status (collected, received, processed)
   • Print specimen labels

API Endpoints Available:

• GET /api/specimen - List specimens
• GET /api/specimen/{id} - Get specimen details

---

Phase 3: Master Data & Configuration (Week 6)

3.1 Test Management Enhancement

Priority: MEDIUM

Features:

1. Test Catalog Browser
   • Improved search and filtering
   • View test details with reference ranges
   • Test-to-container mappings

Already Implemented:

• Tests CRUD in master-data/tests
• Test mappings in master-data/testmap

---

3.2 Reference Range Management

Priority: LOW

Features:

1. Reference Range Setup
   • Manage numeric reference ranges (refnum)
   • Manage text reference values (reftxt)
   • Age and sex-specific ranges

API Note:

Reference ranges are managed through test definition endpoints

---

Phase 4: Quality & Compliance Features (Weeks 7-8)

4.1 Critical Results Management

Priority: MEDIUM

Features:

1. Critical Results Alerting
   • Real-time critical result notifications
   • Acknowledgment tracking
   • Escalation workflow

API Endpoints:

• Use results API with flag filtering

---

4.2 Audit Trail

Priority: LOW

Features:

1. Activity Logging
   • Track who modified results
   • Track order status changes
   • Patient data access logs

---

Implementation Priority Matrix

Feature	Priority	Effort	Impact	Phase
Results Entry	CRITICAL	High	Critical	Phase 1
Results Verification	CRITICAL	Medium	Critical	Phase 1
Report Viewing	CRITICAL	Low	Critical	Phase 1
Live Dashboard	HIGH	Medium	High	Phase 1
Order Workflow	HIGH	Medium	High	Phase 2
Specimen Tracking	MEDIUM	Medium	Medium	Phase 2
Critical Results	MEDIUM	Medium	Medium	Phase 4
Reference Ranges	LOW	Medium	Low	Phase 3
Audit Trail	LOW	High	Low	Phase 4

---

Technical Implementation Notes

API Client Pattern

Following existing patterns in src/lib/api/:

// src/lib/api/results.js
import { get, patch, del } from './client.js';

export async function fetchResults(params = {}) {
  const query = new URLSearchParams(params).toString();
  return get(query ? `/api/results?${query}` : '/api/results');
}

export async function fetchResultById(id) {
  return get(`/api/results/${id}`);
}

export async function updateResult(id, data) {
  return patch(`/api/results/${id}`, data);
}

export async function deleteResult(id) {
  return del(`/api/results/${id}`);
}

Route Structure

src/routes/(app)/
├── dashboard/          # Update with live data
├── patients/           # ✅ Exists
├── visits/             # ✅ Exists  
├── orders/             # ✅ Exists (enhance)
├── results/            # NEW - Results management
│   ├── +page.svelte
│   ├── entry/
│   │   └── +page.svelte
│   └── verification/
│       └── +page.svelte
└── reports/            # NEW - Report viewing
    └── +page.svelte

Database Schema Relationships

Patient (1) → (N) Visits
Patient (1) → (N) Orders
Visit (1) → (N) Orders
Visit (1) → (N) ADT Records
Order (1) → (N) Specimens
Order (1) → (N) Results
Order (1) → (N) PatRes (test records)
Specimen (1) → (N) Results
Test Definition (1) → (N) Results

---

Success Criteria for MVP

1. End-to-end workflow works: Can register patient → create visit → create order → enter results → view report
2. Results validation: System correctly flags high/low results based on reference ranges
3. Order tracking: Can track order status through the pipeline
4. Dashboard: Shows real metrics, not static data
5. Reports: Can generate and view HTML reports for orders

---

Future Enhancements (Post-MVP)

1. Instrument Integration - Edge API for automated result import
2. Barcoding/Labeling - Specimen label printing
3. QC Management - Quality control charts and rules
4. Billing Integration - Connect to billing system
5. External Lab Interface - Send orders to reference labs
6. Mobile App - Phlebotomy collection app
7. Patient Portal - Patients can view their results
8. Analytics - Advanced reporting and statistics