mahdahar/clqms-fe1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
clqms-fe1/docs/frontend-implementation-plan.md

34 KiB
Raw Blame History

CLQMS Frontend Implementation Plan

Project Overview

CLQMS (Clinical Laboratory Quality Management System) frontend built with SvelteKit using the KISS (Keep It Simple) principle.

Architecture Decisions (KISS Principles)

  • No TypeScript - Plain JavaScript to keep it simple
  • Tailwind CSS & DaisyUI - Utility classes, minimal custom CSS
  • Simple Fetch API - Manual wrapper functions, no codegen
  • SvelteKit File-based Routing - Standard patterns
  • Server-side auth checking - SvelteKit hooks for session validation

Project Structure\n\n\nsrc/\n├── lib/\n│ ├── api/ # API service functions\n│ │ ├── client.js # Base fetch wrapper with auth\n│ │ ├── auth.js # Auth endpoints\n│ │ ├── valuesets.js # ValueSet endpoints\n│ │ ├── locations.js # Location endpoints\n│ │ ├── contacts.js # Contact endpoints\n│ │ ├── specialties.js # Specialty endpoints\n│ │ └── ... # Other endpoint modules\n│ ├── components/ # Reusable Svelte components\n│ │ ├── DataTable.svelte\n│ │ ├── Modal.svelte\n│ │ ├── SelectDropdown.svelte\n│ │ ├── Sidebar.svelte\n│ │ └── ToastContainer.svelte\n│ ├── stores/ # Svelte stores\n│ │ ├── auth.js # Auth state\n│ │ └── valuesets.js # Cached lookup values\n│ └── utils/ # Utility functions\n│ └── toast.js # Toast notifications\n├── routes/\n│ ├── +layout.svelte # Root layout with nav\n│ ├── +page.svelte # Redirect to login\n│ ├── login/\n│ │ └── +page.svelte\n│ └── (app)/ # Group: protected routes\n│ ├── +layout.svelte # Auth check with sidebar\n│ ├── dashboard/\n│ │ └── +page.svelte\n│ └── master-data/\n│ ├── +page.svelte\n│ ├── locations/\n│ ├── contacts/\n│ ├── specialties/\n│ └── valuesets/\n├── app.css # Global styles with Tailwind\n└── app.html # HTML template\n

Implementation Phases

Phase 0: Foundation ✅ COMPLETED

Priority: High | Time Estimate: 1-2 hours | Status: Done

  • Initialize SvelteKit project with Tailwind CSS
  • Configure API base URL and environment variables
  • Create base API client with JWT token handling
  • Implement login/logout flow
  • Create root layout with navigation
  • Set up protected route group with auth checks
  • Create dashboard homepage

Key Files:

  • src/lib/api/client.js - Base fetch wrapper
  • src/lib/api/auth.js - Auth endpoints
  • src/lib/stores/auth.js - Auth state management
  • src/routes/+layout.svelte - Root layout
  • src/routes/(app)/+layout.svelte - Protected layout
  • src/routes/login/+page.svelte - Login page

Phase 1: Foundation Data ✅ COMPLETED

Priority: High | Time Estimate: 4-6 hours | Status: Done

Why First: These are prerequisites for all other modules. ValueSets provide dropdown options; Master Data provides reference entities.

1a. System ValueSets Module (Library) ✅ COMPLETED

System ValueSets are pre-defined lookup values used throughout the application (gender, marital status, specimen types, etc.). These are read-only libraries fetched from JSON files and cached.

  • ValueSet browser page (view system value sets by key)
  • ValueSet items viewer (read-only)
  • Cache frequently used value sets in stores
  • SelectDropdown component using cached value sets
  • Refresh ValueSet cache

API Endpoints (Library/System ValueSets):

  • GET /api/valueset - List all library value sets with item counts
  • GET /api/valueset/{key} - Get library value set by key (e.g., 'marital_status', 'sex')
  • POST /api/valueset/refresh - Refresh library ValueSet cache from JSON files

