servicedesk/README.md

Servicedesk

Helpdesk / ticketing system built with Laravel + Livewire (Polish UI). Clients submit support tickets, operators triage and resolve them inside team queues, and admins configure everything else — categories, SLA rules, templates, branding, LDAP/SMTP, and a REST API for external integrations.

Roles & areas

The app has three areas, gated by role (a user can hold more than one at once):

Area	Route prefix	Who	What they do
Client	/client	client	Submit tickets, track status, reply, see resolution
Operator	/operator	operator	Work the ticket queue, reply/resolve, see team statistics
Admin	/admin	admin	Configure categories, users, teams, SLA, templates, triggers, branding, LDAP/SMTP/BookStack

Every account gets the client role by default (see AssignDefaultRole for LDAP-provisioned accounts), and always lands on /client first after login regardless of what other roles it also holds — staff switch into Operator/Admin via the role switcher in the header. See wiki/client, wiki/operator, and wiki/admin for role-specific how-to guides.

Feature overview

• Tickets — number, subject, body, category/subcategory, status, priority, team, assignee, custom fields (per subcategory), attachments, full message thread (public replies + internal notes), history log, merge, delete.
• SLA — per-priority response/resolution time targets; a scheduled command (tickets:check-sla-breaches, every 15 min) flags overdue tickets and can notify the assigned operator.
• SLA automation rules (Admin > Automatyzacja SLA) — configurable rules that change a ticket's priority/status/team/assignee after N minutes of customer silence (optionally scoped to a priority/category/team), evaluated every 15 minutes (automation:run-rules). Reuses the same TicketService setters a manual operator action would, so an automated change gets the same history entry, notification, and live broadcast as a human doing it; each rule fires once per ticket until a fresh customer reply or a close/reopen resets it.
• Real-time updates — the operator ticket queue and both ticket-detail views (operator and client) update live over WebSockets (Laravel Reverb): new tickets, status/priority/team/assignee changes, and new replies ("live chat") all show up without a manual refresh. A periodic fallback refresh (with a visible, clickable countdown badge — click it to fetch immediately and reset the countdown) covers a dropped websocket connection. All of the refresh/poll intervals in the app, browser-side and the background scheduled commands alike, are configurable from Admin > Konfiguracja (see below).
• Categories & custom fields — admin-defined categories/subcategories, each with its own set of custom fields (text/textarea/select/checkbox/date/number) and an optional default priority.
• Teams — subcategories auto-route to a team; operators only see their own team's queue (plus unrouted tickets and anything assigned to them) unless they're an admin. Reassigning a ticket to a team, though, is unrestricted — an operator can route a ticket to any team, not just one they belong to.
• Templates — canned response snippets for the reply box, admin-configurable "quick actions" (send + transition status in one click), and HTML e-mail templates for every ticket lifecycle event (created, status/priority/category/ team changed, closed, operator replied, SLA breached), each independently enable/disable-able.
• Operator statistics (/operator/stats) — filterable dashboard (date range, team, priority, category, assignee) organized into sections: KPI tiles (volume, SLA breach rate, average first-response/resolution time, CSAT); breakdowns by status, priority, category and subcategory; team/operator workload; top 10 clients by ticket volume plus a client × subcategory cross-tab (top 5 subcategories, rest folded into "Inne"); CSAT average by team and by operator; and a daily created-vs-closed trend.
• Branding & config — company name/logo/favicon/accent color, login notice, e-mail layout/footer, SMTP connection (Admin > E-MAIL), attachment limits, session lifetime, timezone (Admin > Konfiguracja), and LDAP connection + user sync + BookStack (Admin > Integracje).
• LDAP auth — logins bind against an LDAP/LLDAP directory (config/auth.php, config/ldap.php); local accounts (e.g. the emergency admin account) fall back to e-mail + local password when the LDAP bind doesn't match.
• Triggers (Admin > Wyzwalacze) — event-driven business rules that fire immediately on a ticket lifecycle event (created, any field updated, status/ priority/assignee/team/category changed, new public reply): AND-combined conditions gate a sequence of actions (set status/priority/team/assignee, or send an e-mail using a dedicated set of freely add/edit/delete-able trigger e-mail templates, kept separate from the fixed per-event system templates). Complements the time-based SLA automation rules above rather than replacing them.
• Ticket watching — operators can star/"Obserwuj" any ticket to follow it regardless of assignment/team, which feeds the "Obserwowane zgłoszenia" scope in their notification preferences.
• Per-user notification preferences (/settings/notifications) — each operator/admin chooses, per event category (new ticket, ticket update, escalation), which scope of tickets (mine, unassigned, watched, all) notifies them via the in-app bell, and whether that also sends an e-mail; plus an opt-in toggle for native in-tab browser push notifications.
• REST API (/api/v1/..., Sanctum token auth, ability-scoped: tickets:read, tickets:write, dictionaries:read, users:read) for tickets/messages/users/ categories/statuses/priorities/teams — issued via admin-managed API clients. Interactive docs (L5-Swagger) at /admin/api-docs.
• PWA — installable manifest + icons for the client-facing area.
• In-app notifications — a bell in the top bar (client/operator/admin areas) backed by Laravel's database notification channel, alongside the existing e-mail notifications (same per-trigger enable toggle drives both); shows unread notifications only — reading one removes it from the list. Updates live over WebSockets the moment a notification is created (with a 30s fallback poll), and can optionally raise a native browser push notification while the tab is open (see per-user notification preferences above). Includes a dedicated trigger notifying every operator on a team whose subcategories match a newly created ticket.
• Attachments — drag-and-drop upload (in addition to the file picker); every attachment shows in the message thread as just its filename, opening in a new tab on click (no inline image preview).
• E-mail intake (IMAP) (optional, off by default) — clients can create tickets or reply to an existing one just by sending/replying to an e-mail; configure any number of mailboxes in Admin > Poczta (e.g. one address per team), each routed to a specific subcategory or a whole category. A reply is matched back to its ticket via the number/checksum already present in every notification's subject; automatic replies (autoresponders, bounces) are detected and rejected instead of creating junk tickets, and the "restrict tickets to LDAP" setting is enforced for e-mail exactly like the guest web form. A manual "Pobierz teraz" button fetches immediately outside the 5-minute schedule; all activity is logged separately to storage/logs/imap-*.log. Tickets/messages that came in by e-mail show a small mail-icon badge in the operator queue and ticket view.
• Configurable ticket numbering (Admin > Konfiguracja) — a custom prefix and minimum zero-padded length for the ticket number, plus an optional "hide ticket order" mode that displays a stable per-ticket checksum instead of the sequential number. When enabled, ticket URLs switch to the same checksum too, so the number in the link always matches the one on the page; the REST API is unaffected and always addresses tickets by id.
• Customer satisfaction (CSAT) — clients rate a ticket 1–5 stars (+ optional comment) once it's closed; average/response-rate surfaced as a KPI on the operator stats dashboard, with a link in the "ticket closed" e-mail.
• Saved queue views — operators can save their current filter/sort/column combination in the ticket queue, mark one as default, and switch between them.
• Full-text search — MySQL/MariaDB FULLTEXT search (with a portable LIKE fallback) across ticket subject/body and reply message bodies, available in both the operator queue and the client's own ticket list.
• Stats export — the operator stats dashboard can export the currently filtered ticket set as CSV.
• BookStack knowledge-base integration (optional, off by default) — suggests relevant BookStack articles by category/subcategory while a ticket is being created, and in a separate sidebar panel on an existing ticket for both operators and clients (with a copy-link button for operators). Loads in after the page's first paint rather than blocking it. Configured entirely from Admin > Integracje: connection + API token, optional SSL-verification bypass for self-signed instances, a content-type filter (books/pages/ chapters, independently toggleable) and a "search by" mode (name / tags / both), and two independent per-shelf allow-lists (nothing is searched until an admin opts specific shelves in, separately for ticket-creation suggestions vs. the operator/client ticket-view sidebar). A pair of "Otaguj nową treść"/"Otaguj wszystko ponownie" buttons (also available as php artisan bookstack:tag-content) use the AI integration below to auto-tag every book/chapter/page with matching subcategory names, so the tag-based search mode has something to find.
• Generic AI integration (Admin > Integracje > "Integracja AI") (optional, off by default) — an OpenAI-compatible chat-completions client (Groq, OpenAI, or a self-hosted Ollama instance) configured by base URL, optional API key, model, and an SSL-verification toggle. Not tied to a single feature — it backs the BookStack auto-tagging above and the AI ticket triage/summary below, and is meant to be reused by anything that needs an LLM call in the future.
• AI-driven ticket triage + summary (Admin > Integracje > "Automatyzacja AI dla zgłoszeń") (optional, off by default, requires the AI integration above) — five independent toggles run once per new ticket, in the background (ai:run-ticket-automation, never synchronously at submission): assign a category/subcategory when missing, pick a subcategory when only a category is set, recheck/correct an already-categorized ticket, rewrite an unclear subject, and set a priority from the ticket's content. Every applied change is logged in the ticket's history. Separately, an AI-generated summary + suggested next action for every ticket, shown to operators only, refreshed as the thread grows, with an admin-editable prompt (reset-to-default button included).

