servicedesk/ARCHITECTURE.md

# Architecture

Server-rendered Laravel + Livewire app (no SPA/API-driven frontend for the app
itself — the REST API in `routes/api.php` exists purely for external
integrations). See [README.md](README.md) for the feature list and tech stack;
this doc covers how the pieces fit together.

## Request flow

1. `routes/web.php` gates every area behind `auth` + a role middleware
   (`role:client`, `role:operator`, `role:admin` → `App\Http\Middleware\EnsureRole`),
   which checks the role against `$user->roles`. A user can hold multiple roles at
   once; the router just requires *one* of the listed roles per route group.
2. Each route resolves to a full-page Livewire component under
   `app/Livewire/{Client,Operator,Admin,Auth}/` — there are no traditional
   controllers rendering Blade views for these areas (the REST API in
   `routes/api.php` is the exception, backed by `app/Http/Controllers/Api/`).
3. Livewire components call into `app/Services/TicketService.php` for anything
   that mutates ticket state (create/transition/reply/notify) rather than
   mutating models directly — keep that convention when adding new mutations so
   notification/history/SLA side effects stay in one place.
4. `App\Providers\AppServiceProvider::boot()` runs a settings override pass on
   every request (`applyLdapSettingsOverride`, `applyMailSettingsOverride`,
   `applySessionSettingsOverride`, `applyTimezoneSettingsOverride`) — see
   "Settings override" below.

## Data model

Core tables/models (`app/Models/`):

```
Category ─< Subcategory ─< CustomField        (per-subcategory custom fields)
                 │
                 └──< Ticket >── Team          (subcategory routes to a team)
                          │
                          ├──< TicketMessage   (public replies + internal notes)
                          ├──< TicketAttachment
                          ├──< TicketHistory
                          ├── customer/assignee → User
                          ├── status  → Status   (fixed stages: new/open/closed)
                          ├── priority → Priority → SlaRule (response/resolution minutes)
                          └── csat_rating/csat_comment/csat_rated_at (nullable — set once, on close)

User ─< UserFieldValue >─ UserField
User ─< SavedQueueView                          (operator's own saved queue filter/sort/column presets)
User ─< notifications (Laravel's database channel — polymorphic, morph-mapped as 'user')
ApiClient                                       (Sanctum token owner, ability-scoped)
Setting                                          (single-row-per-key config store, see below)
ReplyQuickAction, ResponseTemplate, EmailTemplate, NotificationSetting
```

`tickets.subject`/`tickets.body` and `ticket_messages.body` carry a MySQL/MariaDB
`FULLTEXT` index (added in a later migration, MySQL-only — absent on the sqlite
connection the test suite runs on) — `Ticket::scopeSearch()` uses
`whereFullText()` when the active connection is `mysql` and falls back to a
portable `LIKE` otherwise, so the same call site works in both places.

`Ticket` (`app/Models/Ticket.php`) is the largest model — it owns SLA math
(`slaInfo()`, `isOverdue()`, `resolutionDeadline()`), status/priority display
helpers (`statusLabel()`, `tagStyleFromColor()`), operator-visibility scoping
(`scopeVisibleToOperator`, `isVisibleToOperator` — a team member sees their team's
queue + unassigned + anything assigned to them, an admin sees everything), and
work-timer tracking (`timerElapsedSeconds()`). Keep ticket-shaped logic here
rather than spreading it across Livewire components.

## Ticket numbering & URLs

A ticket carries three distinct identifiers, each with a different job:

- **`id`** — the DB primary key. Never shown to users; the REST API
  (`routes/api.php`) is deliberately pinned to it (`{ticket:id}` explicit
  binding on every `{ticket}` route) so external integrations have a stable
  contract regardless of the numbering settings below.
- **`number`** — a plain sequential string (`Ticket::nextNumber()`, max+1
  starting at 1001), unique but otherwise unremarkable. Backs `scopeSearch()`
  and the numeric sort in `Operator/Queue.php` regardless of display mode.