1b. Master Data - Locations & Contacts ✅ COMPLETED

  • Locations list page with search (supports LocCode, LocName filters)
  • Locations create/edit form
  • Contacts (Physicians) list page
  • Contacts create/edit form

API Endpoints:

Locations:

  • GET /api/location - List locations (query: LocCode, LocName)
  • POST /api/location - Create location (required: LocCode, LocFull)
  • PATCH /api/location - Update location (required: LocCode, LocFull)
  • DELETE /api/location - Delete location (body: { LocationID })
  • GET /api/location/{id} - Get location details

Location Schema:

  • LocationID - Primary key (auto-generated)
  • SiteID - Reference to site
  • LocCode - Location code, max 6 chars (required)
  • Parent - Parent location ID (for hierarchical locations)
  • LocFull - Full location name, max 255 chars (required)
  • Description - Description, max 255 chars
  • LocType - Location type (e.g., ROOM, WARD, BUILDING)
  • CreateDate, EndDate - Timestamps

Contacts:

  • GET /api/contact - List contacts
  • POST /api/contact - Create contact (required: NameFirst)
  • PATCH /api/contact - Update contact
  • DELETE /api/contact - Delete contact
  • GET /api/contact/{id} - Get contact details

Contact Schema:

  • ContactID - Primary key (auto-generated)
  • NameFirst - First name (required)
  • NameLast - Last name
  • Title - Title (e.g., Dr, Mr, Mrs)
  • Initial - Middle initial
  • Birthdate - Date of birth (ISO 8601)
  • EmailAddress1, EmailAddress2 - Email addresses
  • Phone - Primary phone
  • MobilePhone1, MobilePhone2 - Mobile numbers
  • Specialty - Medical specialty code
  • SubSpecialty - Sub-specialty code
  • CreateDate, EndDate - Timestamps

1d. Master Data - Supporting Entities ✅ COMPLETED

  • Occupations management
  • Medical Specialties management
  • Counters management (for ID generation)

API Endpoints:

Occupations:

  • GET /api/occupation - List occupations
  • POST /api/occupation - Create occupation (required: OccCode, OccText)
  • PATCH /api/occupation - Update occupation (required: OccCode, OccText)
  • GET /api/occupation/{id} - Get occupation details

Occupation Schema:

  • OccupationID - Primary key (auto-generated)
  • OccCode - Occupation code (required)
  • OccText - Occupation name/text (required)
  • Description - Additional description
  • CreateDate - Creation timestamp

Medical Specialties:

  • GET /api/medicalspecialty - List specialties
  • POST /api/medicalspecialty - Create specialty (required: SpecialtyText)
  • PATCH /api/medicalspecialty - Update specialty (required: SpecialtyText)
  • GET /api/medicalspecialty/{id} - Get specialty details

Medical Specialty Schema:

  • SpecialtyID - Primary key (auto-generated)
  • SpecialtyText - Specialty name/text (required)
  • Parent - Parent specialty ID (for hierarchical structure)
  • Title - Title/abbreviation
  • CreateDate, EndDate - Timestamps

Counters:

  • GET /api/counter - List counters
  • POST /api/counter - Create counter
  • PATCH /api/counter - Update counter
  • DELETE /api/counter - Delete counter (body: { CounterID })
  • GET /api/counter/{id} - Get counter details

Counter Schema:

  • CounterID - Primary key (auto-generated)
  • CounterDesc - Counter description/name
  • CounterValue - Current counter value
  • CounterStart - Starting value
  • CounterEnd - Ending value (for auto-reset)
  • CounterReset - Reset pattern (D=Daily, M=Monthly, Y=Yearly)

1e. Master Data - Geography ✅ COMPLETED

  • Geographical areas list
  • Provinces list (read-only dropdown)
  • Cities list with province filter

API Endpoints:

  • GET /api/areageo - List all geographical areas
  • GET /api/areageo/provinces - List provinces
  • GET /api/areageo/cities?province_id={id} - List cities (with province filter)

Notes:

  • Geography endpoints are read-only (no POST/PATCH/DELETE)
  • Used for patient address province/city selection
  • Returns hierarchical location data