Tech stack

• Backend: Laravel, Livewire (server-driven UI, no SPA build beyond Tailwind/Vite for CSS), LdapRecord for directory auth, Sanctum for API tokens, L5-Swagger for API docs, Laravel Reverb for WebSocket broadcasting (real-time queue/chat updates — see ARCHITECTURE.md), webklex/php-imap for the optional e-mail intake fetcher (pure-PHP IMAP client, no ext-imap needed).
• Frontend: Blade + Livewire + a little Alpine.js for local UI state; Tailwind v4 via Vite for resources/css/app.css; Laravel Echo + Pusher-protocol client (resources/js/echo.js) for Reverb. No JS charting library — the statistics dashboard is hand-rolled inline-styled bar/column charts, so it needs no client build step beyond the CSS bundle.
• Database: MariaDB.
• Deployment: compose.yaml — servicedesk (source bind-mounted from ./src, no image rebuild needed for PHP/Blade/route changes) + mariadb + reverb (same image, php artisan reverb:start), fronted by Traefik with a private-CA TLS cert (the websocket path is routed to reverb by a higher-priority Traefik rule; everything else goes to servicedesk). The servicedesk image itself is built and pushed by Gitea Actions (.gitea/workflows/build.yml) to the Gitea container registry whenever Dockerfile changes — compose.yaml just pulls a tag, it never builds locally.

