Kacper
13a758779d
Some checks failed
Build and push image / build (push) Failing after 3m17s
Documentation overhaul (TESTING/CONTRIBUTING/ARCHITECTURE/SECURITY/CLAUDE.md, CHANGELOG.md, drop unmaintained src/README.md) plus CI-built Docker images: Gitea Actions now builds and pushes the servicedesk image to the Gitea container registry on Dockerfile changes, and compose.yaml pulls that image instead of building locally. No application behavior changes. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for AI coding agents working in this repo. See [README.md](README.md)
|
|
for the feature/tech overview, [ARCHITECTURE.md](ARCHITECTURE.md) for how the app
|
|
is put together, and [install.md](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 `pull`s a tag (`sudo docker compose pull && sudo docker
|
|
compose up -d`, see [install.md](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:
|
|
```bash
|
|
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](TESTING.md) and [CONTRIBUTING.md](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.
|