Phase 2: Patient Management\nPriority: High | Time Estimate: 3-4 hours\n\nDependencies: Master Data (locations, contacts, occupations, provinces/cities)\n\n#### 2a. Patient CRUD\n- [ ] Patients list page with pagination and search\n- [ ] Patient create form with validation\n- [ ] Patient edit form\n- [ ] Patient detail view\n- [ ] Patient delete with confirmation\n\nAPI Endpoints:\n- GET /api/patient - List patients (query: page, perPage, InternalPID, PatientID, Name, Birthdate)\n- POST /api/patient - Create patient\n- PATCH /api/patient - Update patient\n- DELETE /api/patient - Delete patient (soft delete, body: { InternalPID })\n- GET /api/patient/{id} - Get patient by ID\n- GET /api/patient/check - Check if patient exists (query: PatientID, EmailAddress1)

2b. Advanced Patient Features

  • Patient identifier management (KTP, PASS, SSN, etc.)
  • Patient linking (family relationships)
  • Custodian/guardian assignment
  • Patient address management

Fields to Implement:

  • PatientID, AlternatePID
  • Prefix, NameFirst, NameMiddle, NameLast, NameMaiden, Suffix
  • Sex, Birthdate, PlaceOfBirth, Citizenship
  • Address fields (Street_1/2/3, ZIP, Province, City, Country)
  • Contact (Phone, MobilePhone, EmailAddress1/2)
  • Identifiers (PatIdt - type and number)
  • Demographics (Race, MaritalStatus, Religion, Ethnic)
  • Linked patients (LinkTo)
  • Custodian
  • DeathIndicator, TimeOfDeath
  • Comments (PatCom)

Phase 3: Patient Visits

Priority: High | Time Estimate: 2-3 hours

Dependencies: Patients, Master Data (locations, contacts)

  • Visits list page with filters
  • Create visit form
  • Edit visit form
  • View visits by patient
  • ADT workflow (Admit/Discharge/Transfer)

API Endpoints:

  • GET /api/patvisit - List visits
  • POST /api/patvisit - Create visit
  • PATCH /api/patvisit - Update visit
  • DELETE /api/patvisit - Delete visit
  • GET /api/patvisit/{id} - Get visit by ID
  • GET /api/patvisit/patient/{patientId} - Get visits by patient
  • POST /api/patvisitadt - Create ADT visit
  • PATCH /api/patvisitadt - Update ADT visit

Fields:

  • VisitID, PatientID, VisitDate, VisitType
  • SiteID, LocationID, DepartmentID
  • AttendingPhysician, ReferringPhysician

Phase 4: Specimen Management

Priority: Medium | Time Estimate: 2-3 hours

Dependencies: ValueSets (specimen types, collection methods, statuses)

  • Specimens list page
  • Specimen create/edit forms
  • Container definitions management
  • Specimen preparation methods
  • Specimen statuses
  • Collection methods
  • Samples list with status filtering

API Endpoints:

  • GET /api/specimen - List specimens
  • POST /api/specimen - Create specimen
  • PATCH /api/specimen - Update specimen
  • GET /api/specimen/{id} - Get specimen details
  • GET /api/specimen/container - List containers
  • POST /api/specimen/container - Create container
  • PATCH /api/specimen/container - Update container
  • GET /api/specimen/container/{id} - Get container details
  • GET /api/specimen/prep - List preparations
  • POST /api/specimen/prep - Create preparation
  • PATCH /api/specimen/prep - Update preparation
  • GET /api/specimen/prep/{id} - Get preparation details
  • GET /api/specimen/status - List statuses
  • POST /api/specimen/status - Create status
  • PATCH /api/specimen/status - Update status
  • GET /api/specimen/status/{id} - Get status details
  • GET /api/specimen/collection - List collection methods
  • POST /api/specimen/collection - Create collection method
  • PATCH /api/specimen/collection - Update collection method
  • GET /api/specimen/collection/{id} - Get collection method details
  • GET /api/sample - Get samples (with status filter)