See install.md for full step-by-step deployment instructions — both via Docker Compose (this stack) and directly on a server with Apache/Nginx, including which .env values to set (there are two separate .env files — Compose-level and Laravel-level) and the LDAP/SMTP gotcha after a fresh seed.

Local/dev notes

• The app container mounts ./src directly — editing PHP/Blade/routes takes effect immediately, no rebuild or restart needed.
• CSS/JS changes under resources/ do need a Vite build. Neither the host nor the app container has Node installed; rebuild with a throwaway container instead of rebuilding the app image:

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

• Fresh install / reset:

  sudo docker exec servicedesk-servicedesk-1 php artisan migrate:fresh --seed
  

  Seeds real reference data (categories, custom fields, statuses/priorities/SLA, teams, quick actions, response/e-mail templates, branding/config with example SMTP+LDAP placeholders) and a single local fallback account, admin@example.com / admin — replace its password and/or the SMTP/LDAP settings before relying on this in anything but a lab environment.

Project layout

src/                     Laravel application
  app/Livewire/          Client/Operator/Admin Livewire components
  app/Models/            Eloquent models
  app/Events/            Broadcast events (TicketQueueChanged, TicketMessagePosted)
  app/Console/Commands/  Scheduled commands (SLA breach check, automation rules, IMAP fetch,
                         AI ticket triage/summary) + bookstack:tag-content
  app/Services/          TicketService (ticket lifecycle + notifications), BookStackClient,
                         ImapMailboxFetcher (I/O) + ImapMessageClassifier (pure logic),
                         AiClient (generic LLM client), BookStackContentTagger,
                         TicketAiTriageService, TicketAiSummaryService
  app/Ldap/              LDAP user model + sync handlers
  database/migrations/   Schema (one file per table group, final shape)
  database/seeders/      DatabaseSeeder — reference data, no ticket data
  resources/css/         Tailwind entrypoint (needs `npm run build` after edits)
  resources/js/echo.js   Laravel Echo/Reverb client + broadcast → Livewire event bridge
  resources/views/       Blade templates
  routes/web.php         Client/Operator/Admin routes (role-gated)
  routes/api.php         REST API (Sanctum, ability-gated)
  routes/channels.php    Broadcasting channel authorization (operator.queue, ticket.{id})
wiki/
  client/                How-to guide for the Client role
  operator/               How-to guide for the Operator role
  admin/                  How-to guide for the Admin role