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/`:

```javascript
// 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