- **`checksum`** — a 6-digit HMAC-derived value (salted with `app.key`,
  keyed off `id`), assigned once in a `Ticket::booted()` `created` listener
  and never changed afterward. Collisions are handled for real, not just
  assumed away: `Ticket::generateUniqueChecksum()` walks a nonce forward
  until the candidate is free (checked against the DB), and the column has a
  `unique()` constraint as a hard backstop.

`Ticket::displayNumber()`/`formattedNumber()` pick between `number` (zero-padded
to `Settings::get('ticket_number_min_length')`) and `checksum` based on
`Settings::bool('ticket_number_obfuscate')` — the "Ukryj kolejność zgłoszeń"
toggle in Admin > Konfiguracja. `Ticket` also overrides `getRouteKey()` and
`resolveRouteBinding()` to mirror that same choice, so **the web routes**
(`routes/web.php`, all plain `{ticket}` implicit bindings — no explicit field)
resolve and generate URLs against whichever column is currently the display
number: flip the setting and both the visible number *and* every link
(`route('client.ticket', $ticket)` etc.) switch together, and a bookmarked URL
built under the old mode stops resolving. This is why the API routes need the
explicit `{ticket:id}` override — without it, the same global `getRouteKey()`
change would silently start requiring `number`/`checksum` in API path params
too, breaking the documented `integer` "Ticket id" contract.

The `{numer}` placeholder available in admin-editable e-mail templates
(Admin > Szablony e-mail / Wyzwalacze) resolves to `formattedNumber()`
*without* `displayNumber()`'s prefix — those templates already hardcode their
own `#{numer}`, so adding the prefix there too would double it up or clash
with a non-default prefix.

A ticket route binding that resolves to nothing (most commonly: the ticket
was deleted while someone had it open, and a later request — typically
Livewire's own "model missing during hydration" recovery, which does a full
`window.location.reload()` of the same page — hits `{ticket}` again) no
longer surfaces Laravel's default 404 page. `bootstrap/app.php` registers a
`NotFoundHttpException` render callback (note: `Handler::prepareException()`
already converts `ModelNotFoundException` into `NotFoundHttpException`,
wrapped as `getPrevious()`, *before* any render callback runs — a callback
typed against `ModelNotFoundException` itself would never match) that
redirects to `operator.queue`/`client.dashboard` instead, for any
authenticated request under `operator/*`/`client/*`.

## Roles & permissions

`$user->roles` reads/writes as a plain array (`['client', 'operator']`), but
it's a **virtual attribute** (`User::getAttribute()`/`setAttribute()`
overrides) backed by a real `roles` lookup table + `role_user` pivot, not an
actual column — assigning `'roles' => [...]` on create/update stashes the keys
until the model's `saved` hook resolves them against `roles.key` and syncs the
pivot. This matters for tests/seeders: a role key must exist in the `roles`
table *before* it can be assigned this way, or the assignment silently becomes
a no-op (`Tests\TestCase::setUp()` seeds the 3 fixed roles for exactly this
reason, since almost every test creates a role-bearing user). Checked via
`EnsureRole` at the route level. Every account gets `client` by default
(`App\Ldap\Handlers\AssignDefaultRole` for LDAP-provisioned accounts); staff
switch areas via the header role switcher, but always land on `/client` first
after login.

## Authentication

`config/auth.php` defines the default `web` guard against an LDAP-backed user
provider (LdapRecord); a plain Eloquent provider is kept alongside it only for
local tooling/tests that don't hit a directory. In production, LDAP bind is the
primary path; the local fallback account (`admin@example.com` from the seeder)
authenticates against a local password when the LDAP bind doesn't match — this is
the account used for first login after a fresh install (see
[install.md](install.md)).

`app/Ldap/Handlers/` hooks into LdapRecord's import/sync events:
`AssignDefaultRole` grants the `client` role to new LDAP-provisioned accounts,
`SyncUserFieldsFromLdap` keeps `UserFieldValue` rows in sync with directory
attributes.

## Settings override ("live config")