Phase 5: Test Catalog\nPriority: Medium | Time Estimate: 2-3 hours\n\nDependencies: Organization (disciplines, departments), ValueSets\n\n- [ ] Test definitions list with filtering\n- [ ] Create/edit test definitions\n- [ ] Test mapping management (host/client codes)\n\nAPI Endpoints:\n- GET /api/tests - List tests\n- POST /api/tests - Create test\n- PATCH /api/tests - Update test\n- GET /api/tests/{id} - Get test details\n\nQuery Parameters:\n- page, perPage - Pagination\n- SiteID - Filter by site\n- TestType - Filter by type (TEST, PARAM, CALC, GROUP, TITLE)\n- VisibleScr - Filter by screen visibility (0=hidden, 1=visible)\n- VisibleRpt - Filter by report visibility (0=hidden, 1=visible)\n- TestSiteName - Search by test name or code\n\nTest Types:\n- TEST - Technical test\n- PARAM - Parameter\n- CALC - Calculated\n- GROUP - Panel/Profile\n- TITLE - Section header\n\nTest Definition Schema:\n- id - Primary key\n- TestCode - Test code\n- TestName - Test name\n- TestType - Type (TEST, PARAM, CALC, GROUP, TITLE)\n- DisciplineID - Reference to discipline\n- DepartmentID - Reference to department\n- SpecimenType - Specimen type code\n- Unit - Measurement unit\n- Formula - Calculation formula

