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:

# 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:

# 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:

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:

  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).