servicedesk/CLAUDE.md

CLAUDE.md

Guidance for AI coding agents working in this repo. See README.md for the feature/tech overview, ARCHITECTURE.md for how the app is put together, and install.md for full deployment instructions.

This is a live production system

The only real user today is the owner's own account (client+operator+admin roles). Treat the running database as production, not a sandbox:

• Never create/modify/delete real DB records (users, tickets, settings, etc.) without the user explicitly asking. Don't spin up throwaway test users via php artisan tinker against this DB.
• For UI/CSS verification, prefer an offline static-HTML harness reproducing the real markup+CSS, or ask for test credentials, rather than poking at prod data.
• Production is fronted by Traefik with a private-CA TLS cert (not publicly trusted) — tools like curl/Playwright need -k / ignore_https_errors to hit it directly.

Container operations: use sudo, never build the image locally

All Docker commands against this stack need sudo (e.g. sudo docker compose exec servicedesk ..., sudo docker exec servicedesk-servicedesk-1 ...).

Never run docker build, docker compose build, or --build. The servicedesk image is built by CI (.gitea/workflows/build.yml, triggered on Dockerfile changes on main) and pushed to the Gitea container registry; compose.yaml only ever pulls a tag (sudo docker compose pull && sudo docker compose up -d, see install.md 1.3/1.3a) — building locally would just diverge from what CI produces. The app container (servicedesk-servicedesk-1) mounts ./src from the host over NFS (/mnt/rabbit-containers → NFS export), so plain file edits already take effect with no rebuild or restart:

• Blade/PHP/route edits: just edit the files — live instantly, no restart needed.
• resources/css/app.css / resources/js/* (Vite/Tailwind entrypoints) do need a rebuild — public/build/assets/ is static compiled output. Neither the host nor the app container has Node installed; rebuild with a throwaway container instead of touching the app image:

  sudo docker run --rm -v "$(pwd)/src":/app -w /app node:22 npm run build
  

  (run from the repo root; node_modules already exists, no install needed). Verify via public/build/manifest.json picking up a new hash.
• After running artisan cache commands for diagnostics (config:cache, view:cache), clear them again afterward (config:clear/view:clear) — this app normally runs uncached so edits apply live; leaving a cache on silently breaks that workflow.

Apache /icons/ alias trap

The stock php:apache image enables mods-enabled/alias.conf, which defines Alias /icons/ "/usr/share/apache2/icons/". Any app-level static directory at public/icons/ is silently shadowed by Apache's own stock icon set — requests 404 before ever reaching Laravel, with no useful log line. This project deliberately uses public/pwa-icons/ for PWA manifest icons for exactly this reason — never add a public/icons/ directory.

Established UI conventions

• Post-login redirect always lands on /client (User::defaultArea() in app/Models/User.php), even for accounts holding operator/admin roles too — staff switch areas via the role switcher in the header (resources/views/components/profile-menu.blade.php). Keep /client first-priority in defaultArea() if you add new roles/areas.
• Mobile tables: don't rely on horizontal scroll alone for wide data tables. The established pattern (.table-cards-mobile in resources/css/app.css, @media (max-width:640px)) turns each <tr> into a card with data-label attributes on <td>s. Currently applied to the operator ticket queue; apply the same treatment to any other wide table you add or make mobile-relevant (admin panel tables don't have it yet).

Testing & code style

See TESTING.md and CONTRIBUTING.md — run php artisan test and ./vendor/bin/pint before considering a change done. There is no CI; local test runs are the only gate.