`App\Support\Settings` (`app/Support/Settings.php`) is a cached key/value reader
over the `settings` table, with hardcoded defaults for every key (company name,
LDAP/SMTP connection details, attachment limits, session lifetime, timezone,
branding/email HTML, etc.). Admin > Konfiguracja (general/attachments/session),
Poczta (SMTP) and Integracje (LDAP, BookStack) all write to this same table, and
`AppServiceProvider::boot()` re-applies the relevant subset of it over
`config()` on every request — meaning **`Setting` rows win over `.env`** for
LDAP, mail, session lifetime and timezone once they're non-empty. This is by
design (lets an admin reconfigure LDAP/SMTP without a redeploy) but is also the
source of the "seeded placeholder overrides real `.env` values" gotcha
documented in [install.md](install.md) — anything touching LDAP/mail/session/
timezone config should go through `Settings`, not raw `config()`/`.env` reads.

`settingsTableUsable()` gates all four overrides on whether the `settings`
table is safe to query yet — but is deliberately scoped to just the `migrate`
command family (`runningConsoleCommand('migrate', 'migrate:fresh', ...)`), not
"any console command". It used to blanket-skip for every console invocation
(exempting only unit tests), which silently broke every scheduled command's
outbound mail: `AppServiceProvider::boot()` runs on each process including
`schedule:run`-invoked commands, so `tickets:check-sla-breaches`,
`automation:run-rules` and `emails:fetch-imap` (below) all sent notifications
through whatever `.env`'s `MAIL_MAILER` happened to be (`log`, i.e. nowhere)
instead of the admin-configured SMTP server — with no error, since the `log`
mailer never throws. If a scheduled command's notification/lookup ever again
seems to silently use `.env` defaults instead of `Settings`, check here first.

## Notifications

`TicketService::notify(Ticket $ticket, string $triggerKey)` is the single
fan-out point for every ticket lifecycle event (see the `NotificationSetting`
rows seeded per trigger key) — it resolves the configured recipient
(`$ticket->assignee` or `$ticket->customer`) to a real `User` when one exists
and calls `$user->notify(new TicketNotification(...))`, which fires **both**
the `mail` and `database` channels (`App\Notifications\TicketNotification`) —
there's no separate on/off switch for in-app vs. e-mail, the same
`NotificationSetting.enabled` flag gates both. A guest customer with no
account still gets routed anonymously (`Notification::route('mail', $email)`,
mail-only — the database channel needs a real notifiable to attach the row
to). `TicketNotification` is constructed with an explicit `$recipientRole`
('client'|'operator') rather than inferring it from the notifiable's roles,
since one account can hold both — this decides whether the ticket link (both
the e-mail body and the in-app notification's `url`) points into `/client/...`
or `/operator/...`.

## Real-time broadcasting (Reverb)

Two private channels, authorized in `routes/channels.php`:

- **`operator.queue`** — one shared channel for every operator/admin (not
  scoped per team/ticket), so the receiving `Operator\Queue` component just
  re-queries through its own already-correct `Ticket::scopeVisibleToOperator()`
  on any event instead of the channel-auth callback needing to duplicate that
  ACL logic. Payloads stay minimal (ticket id + reason + actor id) for the
  same reason.
- **`ticket.{id}`** — per-ticket channel for the message thread and detail
  changes, authorized for an operator with `isVisibleToOperator()` **or** the
  ticket's own customer (OR, not else-if — the one real account in this app
  holds both roles at once). An internal note broadcasts on the same channel
  a client can subscribe to, but the payload never carries the message body —
  each side's Livewire component only ever re-queries whatever its own
  already-authorized computed property returns, so there's nothing to leak.

Two events, both `App\Events\TicketQueueChanged` (broadcasts on **both**
channels above — a status/priority/team/assignee change needs to reach a
client watching their own ticket too) and `App\Events\TicketMessagePosted`
(broadcasts on `ticket.{id}` only). Both implement `ShouldBroadcastNow`, not
`ShouldBroadcast` — this app runs with no queue worker by design (see
`TicketNotification`), so broadcasting happens synchronously within the
request like everything else here. `TicketService` dispatches both from every
ticket-mutating method (create/setStatus/setPriority/setAssignee/setTeam/
operatorReply/operatorNote/clientReply/apiMessage/merge); the two ad hoc
delete call sites (`Operator\Queue::confirmDeleteSelected()`,
`Operator\TicketShow::confirmDeleteTicket()`) dispatch `TicketQueueChanged`
directly since there's no `TicketService::delete()` to hook into.

