# LASUCA Controls – Copilot Instructions

## Architecture snapshot
- `index.php` is the live overview: PrototypeJS `Ajax.Updater` polls `data/main.php` every second and swaps the entire dashboard fragment into `<div id="overview_values">`.
- Feature pages under `boilers/`, `tanks/`, `vertical/`, etc. copy the same pattern but point to their own `*main.php` include stacks.
- Each `data/*.php` partial renders a table-driven widget and assumes pre-populated arrays such as `$value`, `$ID`, `$rounded1`; these now come from the shared loaders in `includes/items.php` and `includes/items2dec.php`, which hydrate process tag values from the historians/PLCs before the fragment renders.
- Legacy alternates live in `data/OLD/` for reference—verify changes against their modern counterparts before deleting behavior.

## Data sources & globals
- MySQL connectivity is centralized in `includes/dbinfo.php` / `includes/dbconnect.php`; fragments build short queries (e.g. `includes/w15minavg.php`, `includes/record.php`) with raw `mysqli` calls—close handles once done.
- Sugar-cane totals (`includes/tonsin.php`) come from SQL Server via `sqlsrv_connect`; the PHP `sqlsrv` extension must be installed locally.
- Expect `items.php` to return associative arrays keyed by SCADA tag names (uppercase with spaces or underscores). When adding new metrics, extend that upstream fetch first or guard against missing keys with `isset()`.

## Working with dashboard modules
- New UI blocks belong in `data/` and should mirror the existing table markup + inline PHP echoes; keep row comments (`ROW START/END`) to stay navigable.
- Progress bars rely on CSS IDs declared in `style.css` (`#progressmills`, `#progresstanks`, etc.); reuse existing IDs to inherit sizing.
- Automation/manual status chips are rendered by branching on numeric flags (`0` auto, `1` manual). Follow the color scheme already in `data/boilers*.php` and `data/tablesandtd.php`.
- When you need downtime banners, look at `data/maintenence.php` for the minimal markup.

## Polling & client behavior
- Prototype's `PeriodicalExecuter` schedules refreshes; any new async endpoint should output a full HTML fragment ready for innerHTML replacement and avoid emitting `<html>` or `<body>` tags.
- Avoid long-running queries—each partial runs every second, so cache expensive math in SQL views or upstream collectors.

## Local run & verification
- There is no build step; serve locally with PHP's built-in server from the repo root, e.g. `php -S localhost:8000 -t v:\overviews`. Hit `/index.php` to smoke-test.
- Before shipping, lint touched PHP with `php -l path/to/file.php`; broken includes surface only at runtime, so exercise the page you changed.
- Provide sanitized credentials via environment-driven includes when committing—current repo stores plaintext, so redact them if you regenerate config files.

## Gotchas & tips
- Missing `includes/items.php` or `includes/items2dec.php` will fatal—stub them with dummy arrays when running in isolation.
- Data fragments expect to step up one directory (`../includes/...`) to reach shared helpers; when adding new modules keep that relative pathing consistent.
- Fonts and viewport sizing depend on vw units; test in a 4K display mode if you tweak CSS spacing.
- Keep Ajax endpoints PHP-only—switching to JSON would require rewriting the Prototype update pipeline, so stick with HTML fragments unless you plan a broader refactor.

## Developer tools
- `testall/` - Shows all modular dashboard sections on one page for easier editing. Use this when working on individual modules to see changes in context.

## Deprecated/experimental (ignore)
- `jpowered/` - Unused experiment
- `loaddata/` - Experiment, should be moved to OLD/
- `OLD/` - Legacy files
