# LASUCA Shared Endpoint – AI Guide

## Architecture
- Single PHP micro-endpoint; every request enters `public/index.php`, loads config, calls `Lasuca\SharedEndpoint\fetchLatestItems()` from `src/Database.php`, then JSON-encodes the payload.
- No frameworks or Composer setup; stick to core PHP 8+ features already in use (`strict_types`, namespaced functions, `mysqli`).
- Output contract is the canonical data feed for multiple dashboards; preserve field names (`status`, `metadata`, `items`) and the nested keys consumed by clients.

## Data access
- `fetchLatestItems()` opens a short-lived `mysqli` connection using the array returned by `config.php`; closes connections explicitly after the query.
- Query targets the `items` table ordered by `ID`; schema is assumed to expose `ID`, `Name`, `Value`, and `Timestamp`. Add columns by extending both the `SELECT` statement and the array mapping.
- Values are normalised before returning: `tagId` → int, `value`/`rounded1`/`rounded2` → float, `timestamp` stays as the DB-provided string. Keep these conversions when expanding the payload.

## Configuration & caching
- `config.php` reads environment variables (`LASUCA_DB_*`, `LASUCA_CACHE_TTL`) with sensible on-prem defaults; prefer overriding via env vars rather than editing the file.
- `LASUCA_CACHE_TTL` controls both the config cache and the HTTP `Cache-Control` header (currently hard-coded to `1` second in `public/index.php`). Align these when making caching changes.

## Response handling
- Success responses include `metadata.generatedAt` as an ISO 8601 (UTC) timestamp via `gmdate(DATE_ATOM)` and `metadata.count` from `count($items)`.
- Errors are caught in `public/index.php`: respond with HTTP 500 and a JSON body `{ "status": "error", "message": ... }`. Preserve this shape so clients can detect failure without parsing HTML.
- Use `JSON_PRETTY_PRINT` when changing serialization to keep human-readable outputs during troubleshooting.

## Local workflows
- Serve locally from the parent directory with `php -S localhost:8081 shared-endpoint/public/index.php`; this mimics production routing without extra tooling.
- Database connectivity is the only external dependency; mock or stub calls by swapping `fetchLatestItems()` for a fixture in tests or by wrapping the function in a seam.

## Extension tips
- When adding new endpoints, follow the same pattern: thin public script, shared logic in `src/` under the `Lasuca\SharedEndpoint` namespace, and configuration driven by env-aware arrays.
- Keep new helpers free of side effects beyond DB reads so downstream caching remains predictable.
- Document any new environment variables in both `config.php` comments and the top-level `README.md` so operators stay in sync.