# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **CodeIgniter 4** PHP application for laboratory management (GDC CMOD - Laboratory Request Management System). It handles specimen collection tracking, request validation, and result management with role-based access control.

## Development Commands

```bash
# Run PHP built-in server (from project root)
php spark serve

# Run tests
composer test
```

**Note:** This is a Windows-based deployment using IIS/XAMPP. For production, configure a virtual host pointing to the `public/` folder.

## Database Configuration

- **Primary DB:** SQL Server (`GDC_CMOD.dbo`) via Microsoft ODBC Driver (MSOLEDBSQL)
- **Legacy DB:** Firebird/InterBase (`GLENEAGLES` via ODBC) for patient data
- **Connection:** `\Config\Database::connect()` returns MySQLi connection
- **No CI4 Models** - uses raw SQL queries via `Database::connect()`

## Architecture

### Role-Based Access Control (RBAC)

| Role ID | Name | Route Prefix | Permissions |
|---------|------|--------------|-------------|
| 0 | Superuser | `/superuser` | Full access + Users CRUD |
| 1 | Admin | `/admin` | Full access + Users CRUD |
| 2 | Lab | `/lab` | Request validation, Sample collection |
| 3 | Phlebo | `/phlebo` | Request validation, Sample collection |
| 4 | CS | `/cs` | Request validation, Sample collection |

### Authentication Flow

1. `Auth::login()` - Verifies credentials against `GDC_CMOD.dbo.USERS`, sets session
2. `RoleFilter` - Checks `session()->get('isLoggedIn')` and role ID
3. `GuestFilter` - Redirects logged-in users to role-based dashboard

### Key Database Tables

- `GDC_CMOD.dbo.USERS` - Users with `USERID`, `USERROLEID`, `PASSWORD`
- `GDC_CMOD.dbo.CM_REQUESTS` - Validation tracking (`ISVAL1`, `ISVAL2`, validation users/dates)
- `GDC_CMOD.dbo.TUBES` - Sample collection status
- `GDC_CMOD.dbo.V_DASHBOARD_DEV` - Dashboard data view
- `glendb.dbo.*` - Legacy Firebird patient data

### Request Validation (Dual-Level)

Validation requires 2 different users to validate the same request:
1. First validation sets `ISVAL1=1`, `VAL1USER`, `VAL1DATE`
2. Second validation (different user) sets `ISVAL2=1`, `VAL2USER`, `VAL2DATE`

## Code Conventions

### Controllers
- All extend `BaseController` (which extends `CodeIgniter\Controller`)
- Use `ResponseTrait` for JSON APIs
- Raw SQL queries via `\Config\Database::connect()->query()`

### Routing Pattern

```php
$routes->group('prefix', ['filter' => 'role:N'], function($routes) {
    $routes->get('', 'Controller::index');
    $routes->get('api/resource', 'Controller::method');
});
```

### Session Structure

```php
session()->set([
    'isLoggedIn' => true,
    'userid' => (string) $user['USERID'],
    'userroleid' => (int) $user['USERROLEID'],
    'userrole' => (string) $role,
]);
```

## Important Routes

| Route | Purpose |
|-------|---------|
| `/login`, `/logout` | Authentication |
| `/label/coll/:accessnumber` | Zebra printer label (public) |
| `/api/requests` | Dashboard data (date-filtered) |
| `/api/requests/validate/:accessnumber` | Dual-level validation |
| `/api/samples/collect/:accessnumber` | Mark sample collected |
| `/api/samples/receive/:accessnumber` | Mark sample received (Admin/Superuser only) |

## Frontend Stack

- TailwindCSS + DaisyUI 5 (CDN)
- Alpine.js for reactivity
- Font Awesome 7 for icons

## Common Patterns

### JSON API Response
```php
return $this->response->setJSON(['status' => 'success', 'data' => $result]);
```

### Database Query
```php
$db = \Config\Database::connect();
$result = $db->query("SELECT * FROM table WHERE col = ?", [$value])->getResultArray();
```

### Date Formatting from SQL Server
```php
$row['DATE_COLUMN'] = date('Y-m-d H:i', strtotime($row['DATE_COLUMN']));
```