Browser side, `resources/js/echo.js` bridges Reverb events into plain
Livewire events (`Livewire.dispatch('queue-changed', ...)` /
`'ticket-message-posted'`) rather than using the `#[On('echo-private:...')]`
attribute directly — version-agnostic, and each Livewire component just
declares a plain `#[On(...)]` listener that no-ops if the payload's `actorId`
matches the viewer's own id (self-echo suppression) or the ticket id doesn't
match the component's own ticket. Two easy-to-reintroduce bugs to know about
if "nothing updates live" ever comes back:

1. **CSRF on `/broadcasting/auth`.** Echo's private-channel subscription
   POSTs there under the app's normal CSRF middleware; the `Echo` constructor
   must pass `auth.headers['X-CSRF-TOKEN']` (read from the `<meta
   name="csrf-token">` tag in `layouts/app.blade.php`) or every subscription
   attempt is silently rejected.
2. **Script load order.** `resources/js/app.js` (which imports `echo.js`)
   loads via `@vite` as `type="module"`, which the HTML spec defers until
   after the document is parsed — meaning Livewire's own bootstrap script
   (`@livewireScripts`, a plain synchronous `<script>` near the end of
   `<body>`) has already run by the time `echo.js` executes. Don't gate
   anything in `echo.js` behind `document.addEventListener('livewire:init',
   ...)` — that event fires as part of Livewire's own (earlier) script, so a
   listener registered this late permanently misses it. The one place this
   still matters is the per-ticket subscription triggered from a Livewire
   `@script` block in the ticket-show views, which can run before or after
   `echo.js` depending on exactly when Livewire processes it — it queues the
   ticket id onto `window.__pendingTicketChannelIds` if `echo.js` hasn't
   defined `window.subscribeToTicketChannel` yet, and `echo.js` flushes that
   queue once it has.

As a defense against a dropped websocket connection (backgrounded tab,
network blip), the operator queue and both ticket-detail views also poll
themselves every 30–60 seconds via a small Alpine countdown calling
`$wire.refreshQueue()` / `$wire.refreshTicketData()` — broadcasting is
best-effort, not the only way these views ever update.

