Backend

Runtime stack

• Hono for HTTP routing
• @hono/node-server for local runtime
• zod for request validation
• Supabase admin client for data access and auth admin operations

API entrypoint

apps/api/src/index.ts mounts:

• GET /health
• /api/v1/tickets
• /api/v1/classify
• /api/v1/departments
• /api/v1/notifications
• /api/v1/quick-actions
• /api/v1/stats
• /api/v1/users

All /api/v1/* routes go through the auth middleware.

Backend modules

Module	Purpose
env.ts	layered env loading and validation
middleware/auth.ts	bearer token resolution into role-aware auth context
lib/classifier.ts	outbound call to FastAPI classifier
lib/router.ts	routing decision logic from classifier confidences
lib/assignment.ts	department lookup and least-loaded agent assignment
lib/notifications.ts	notification insertion helpers
lib/audit.ts	audit trail writes
lib/profiles.ts	ensures profile existence on ticket creation

Ticket orchestration

The ticket route is the core workflow in the platform.

Create ticket

• validates Arabic-only title and description
• ensures the submitter profile exists
• classifies the ticket when possible
• computes routing_mode, routing_confidence, status, and routing_reason
• inserts the ticket
• records audit metadata
• auto-assigns or triages
• notifies the submitter and relevant agents/admins

Update ticket

Agents and admins can update:

• status
• priority
• assigned_agent_id
• department_id

The route also emits audit entries and targeted notifications when state changes matter to submitters or assignees.

Override routing

Routing overrides are explicit and measurable:

• updates routing fields
• forces routing_overridden = true
• records a dedicated audit entry
• notifies the submitter and acting support user

Reclassify ticket

Reclassification reruns the classifier against the stored Arabic ticket text. If a ticket has already been manually overridden, the new classifier result updates classification and routing_confidence but does not silently replace the human override.

Role behavior

Role	Backend access model
end_user	Can create tickets and only read own tickets
agent	Reads department or assigned tickets, works queues and comments
admin	Full platform access including users, stats utilities, and reseeding

Stats subsystem

The stats router provides both reporting and local-dev admin utilities.

Reporting endpoints cover:

• routing mode breakdown
• confidence histogram
• taxonomy distribution
• per-department override rate
• agent workload

Admin-only utility endpoints cover:

• dev config readout
• ticket reseeding and deletion
• notification deletion
• quick action reseeding

Design choice worth noting

The backend is intentionally orchestration-heavy rather than domain-layer heavy. Business rules sit close to the route handlers and helper libs, which keeps the code understandable for a small product team but means future growth may justify extracting a more explicit service layer.