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.

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.

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.

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.

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.

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.