16 · Tickets & appointments
Service-desk ticketing (with public portal / feedback-style categories), salon-style appointments + stylists, and how they connect — including the real code path where booking can create a billable ticket.
Two related products (not one blob)
| Tickets (service desk) | Appointments (booking) | |
|---|---|---|
| Job | Track work items: support, repair, feedback, orders-as-tickets, etc. | Schedule time with staff (stylists, etc.) |
| Staff UI | /tickets, service desk, settings, portal designer |
/admin/appointments, active stylists |
| Public UI | /:slug/public/ticket, /support/:slug |
/book/:slug |
| API | /api/tickets, /api/public/* ticket routes, admin ticket-settings |
/api/appointments, /api/public/appointments |
| Feature gate | tickets (plan) | appointments feature flag on mounts |
Your instinct was right
Appointments can create/link a ticket for billing/tracking.
Public ticket portal + categories (including “Compliment”) is how feedback-style intake works —
not a separate “feedback app,” but the same ticket system with portal + categories enabled.
Ticketing system
Staff surfaces
| Path | Purpose |
|---|---|
/tickets | Dashboard |
/tickets/new · /tickets/search · /tickets/:id | CRUD / detail |
/admin/ticket-management | Service desk simple UI |
/admin/ticket-settings | Portal on/off, categories, SLA-ish settings |
/admin/settings/ticket-portal-designer | Public form designer |
Staff portal …/tickets | My tickets (staff view) |
Backend
/api/tickets— list/create/update/status; scopestickets:read/write- Types include: incident, request, change, task, asset, kb, order, bizticket, customsvc
- Workflows:
ticketWorkflow.service.js(auto-assign, escalation, transitions when enabled) - SLA:
ticketSLA.service.js - Notifications:
ticketNotification.service.js - Queue numbers:
ticketCounter— “now serving #42” style - Optional bill / POS invoice hooks on tickets (
maybeCreatePosInvoiceForTicket)
Public portal & feedback-style use
flowchart LR SET[Ticket settings
publicPortalEnabled] CAT[Categories
Inquiry · Issue · Compliment …] FORM[Portal form designer] PUB[Public URLs] TK[(tickets table)] STAFF[Staff service desk] SET --> PUB FORM --> PUB CAT --> PUB PUB -->|submit| TK --> STAFF
Enablement (per tenant)
| Setting | Meaning |
|---|---|
publicPortalEnabled | Turn public intake on/off |
allowGuestTickets | Guests without login can submit |
requireLogin | Opposite policy — force account |
| Portal URL | Backend-generated: /{tenantSlug}/public/ticket |
| Theme / language / timezone | Portal presentation |
Public endpoints (public.tickets.routes.js)
| Path | Purpose |
|---|---|
GET /api/public/portal-form/:tenantSlug | Form config for designer-driven portal |
GET /api/public/categories/:tenantSlug | Categories for the form |
POST /api/public/tickets/:tenantSlug | Submit a ticket |
POST …/track | Track existing ticket |
| Comments endpoints | Public follow-up on a ticket number |
| Knowledge base route | KB surface for tenant |
Feedback without a separate product
Default category seeds include things like General Inquiry and Compliment (“Share positive feedback”). Businesses enable the public portal and use categories (or custom categories) for feedback, complaints, warranty, etc. Same ticket pipeline → same workflows/SLA/staff desk.
UI entry points: /support/:tenantSlug (SupportPortal),
/:tenantSlug/public/ticket, legacy /tickets/public.
Appointments & stylists
| Surface | Path | Role |
|---|---|---|
| Appointments list | /admin/appointments | Schedule board / list |
| Active stylists | /admin/appointments/stylists | Who appears on public booking |
| Public booking | /book/:tenantSlug | Customer picks staff/time |
- API:
/api/appointments(+ staff sub-routes) with feature gateappointments - Public:
/api/public/appointments/:tenantSlug— available slots, staff, create booking - Stylists managed via
/api/appointments/staff— “active stylists appear in public portal”
Do appointments use the ticketing system?
Yes — partly, by design in code
When an appointment is created, the appointments route can
INSERT a row into
tickets (billable ticket), then set
appointments.ticketId / ticketNumber.
If ticket create fails, the appointment still succeeds (logged, non-fatal).
flowchart TD
BOOK[Public / staff book appointment]
AP[(appointments)]
TK[(tickets)]
BILL[Optional ticket bill / POS invoice hooks]
BOOK --> AP
AP -->|on create: try create ticket| TK
AP -->|store ticketId ticketNumber| AP
TK --> BILL
So stylists/booking is not implemented as “just tickets,” but it can hang a ticket off the appointment for tracking/billing. Day-to-day stylist UI is appointments + staff APIs, not the full service-desk screens.
Billable tickets → Core Invoicing
Tickets carry a
bill (line items, amount, status). Checkout creates a
service invoice via Core Invoicing; crypto invoice and mark-paid paths also exist.
Full owner-facing money + audit story:
27 · Auditability & invoicing.
What this is not
| Concept | Reality in GPE today |
|---|---|
| Movie admission / seat inventory tickets | Different product idea — floor seat IDs + invoicing; not this service-desk ticket engine |
| Kitchen tickets | kitchen_tickets / KDS — separate table and flow (see DocHub 15) |
| Standalone “Feedback app” | Portal + categories + tickets, not a separate app package |
File anchors
| Concern | Path |
|---|---|
| Tickets API | backend/routes/tickets.routes.js |
| Admin tickets / settings / workflows | admin.tickets · admin.ticket-settings · admin.ticket-workflows |
| Public tickets | public.tickets.routes.js |
| Portal designer UI | TicketPortalDesigner.jsx · TicketSystemSettings.jsx |
| Public portal UI | PublicTicketPortal.jsx · SupportPortal.jsx |
| Appointments | appointments.routes.js · appointment-staff.routes.js |
| Public booking | public.appointments.routes.js · AppointmentBooking.jsx |
| Stylists UI | ActiveStylists.jsx |
| Workflow / SLA / notify | ticketWorkflow.service.js · ticketSLA.service.js · ticketNotification.service.js |
| OAO | 13-TICKETS-AND-APPOINTMENTS.md |