clqms-be/GEMINI.md

# CLQMS (Clinical Laboratory Quality Management System) - Gemini Context

This file provides context and instructional guidelines for Gemini agents working on the CLQMS repository.

## 1. Project Overview

**CLQMS** is a **headless REST API backend** for a Clinical Laboratory Quality Management System. It manages the complete laboratory workflow: patient registration, ordering, specimen tracking, result entry/verification, and instrument integration.

*   **Type:** API-only Backend (No View Layer).
*   **Framework:** CodeIgniter 4 (PHP 8.1+).
*   **Database:** MySQL.
*   **Authentication:** JWT (Stateless).
*   **Architecture:** Modular MVC with a file-based Lookup Library.

## 2. Technical Stack

*   **Language:** PHP 8.1+ (PSR-compliant)
*   **Framework:** CodeIgniter 4
*   **Dependencies:** `firebase/php-jwt` (Auth), `phpunit/phpunit` (Testing)
*   **Database:** MySQL (Managed via Migrations)
*   **Entry Point:** `public/index.php` (Web), `spark` (CLI)

## 3. Development Workflow & Conventions

### Tool Usage Guidelines
**Critical:** Prioritize semantic code analysis tools over generic file reading to minimize context window usage and improve accuracy.

*   **Explore Code:** Use `find_symbol` or `get_symbols_overview`.
*   **Modify Code:** Use `replace_symbol_body` for functions/classes. Use `replace_content` (regex) for small tweaks.
*   **Add Code:** Use `insert_before_symbol` / `insert_after_symbol`.
*   **Search:** Use `search_for_pattern`.
*   **File Discovery:** Use `list_dir` / `find_file`.

### Common Commands

**Testing:**
```bash
# Run all tests
vendor/bin/phpunit

# Run specific test file
vendor/bin/phpunit tests/feature/UniformShowTest.php

# Run tests in a directory
vendor/bin/phpunit app/Models
```

**Database & Migrations:**
```bash
# Run migrations
spark migrate

# Rollback migrations
spark migrate:rollback

# Seed database
spark db:seed DBSeeder

# Refresh all (Reset DB)
spark migrate:refresh --seed
```

**Code Generation:**
```bash
spark make:model ModelName
spark make:controller ControllerName
spark make:migration MigrationName
```

## 4. Key Architectural Patterns

### MVC Structure
*   **Controllers (`app/Controllers/`)**: Organized by domain (Patient, Order, Test, etc.). All extend `BaseController`.
*   **Models (`app/Models/`)**: Domain-specific data access. All extend `BaseModel`.
    *   **UTC Handling:** Models automatically normalize dates to UTC on save and format to UTC ISO on retrieve.

### Lookup System (`App\Libraries\ValueSet`)
*   **Mechanism:** JSON file-based static data storage. **Do not use database queries for static lookups.**
*   **Location:** `app/Libraries/Data/valuesets/*.json`.
*   **Usage:**
    ```php
    use App\Libraries\ValueSet;
    $options = ValueSet::get('gender'); // Returns dropdown options
    $label = ValueSet::getLabel('gender', '1'); // Returns 'Female'
    ```
*   **Cache:** System caches these files. Run `ValueSet::clearCache()` if files are modified manually (rare).

### Edge API (Instrument Integration)
*   **Purpose:** Middleware for laboratory analyzers.
*   **Flow:** Instrument -> `tiny-edge` -> `POST /api/edge/results` -> `edgeres` table -> Processing -> `patresult` table.
*   **Controllers:** `EdgeController`.

### Database Schema
*   **Migrations:** Sequentially numbered (e.g., `2026-01-01-000001`).
*   **Master Data:** `valueset`, `testdef*` (test definitions), `ref*` (reference ranges).
*   **Transactions:** `patient`, `porder` (orders), `specimen`, `patresult`.

## 5. Documentation Map

*   **`README.md`**: High-level API overview and endpoint list.
*   **`PRD.md`**: Detailed Product Requirements Document. **Read this for business logic queries.**
*   **`CLAUDE.md`**: Original developer guide (source of these conventions).
*   **`TODO.md`**: Current project status and roadmap.
*   **`app/Config/Routes.php`**: API Route definitions.

## 6. Testing Strategy

*   **Framework:** PHPUnit 10.5+.
*   **Location:** `tests/`.
*   **Coverage:** Aim for high coverage on core logic (Models, Libraries).
*   **Configuration:** `phpunit.xml.dist`.

## 7. Configuration
*   **Environment:** managed via `.env` (template in `env`).
*   **Database Config:** `app/Config/Database.php` (uses `.env` variables).