A third private channel, **`App.Models.User.{id}`** (Laravel's default
per-notifiable convention, kept verbatim rather than a shorter alias),
carries realtime bell delivery: `AppServiceProvider::broadcastBellNotifications()`
listens for the framework's own `NotificationSent` event, and — only for the
`database` channel of a `TicketNotification` — dispatches `NotificationCreated`
on the recipient's own channel. This is a single choke point rather than
threading a broadcast call into every `TicketService` notification call site
(including the Trigger engine's `send_notification` action, below).
`resources/js/echo.js` bridges it into a `bell-notification-received` Livewire
event (refreshing `NotificationBell` instantly) and, if the viewer opted in via
the toggle on `/settings/notifications`, also raises a native in-tab
`Notification` popup — no service worker or push subscription, so this only
fires while the tab is open, same limitation as the other Echo listeners here.

## SLA

`SlaRule` holds per-priority response/resolution targets in minutes. The
scheduled command `tickets:check-sla-breaches` (registered in
`routes/console.php`, run every 15 minutes via `schedule:run`) flags overdue
tickets and can notify the assigned operator — see [install.md](install.md) for
why this requires an external cron entry (the Docker image ships no
cron/supervisor of its own).

## SLA automation rules

`AutomationRule` (label, `condition_minutes`, optional `scope_priority_key`/
`scope_subcategory_id`/`scope_team_id`, `action_type` + `action_value`) lets an
admin configure "if a ticket has been silent for N minutes, change its
priority/status/team/assignee" without code — Admin > Automatyzacja SLA. The
scheduled command `automation:run-rules` (also every 15 minutes) evaluates
every enabled rule against `Ticket.last_customer_activity_at` (falling back to
`created_at` if never set — mirrors how `resolutionDeadline()` treats a
missing `SlaRule` as "no SLA" rather than backfilling one), and applies a
match through the same `TicketService` setters a manual operator action would
use, so the automated change gets the same history entry, notification, and
broadcast for free. Idempotency is a per-(rule, ticket) row in
`automation_rule_ticket_logs`, cleared by `TicketService` whenever the silence
that triggered it is broken (a fresh `clientReply()`) or the ticket
closes/reopens (`setStatus()`) — so a rule can fire again after a new period
of silence instead of being permanently latched. Multiple matching rules on
the same ticket in the same run all fire independently, in `id` order; a rule
that closes the ticket doesn't block earlier-ordered rules already applied
this run, but a later rule's own query naturally excludes an already-closed
ticket.

## IMAP e-mail intake

Optional, off by default (`ImapMailbox.enabled` per row — there is no single
global toggle since this is a list of N mailboxes, not a `Settings`
singleton). Split across three layers, mirroring the plan that shipped it:

- **`App\Models\ImapMailbox`** — one row per polled mailbox (host/port/
  encryption/username, `password` cast `'encrypted'` — the first model in
  this codebase to use Laravel's native encrypted cast rather than the
  manual `Crypt::` pattern `Settings` uses, since this is a list of records
  rather than key/value config). `default_subcategory_id` XOR
  `default_category_id` (enforced by the admin form's single combined
  selector, not a DB constraint) route new tickets; `category_id` only ever
  gets populated when there's no subcategory to derive one from (see
  `Ticket::categoryLabel()`/`TicketService::create()`).
- **`App\Services\ImapMessageClassifier`** — pure decision logic, no IMAP
  connection, fully Pest-testable: `rejectionReason()` (auto-reply/bounce
  detection via `Auto-Submitted`/`Precedence`/`X-Autoreply` headers + EN/PL
  subject phrases + a per-mailbox sender blocklist), `matchTicket()`
  (extracts every digit run ≥4 chars from the subject — after stripping
  `Re:`/`Odp:`/`Fwd:`/`FW:`/`Aw:` — and tries each through
  `Ticket::resolveRouteBinding()`, so it transparently matches either the
  plain sequential number or the obfuscated checksum, whichever mode is
  active; no changes to outbound mail were needed since every notification
  subject already carries `{numer}`), `isSenderAllowed()` (mirrors
  `Landing::emailIsKnown()` — enforces `restrict_tickets_to_ldap` for e-mail
  exactly like the guest web form), `resolveSender()` (existing local user,
  or `LdapUserProvisioner::findOrCreateByEmail()` if enabled).
- **`App\Services\ImapMailboxFetcher`** — the I/O layer (`webklex/php-imap`,
  a pure-PHP IMAP client with no `ext-imap` dependency — confirmed available
  extensions were sufficient, no Dockerfile change needed). Fetches
  `whereUnseen()` per mailbox, flags/moves a message **before** creating the
  ticket (a crash mid-batch then risks a "processed but no ticket" message —
  visible and easy to fix manually — rather than a duplicate ticket on the
  next run), converts attachments to `UploadedFile` via a temp file (`$test
  = true` bypasses the `is_uploaded_file()` check outside a real HTTP
  request) so they flow through the existing `Settings::validateAttachments()`
  + `TicketService::attachFiles()` unchanged. Logs every connection attempt
  and per-message decision to a dedicated `imap` log channel
  (`storage/logs/imap-*.log`, always `debug` level regardless of the app's
  own `LOG_LEVEL` — see `config/logging.php`) since this app commonly runs
  at `LOG_LEVEL=error`, which would otherwise silently swallow this
  activity entirely.
  - One real bug worth remembering if IMAP rejection logic ever seems too
    aggressive again: Webklex's `Header::get($name)` returns an *empty*
    `Attribute` (not `null`) for a header that isn't present at all, and
    `Attribute::first()` on that empty instance is `''`, not `null` — a
    naive `$header !== null` check therefore treats *every* message as
    carrying *every* header. Guarded in two places: `ImapMailboxFetcher`
    only keeps a header value that's non-empty, and
    `InboundEmail::header()` itself also treats `''` as absent, so the bug
    can't resurface even if some other header source stops filtering.
