# Frontio (Laravel)

The full description of the Laravel version (conversion step 27 in `laravel-conversion-plan.md`) is still to be
written. Until then, the PHP build's `C:\xampp\htdocs\trellislearn\CLAUDE.md` is the best description of how the
system works (read it, don't change it), and the rules below apply here.

## Where things are

- This project: `C:\xampp\htdocs\frontio`, at https://frontio.test (Laravel 13.39, PHP 8.5).
- The old PHP build, no longer used: `C:\xampp\htdocs\trellislearn`, at https://trellislearn-old.test. The
  conversion plan (`laravel-conversion-plan.md`) still lives there.
- `feature-list.md` and `test-notes.md` are in this project (copied from the PHP build on 7 Nov 2026).
- Not live yet: this is still a test system on the user's computer, and there is no live version. The user will
  say when it goes live.
- `SETUP.md`: installing on cPanel hosting.
- Tests: `php artisan test` (about 3 minutes).
- Demo company for car rental prospects: `php artisan frontio:demo-car-rental` (Coastline, at /coastline, 10 employees; add `--fresh` to rebuild it; sign-in names
  and the demo password are at the top of `app/Console/Commands/DemoCarRental.php`).
- The technical document for the architect and test writers: `docs/Frontio-technical-document.docx`, built
  by `tools/technical-document/`. When the system changes, rebuild it from the builder. Word fills in the
  contents page ("Update entire table", then save).

## Decisions

- **Laravel only (since 7 Nov 2026):** the user no longer uses the PHP build. Make every change in this project
  only. Don't change, commit to or update the database of the PHP build (`C:\xampp\htdocs\trellislearn`); it stays
  only as a record of how things worked.
- **Add forms:** an "add" form that would sit below a long list opens as a pop-up (`<dialog>` with `data-open` /
  `data-close`, see `public/assets/app.js`). A form that stays on the page goes at the top, above the list.
- **Data separation (security rule 6):** every data-separation fix gets a permanent test in `tests/Feature`
  (for example `CertificateSiteScopeTest.php`, and `tests/Feature/Separation`).
- **One named employee:** models with the `SiteScoped` trait (such as `Employee`) filter to the person's sites
  automatically. Still use `scoped_employee()` when an action names one employee, so attempts from outside the
  person's sites are refused and recorded in the activity log.

## How to work

- Explain in plain language before editing. Make small changes and commit after each one.
- Ask before changing the database structure, sign-in, roles or data separation, deleting anything, or adding
  libraries.
- Use fake data only, and never touch the live server.
- Say "employee", not "worker".
- Don't add features that weren't asked for: suggest them, and add them to `feature-list.md`
  as Not decided.
- After changing Blade views, run `php artisan view:clear`.
- The browser pane is not signed in. Never type passwords into it: ask the user to sign in, or check the change
  with a temporary feature test (a fake user with a made-up password, deleted afterwards unless worth keeping).
  To check CSS without signing in, add a copy of the markup to the sign-in page with JavaScript (same app.css).
- `docs/~$...docx` is Word's lock file while the user has the document open: don't commit or delete it. Never
  close or touch the user's open Word windows or other applications.
- Always end with what to retest in the browser.

## Testing agents

Two subagents live in `.claude/agents/`. Both use only the test database in `.env.testing`
(`frontio_test`), never change application code, and end with a summary of passed tests, failed
tests and bugs found.

- **backend-tester**: PHPUnit feature tests for the server side. Use it after changing routes, `app/Areas`,
  `app/Helpers`, models, permissions or data rules, or to check sign-in, roles, organization and site separation,
  licences, worker links, courses and SCORM, compliance, the How-to library or the audit log. Fast; run it first.
- **gui-tester**: Playwright journeys in a real browser at phone and desktop sizes, signed in as each role. Use it
  after changing pages, forms, menus or layouts, or before a release to check what people actually see and click.
  Slower; it starts a local test server.

Both use the people from `database/seeders/TestDataSeeder.php` (two organizations, two sites each, one account
per role). Reset the test database with:

```bash
php artisan migrate:fresh --env=testing --seed --seeder=TestDataSeeder --force
```