Phase 6: Orders\nPriority: High | Time Estimate: 3-4 hours\n\nDependencies: Patients, Visits, Tests, Specimen, ValueSets (priorities, statuses)\n\n- [ ] Orders list with status filtering\n- [ ] Create order with test selection\n- [ ] Order detail view\n- [ ] Update order status\n- [ ] Order items management\n\nAPI Endpoints:\n- GET /api/ordertest - List orders (filters: OrderStatus, InternalPID, page, perPage)\n- POST /api/ordertest - Create order (requires: PatientID, Tests array)\n- PATCH /api/ordertest - Update order\n- DELETE /api/ordertest - Delete order\n- GET /api/ordertest/{id} - Get order details\n- POST /api/ordertest/status - Update order status (body: { OrderID, OrderStatus })\n\nOrder Status Values:\n- ORD - Ordered\n- SCH - Scheduled\n- ANA - Analysis\n- VER - Verified\n- REV - Reviewed\n- REP - Reported\n\nPriority Values:\n- R - Routine\n- S - Stat\n- U - Urgent\n\nOrderTest Schema:\n- OrderID - Order identifier\n- PatientID - Reference to patient\n- VisitID - Reference to visit\n- OrderDate - Order timestamp (ISO 8601)\n- OrderStatus - Status code (ORD, SCH, ANA, VER, REV, REP)\n- Priority - Priority code (R, S, U)\n- SiteID - Reference to site\n- RequestingPhysician - Requesting physician identifier\n\nCreate Order Request:\njson\n{\n \"PatientID\": \"string\",\n \"VisitID\": \"string\" (optional),\n \"Priority\": \"R|S|U\",\n \"SiteID\": integer (optional),\n \"RequestingPhysician\": \"string\" (optional),\n \"Tests\": [\n {\n \"TestID\": integer,\n \"SpecimenType\": \"string\" (optional)\n }\n ]\n}\n

Phase 7: Results & Dashboard

Priority: High | Time Estimate: 2-3 hours

Dependencies: Orders

  • Dashboard with summary cards
  • Results list with patient filtering
  • Sample tracking view

API Endpoints:

  • GET /api/dashboard - Get dashboard summary
    • Returns: pendingOrders, todayResults, criticalResults, activePatients
  • GET /api/result - Get patient results (filter by PatientID, pagination with page)

Dashboard Metrics:

  • pendingOrders - Number of pending orders
  • todayResults - Results processed today
  • criticalResults - Critical/panic results
  • activePatients - Currently active patients

Phase 8: User-defined ValueSets

Priority: Medium | Time Estimate: 3-4 hours Dependencies: Test Catalog (Phase 5)

User-defined ValueSets are created and managed by lab administrators in the database (not from JSON files). These require full CRUD operations and are used for test result interpretation (reference ranges, flags, interpretations).

  • User ValueSet definitions list page
  • User ValueSet definition create/edit form
  • User ValueSet items management (CRUD)

API Endpoints:

User ValueSet Definitions:

  • GET /api/valueset/user/def - List user value set definitions
  • POST /api/valueset/user/def - Create user value set definition
  • GET /api/valueset/user/def/{id} - Get user value set definition by ID
  • PUT /api/valueset/user/def/{id} - Update user value set definition
  • DELETE /api/valueset/user/def/{id} - Delete user value set definition

User ValueSet Items:

  • GET /api/valueset/user/items - List user value set items (filter by VSetID)
  • POST /api/valueset/user/items - Create user value set item
  • GET /api/valueset/user/items/{id} - Get user value set item by ID
  • PUT /api/valueset/user/items/{id} - Update user value set item
  • DELETE /api/valueset/user/items/{id} - Delete user value set item

ValueSetDef Schema:

  • id - Primary key
  • VSetCode - Value set code
  • VSetName - Value set name
  • Description - Description
  • Category - Category

ValueSetItem Schema:

  • id - Primary key
  • VSetID - Reference to ValueSet definition
  • VValue - Value code
  • VLabel - Display label
  • VSeq - Sequence order
  • IsActive - Active flag (boolean)

Phase 9: Organization Structure\nPriority: Medium | Time Estimate: 2-3 hours\n\n- [ ] Accounts management\n- [ ] Sites management\n- [ ] Disciplines management\n- [ ] Departments management\n- [ ] Workstations management\n\nAPI Endpoints:\n\nAccounts:\n- GET /api/organization/account - List accounts\n- POST /api/organization/account - Create account\n- PATCH /api/organization/account - Update account (body: { id, AccountName, AccountCode, AccountType })\n- DELETE /api/organization/account - Delete account (body: { id })\n- GET /api/organization/account/{id} - Get account details\n\nAccount Schema:\n- id - Primary key\n- AccountName - Account name\n- AccountCode - Account code\n- AccountType - Account type\n\nSites:\n- GET /api/organization/site - List sites\n- POST /api/organization/site - Create site\n- PATCH /api/organization/site - Update site (body: { id, SiteName, SiteCode, AccountID })\n- DELETE /api/organization/site - Delete site (body: { id })\n- GET /api/organization/site/{id} - Get site details\n\nSite Schema:\n- id - Primary key\n- SiteName - Site name\n- SiteCode - Site code\n- AccountID - Reference to account\n\nDisciplines:\n- GET /api/organization/discipline - List disciplines\n- POST /api/organization/discipline - Create discipline\n- PATCH /api/organization/discipline - Update discipline (body: { id, DisciplineName, DisciplineCode })\n- DELETE /api/organization/discipline - Delete discipline (body: { id })\n- GET /api/organization/discipline/{id} - Get discipline details\n\nDiscipline Schema:\n- id - Primary key\n- DisciplineName - Discipline name\n- DisciplineCode - Discipline code\n\nDepartments:\n- GET /api/organization/department - List departments\n- POST /api/organization/department - Create department\n- PATCH /api/organization/department - Update department (body: { id, DeptName, DeptCode, SiteID })\n- DELETE /api/organization/department - Delete department (body: { id })\n- GET /api/organization/department/{id} - Get department details\n\nDepartment Schema:\n- id - Primary key\n- DeptName - Department name\n- DeptCode - Department code\n- SiteID - Reference to site\n\nWorkstations:\n- GET /api/organization/workstation - List workstations\n- POST /api/organization/workstation - Create workstation\n- PATCH /api/organization/workstation - Update workstation (body: { id, WorkstationName, WorkstationCode, SiteID, DepartmentID })\n- DELETE /api/organization/workstation - Delete workstation (body: { id })\n- GET /api/organization/workstation/{id} - Get workstation details\n\nWorkstation Schema:\n- id - Primary key\n- WorkstationName - Workstation name\n- WorkstationCode - Workstation code\n- SiteID - Reference to site\n- DepartmentID - Reference to department

Phase 10: Edge API (Instrument Integration)

Priority: Low | Time Estimate: 2-3 hours

  • Edge results viewer
  • Pending orders for instruments
  • Instrument status monitoring

API Endpoints:

  • GET /api/edge/orders - Fetch pending orders (filter by instrument_id, status)
  • POST /api/edge/orders/{orderId}/ack - Acknowledge order delivery
  • POST /api/edge/results - Receive results from instrument (tiny-edge)
  • POST /api/edge/status - Log instrument status (status: online, offline, error, maintenance)

Phase 11: Authentication

Priority: High | Time Estimate: 1-2 hours | Status: ✅ COMPLETED

Foundation authentication system for user login/logout and session management.

  • Login page with form validation
  • JWT token handling (HTTP-only cookie)
  • Logout functionality
  • Auth state management
  • Protected route guards
  • Auth status checking

API Endpoints:

V1 Authentication:

  • POST /api/auth/login - User login (returns JWT in cookie)
  • POST /api/auth/logout - User logout
  • GET /api/auth/check - Check authentication status
  • POST /api/auth/register - Register new user
  • POST /api/auth/change_pass - Change password (authenticated)

V2 Authentication:

  • POST /v2/auth/login - V2 User login
  • POST /v2/auth/logout - V2 User logout
  • GET /v2/auth/check - V2 Check authentication
  • POST /v2/auth/register - V2 Register new user

Security:

  • JWT tokens stored in HTTP-only cookies
  • Bearer token support for API requests
  • Automatic redirect to login on 401 responses

Reusable Components to Build

1. FormInput.svelte

Text input with label, validation, and error display.

Status: Not yet implemented - using native inputs with DaisyUI styling

<FormInput 
  label="Patient ID"
  name="patientId"
  value={patientId}
  required
  pattern="[A-Za-z0-9]+"
/>

2. SelectDropdown.svelte ✅ COMPLETED

Dropdown populated from ValueSets or API data.

<SelectDropdown
  label="Gender"
  name="sex"
  value={sex}
  options={genderOptions}
/>

3. DataTable.svelte ✅ COMPLETED

Sortable, paginated table with actions.

<DataTable
  columns={['ID', 'Name', 'Status']}
  data={patients}
  onEdit={handleEdit}
  onDelete={handleDelete}
  pagination={true}
/>

4. SearchBar.svelte

Search input with debounce.

Status: Not yet implemented

5. Modal.svelte ✅ COMPLETED

Reusable modal for confirmations and forms.

Code Patterns

API Client Pattern

// lib/api/client.js
const API_BASE = import.meta.env.VITE_API_URL || 'http://localhost/clqms01';

export async function apiFetch(endpoint, options = {}) {
  const token = get(authToken);
  
  const res = await fetch(`${API_BASE}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...(token && { 'Authorization': `Bearer ${token}` }),
      ...options.headers
    }
  });
  
  if (res.status === 401) {
    // Handle unauthorized
    authToken.set(null);
    goto('/login');
    return;
  }
  
  return res.json();
}

Form Handling Pattern

<script>
  let formData = { name: '', email: '' };
  let errors = {};
  let loading = false;

  async function handleSubmit() {
    loading = true;
    errors = {};
    
    const result = await createItem(formData);
    
    if (result.status === 'error') {
      errors = result.errors || { general: result.message };
    } else {
      // Success - redirect or show message
    }
    
    loading = false;
  }
</script>

<form on:submit|preventDefault={handleSubmit}>
  <FormInput 
    label="Name" 
    bind:value={formData.name}
    error={errors.name}
  />
  <button type="submit" disabled={loading}>
    {loading ? 'Saving...' : 'Save'}
  </button>
</form>

Store Pattern for ValueSets

// lib/stores/valuesets.js
import { writable } from 'svelte/store';

export const valueSets = writable({});

export async function loadValueSet(key) {
  const res = await fetch(`/api/valueset/${key}`);
  const data = await res.json();
  
  valueSets.update(vs => ({
    ...vs,
    [key]: data.data?.Items || []
  }));
}

// Usage in component:
// onMount(() => loadValueSet('GENDER'));

Environment Setup

Create .env file:

VITE_API_URL=http://localhost/clqms01

Getting Started

  1. Initialize SvelteKit:

    npm create svelte@latest clqms-fe
cd clqms-fe
npm install
npx svelte-add@latest tailwindcss
npm install

  2. Configure tailwind.config.js:

    export default {
  content: ['./src/**/*.{html,js,svelte,ts}'],
  theme: { extend: {} },
  plugins: []
};

  3. Start with Phase 0:

    • Create API client
    • Set up auth stores
    • Build login page
    • Create protected layout

Navigation Structure

Dashboard (Home)
├── Master Data
│   ├── System ValueSets (read-only from JSON)
│   ├── Locations
│   ├── Contacts
│   ├── Occupations
│   ├── Medical Specialties
│   ├── Counters
│   └── Geography (Provinces/Cities)
├── Organization
│   ├── Accounts
│   ├── Sites
│   ├── Disciplines
│   ├── Departments
│   └── Workstations
├── Patients
│   ├── All Patients
│   └── Patient Visits
├── Laboratory
│   ├── Specimens
│   ├── Tests
│   ├── Orders
│   ├── Results
│   └── User ValueSets (CRUD in database)
└── Edge
    └── Instrument Status

Notes

  • Use +layout.server.js for server-side auth checks
  • Use SvelteKit's invalidateAll() after mutations
  • Cache ValueSets in localStorage for better UX
  • Implement optimistic updates where appropriate
  • Use loading states for all async operations
  • Add toast notifications for success/error feedback

API Reference Summary

Authentication

Method Endpoint Description
POST /api/auth/login User login (JWT in cookie)
POST /api/auth/logout User logout
GET /api/auth/check Check auth status
POST /api/auth/register Register new user
POST /api/auth/change_pass Change password
POST /v2/auth/login V2 Login
POST /v2/auth/logout V2 Logout
GET /v2/auth/check V2 Auth check
POST /v2/auth/register V2 Register

ValueSets (Library/System)

Method Endpoint Description
GET /api/valueset List all library value sets
GET /api/valueset/{key} Get value set by key
POST /api/valueset/refresh Refresh cache from JSON

ValueSets (User-defined)

Method Endpoint Description
GET /api/valueset/user/def List user value set definitions
POST /api/valueset/user/def Create definition
GET /api/valueset/user/def/{id} Get definition by ID
PUT /api/valueset/user/def/{id} Update definition
DELETE /api/valueset/user/def/{id} Delete definition
GET /api/valueset/user/items List items (filter: VSetID)
POST /api/valueset/user/items Create item
GET /api/valueset/user/items/{id} Get item by ID
PUT /api/valueset/user/items/{id} Update item
DELETE /api/valueset/user/items/{id} Delete item

Master Data - Locations

Method Endpoint Description
GET /api/location List locations (query: LocCode, LocName)
POST /api/location Create location
PATCH /api/location Update location
DELETE /api/location Delete location
GET /api/location/{id} Get location by ID

Master Data - Contacts

Method Endpoint Description
GET /api/contact List contacts
POST /api/contact Create contact
PATCH /api/contact Update contact
DELETE /api/contact Delete contact
GET /api/contact/{id} Get contact by ID

Master Data - Supporting Entities

Method Endpoint Description
GET /api/occupation List occupations
POST /api/occupation Create occupation
PATCH /api/occupation Update occupation
GET /api/occupation/{id} Get occupation by ID
GET /api/medicalspecialty List specialties
POST /api/medicalspecialty Create specialty
PATCH /api/medicalspecialty Update specialty
GET /api/medicalspecialty/{id} Get specialty by ID
GET /api/counter List counters
POST /api/counter Create counter
PATCH /api/counter Update counter
DELETE /api/counter Delete counter
GET /api/counter/{id} Get counter by ID

Master Data - Geography (Read-only)

Method Endpoint Description
GET /api/areageo List all geographical areas
GET /api/areageo/provinces List provinces
GET /api/areageo/cities List cities (query: province_id)

Patients

Method Endpoint Description
GET /api/patient List patients (query: page, perPage, Name, etc.)
POST /api/patient Create patient
PATCH /api/patient Update patient
DELETE /api/patient Delete patient (soft delete)
GET /api/patient/{id} Get patient by ID
GET /api/patient/check Check if patient exists

Patient Visits

Method Endpoint Description
GET /api/patvisit List visits (query: page, perPage)
POST /api/patvisit Create visit
PATCH /api/patvisit Update visit
DELETE /api/patvisit Delete visit
GET /api/patvisit/{id} Get visit by PVID
GET /api/patvisit/patient/{patientId} Get visits by patient
POST /api/patvisitadt Create ADT visit
PATCH /api/patvisitadt Update ADT visit

Organization - Accounts

Method Endpoint Description
GET /api/organization/account List accounts
POST /api/organization/account Create account
PATCH /api/organization/account Update account
DELETE /api/organization/account Delete account
GET /api/organization/account/{id} Get account by ID

Organization - Sites

Method Endpoint Description
GET /api/organization/site List sites
POST /api/organization/site Create site
PATCH /api/organization/site Update site
DELETE /api/organization/site Delete site
GET /api/organization/site/{id} Get site by ID

Organization - Disciplines

Method Endpoint Description
GET /api/organization/discipline List disciplines
POST /api/organization/discipline Create discipline
PATCH /api/organization/discipline Update discipline
DELETE /api/organization/discipline Delete discipline
GET /api/organization/discipline/{id} Get discipline by ID

Organization - Departments

Method Endpoint Description
GET /api/organization/department List departments
POST /api/organization/department Create department
PATCH /api/organization/department Update department
DELETE /api/organization/department Delete department
GET /api/organization/department/{id} Get department by ID

Organization - Workstations

Method Endpoint Description
GET /api/organization/workstation List workstations
POST /api/organization/workstation Create workstation
PATCH /api/organization/workstation Update workstation
DELETE /api/organization/workstation Delete workstation
GET /api/organization/workstation/{id} Get workstation by ID

Specimen Management

Method Endpoint Description
GET /api/specimen List specimens
POST /api/specimen Create specimen
PATCH /api/specimen Update specimen
GET /api/specimen/{id} Get specimen by ID
GET /api/specimen/container List containers
POST /api/specimen/container Create container
PATCH /api/specimen/container Update container
GET /api/specimen/container/{id} Get container by ID
GET /api/specimen/prep List preparations
POST /api/specimen/prep Create preparation
PATCH /api/specimen/prep Update preparation
GET /api/specimen/prep/{id} Get preparation by ID
GET /api/specimen/status List statuses
POST /api/specimen/status Create status
PATCH /api/specimen/status Update status
GET /api/specimen/status/{id} Get status by ID
GET /api/specimen/collection List collection methods
POST /api/specimen/collection Create collection method
PATCH /api/specimen/collection Update collection method
GET /api/specimen/collection/{id} Get collection method by ID
GET /api/sample Get samples

Test Catalog

Method Endpoint Description
GET /api/tests List tests (query: TestType, SiteID, etc.)
POST /api/tests Create test
PATCH /api/tests Update test
GET /api/tests/{id} Get test by ID

Orders

Method Endpoint Description
GET /api/ordertest List orders (query: OrderStatus, InternalPID)
POST /api/ordertest Create order
PATCH /api/ordertest Update order
DELETE /api/ordertest Delete order
GET /api/ordertest/{id} Get order by ID
POST /api/ordertest/status Update order status

Results & Dashboard

Method Endpoint Description
GET /api/dashboard Get dashboard summary
GET /api/result Get patient results (query: PatientID, page)

Edge API (Instrument Integration)

Method Endpoint Description
GET /api/edge/orders Fetch pending orders
POST /api/edge/orders/{orderId}/ack Acknowledge order
POST /api/edge/results Receive instrument results
POST /api/edge/status Log instrument status