- **`TicketService::guestReply()`** — the one new method added to the
  existing service: a customer reply with no `User` account (mirrors
  `clientReply()` — real customer activity, resets SLA silence, fires
  `comment_added` so an admin-configured Trigger can reopen a closed ticket
  — rather than `apiMessage()`, which tags a system/integration note, not
  client content). Both `clientReply()` and `guestReply()` take an optional
  trailing `string $source = 'web'`, stored as `TicketMessage.source`
  (`null` for `'web'`) — the per-message counterpart to `Ticket.source`,
  since a ticket opened on the web can later get an e-mail reply or vice
  versa. Both surface as a small mail-icon badge (operator queue: next to
  the ticket number; ticket view: per-message in the thread, plus a tag next
  to the ticket number in the header).
- **`emails:fetch-imap`** (`app/Console/Commands/FetchImapEmails.php`),
  registered in `routes/console.php` as
  `Schedule::command('emails:fetch-imap')->everyFiveMinutes()->withoutOverlapping()`
  — the one scheduled command in this app that opts into
  `withoutOverlapping()` (SLA/automation don't), given IMAP I/O latency.
  Early-returns if no `ImapMailbox` is enabled. Also callable directly per
  mailbox from Admin > Poczta's "Pobierz teraz" button
  (`ImapMailboxFetcher::fetchMailbox()`, bypassing the enabled-only
  `fetchAll()` used by the schedule) for on-demand fetching/diagnosis
  without shell access.

Requires the same external `schedule:run` cron entry as SLA/automation (see
[install.md](install.md) and the crontab note in
[CLAUDE.md](CLAUDE.md)) — without it, only the manual "Pobierz teraz" button
does anything.

## API

`routes/api.php` + `app/Http/Controllers/Api/` expose a small ability-scoped REST
surface over Sanctum tokens (`tickets:read`, `tickets:write`,
`dictionaries:read`, `users:read`), issued via admin-managed `ApiClient` records.
Rate limiting is configured per-client (120 req/min keyed by client ID) vs. a
tighter per-IP limit for unauthenticated requests
(`AppServiceProvider::configureApiRateLimiting()`). Interactive docs are
generated by L5-Swagger at `/admin/api-docs`; there is no static Markdown API
reference in-repo.

## BookStack integration

`App\Services\BookStackClient` is the only outbound HTTP client in the
codebase (Laravel's `Http` facade) — everything else here only ever receives
requests. It's entirely `Settings`-driven, no `.env`/`config()` involved:
`bookstack_enabled`, `bookstack_base_url`, `bookstack_token_id`/
`bookstack_token_secret` (encrypted, same as the LDAP/SMTP passwords),
`bookstack_verify_ssl`, `bookstack_search_types` ('both'|'page'|'book'), and
**two independent** allow-lists of BookStack shelf IDs —
`bookstack_allowed_shelf_ids_creation` (ticket-wizard suggestions) and
`bookstack_allowed_shelf_ids_ticket_view` (the operator's sidebar on an
existing ticket) — `search()` takes a `$context` (`CONTEXT_CREATION` /
`CONTEXT_TICKET_VIEW`) that selects which one applies. **An empty allow-list
means "search nothing"**, not "search everything" — nothing is ever
suggested until an admin explicitly opts shelves in, independently per
context. BookStack has no "which shelf is this book on" field in its own
search response, so `BookStackClient` fetches `/api/shelves` +
`/api/shelves/{id}` once (cached 30 min) into a shelf→book-ids map, used both
to resolve the allow-list to book IDs and to build the "Shelf > Book"
breadcrumb shown next to each suggestion. Per-query search results are cached
10 minutes, keyed on the query text **and** the active allow-list, so toggling
which shelves are allowed is reflected immediately instead of serving a
pre-change result for up to 10 minutes.