Frontend

Runtime stack

• Vite
• React 19
• React Router
• TanStack Query
• Supabase browser client
• Recharts for analytics

Route map

Public and shared routes

Route	Purpose
/	portal home
/tickets/new	create ticket
/tickets/:id	end-user ticket detail
/notifications	user notification center
/settings	shared settings page
/profile	current user profile
/auth/login	sign in
/auth/register	sign up
/auth/forgot-password	password reset request
/auth/reset-password	password reset completion
/auth/accept-invite	invite acceptance flow

Agent and admin routes

Route	Guard
/dashboard	agent or admin
/queue	agent or admin
/queue/:id	agent or admin
/stats	agent or admin
/departments	agent or admin
/departments/:id	agent or admin

Admin-only routes

Route	Purpose
/users	user directory
/users/:id	user detail
/developer-tools	classifier and local-dev admin tools
/quick-actions	quick action management

App structure

Area	Role
src/app	router, layout, providers, error boundaries
src/pages	route-level screens
src/components	UI modules by feature
src/hooks	realtime and app-specific hooks
src/lib	API client, classifiers, formatting helpers
src/i18n	message catalogs and locale provider

Key UX capabilities

End users

• submit Arabic-only tickets
• track ticket detail and comments
• receive notification updates
• manage basic profile and settings

Agents

• work a live queue
• update status and priority
• reassign work
• review classification details
• apply quick actions
• inspect audit history

Admins

• manage users and invitations
• inspect department-level stats
• use developer tools and reseed utilities
• manage quick action content

Realtime hooks

Two hooks carry most of the live behavior:

• useRealtimeNotifications
• useRealtimeQueue

These subscribe on mount and remove channels on unmount. The goal is simple: live updates without turning the frontend into a custom event-processing system.

API client pattern

src/lib/api.ts centralizes:

• bearer token injection from Supabase session
• JSON response parsing
• typed helpers for each backend route

That keeps page components thin and makes the route surface easy to audit.