clqms-be/CLAUDE.md

# CLQMS Backend - Claude Code Instructions

**Project:** Clinical Laboratory Quality Management System (CLQMS) Backend
**Framework:** CodeIgniter 4 (PHP)
**Platform:** Windows - Use PowerShell or CMD for terminal commands
**Frontend:** Alpine.js (views/v2 directory contains Alpine.js components)

### Views/V2 Structure
```
app/Views/v2/
├── layout/
│   └── main_layout.php       # Main layout with sidebar, navbar, Alpine.js layout() component
├── auth/
│   └── login.php             # Login page
├── dashboard/
│   └── dashboard_index.php   # Dashboard view
├── patients/
│   ├── patients_index.php    # Patient list with x-data="patients()" component
│   └── dialog_form.php       # Patient form dialog
├── requests/
│   └── requests_index.php    # Lab requests
├── settings/
│   └── settings_index.php    # Settings page
└── master/
    ├── organization/         # Organization management (accounts, sites, disciplines, departments, workstations)
    ├── specimen/             # Specimen management (containers, preparations)
    ├── tests/                # Lab tests (tests_index, param_dialog, grp_dialog, calc_dialog)
    └── valuesets/            # Value sets management
```

### Alpine.js Patterns
- **Global layout:** `layout()` function in `main_layout.php` handles sidebar state, theme toggle, and navigation
- **Page components:** Each page uses `x-data="componentName()"` (e.g., `x-data="patients()"`)
- **API calls:** Use `fetch()` with `BASEURL` global variable and `credentials: 'include'`
- **Dialogs:** Modals use `x-show` with `@click.self` backdrop click to close
- **TailwindCSS 4:** Loaded via CDN with custom CSS variables for theming

## Quick Reference

**Static Library:**
- [`Lookups`](app/Libraries/Lookups.php) - Static lookup constants (no database queries)

**Usage:**
```php
use App\Libraries\Lookups;

// Get formatted lookup [{value: 'KEY', label: 'Label'}, ...]
Lookups::get('gender');

// Get raw associative array ['KEY' => 'Label', ...]
Lookups::getRaw('gender');

// Get all lookups for frontend
Lookups::getAll();
```

## Agent Workflow for Valueset Queries

Use `Lookups` class for all lookup queries - no database queries needed.

### Step 1: Identify the Lookup Constant

**By Category Name:** Match VSName to constant name (e.g., "Gender" → `Lookups::GENDER`)
**By Reference:** Match VSDesc to constant name (e.g., `testdefsite.TestType` → `Lookups::TEST_TYPE`)
**By VSetDefID:** Map VSetDefID to constant (see Common Lookups table below)

### Step 2: Retrieve Values

```php
// Formatted for frontend dropdowns
Lookups::get('gender');    // [{value: '1', label: 'Female'}, ...]

// Raw key-value pairs
Lookups::getRaw('gender'); // ['1' => 'Female', '2' => 'Male', ...]
```

### Step 3: Return Results

**Response Format (formatted):**
```json
[
  { "value": "1", "label": "Female" },
  { "value": "2", "label": "Male" },
  { "value": "3", "label": "Unknown" }
]
```

## Common Lookups

| VSetDefID | Constant | Search Keywords |
|-----------|----------|-----------------|
| 1 | `WS_TYPE` | workstation, type |
| 2 | `ENABLE_DISABLE` | enable, disable |
| 3 | `GENDER` | gender, sex |
| 4 | `MARITAL_STATUS` | marital, status |
| 5 | `DEATH_INDICATOR` | death, indicator |
| 6 | `IDENTIFIER_TYPE` | identifier, type, KTP, passport |
| 7 | `OPERATION` | operation, CRUD |
| 8 | `DID_TYPE` | device, ID, AAID, IDFA |
| 9 | `REQUESTED_ENTITY` | requested, entity, patient, insurance |
| 10 | `ORDER_PRIORITY` | priority, order, stat, ASAP |
| 11 | `ORDER_STATUS` | status, order |
| 12 | `LOCATION_TYPE` | location, type |
| 13 | `ADDITIVE` | additive, heparin, EDTA |
| 14 | `CONTAINER_CLASS` | container, class |
| 15 | `SPECIMEN_TYPE` | specimen, type, blood, urine |
| 16 | `UNIT` | unit |
| 17 | `GENERATE_BY` | generate, by |
| 18 | `SPECIMEN_ACTIVITY` | specimen, activity |
| 19 | `ACTIVITY_RESULT` | activity, result |
| 20 | `SPECIMEN_STATUS` | specimen, status |
| 21 | `SPECIMEN_CONDITION` | specimen, condition |
| 22 | `SPECIMEN_ROLE` | specimen, role |
| 23 | `COLLECTION_METHOD` | collection, method |
| 24 | `BODY_SITE` | body, site |
| 25 | `CONTAINER_SIZE` | container, size |
| 26 | `FASTING_STATUS` | fasting, status |
| 27 | `TEST_TYPE` | test, type, testdefsite |
| 28 | `RESULT_UNIT` | result, unit |
| 29 | `FORMULA_LANGUAGE` | formula, language |
| 30 | `RACE` | race, ethnicity |
| 31 | `RELIGION` | religion |
| 32 | `ETHNIC` | ethnic |
| 33 | `COUNTRY` | country (loaded from external file) |
| 34 | `CONTAINER_CAP_COLOR` | container, cap, color |
| 35 | `TEST_ACTIVITY` | test, activity |
| 36 | `ADT_EVENT` | ADT, event |
| 37 | `SITE_TYPE` | site, type |
| 38 | `SITE_CLASS` | site, class |
| 39 | `ENTITY_TYPE` | entity, type |
| 40 | `AREA_CLASS` | area, class |
| 41 | `MATH_SIGN` | math, sign |
| 42 | `V_CATEGORY` | category |
| 43 | `RESULT_TYPE` | result, type |
| 44 | `REFERENCE_TYPE` | reference, type |
| 45 | `RANGE_TYPE` | range, type |
| 46 | `NUMERIC_REF_TYPE` | numeric, reference |
| 47 | `TEXT_REF_TYPE` | text, reference |

**Convenience Aliases:**
- `Lookups::PRIORITY` → alias for `ORDER_PRIORITY`
- `Lookups::TEST_STATUS` → Test status values
- `Lookups::REQUEST_STATUS` → alias for `SPECIMEN_STATUS`
- `Lookups::RESULT_STATUS` → Result status values

## Example Agent Conversations

**User:** "Show me Gender values"
**Agent:**
1. `Lookups::get('gender')` → Returns formatted array
2. Output: Female, Male, Unknown

**User:** "What values for testdefsite.TestType?"
**Agent:**
1. `Lookups::get('test_type')` → Returns formatted array
2. Output: TEST, PARAM, CALC, GROUP, TITLE

**User:** "Find specimen status options"
**Agent:**
1. `Lookups::get('specimen_status')` → Returns formatted array
2. Output: To be collected, Collected, In-transport, Arrived, etc.

---

## Commanding Officer Persona Mode

When the user addresses you as their commanding officer or in a starship context, respond accordingly:

- Address the officer respectfully ("Commander", "Captain", "Sir/Ma'am")
- Use military/space command terminology ("affirmative", "reporting", "orders", "status")
- Frame technical responses in mission-ops format ("Systems operational", "Data retrieved", "Report ready")
- Keep responses crisp and professional, befitting ship command
- Example: "Commander, the valueset data you requested is ready for review."
- Start something with basmalah and end with hamdalah