Architecture

System shape

End user / Agent browser
  -> apps/web (React + Vite)
  -> apps/api (Hono)
  -> Supabase (Postgres, Auth, Realtime)
  -> external classifier service (FastAPI)

Monorepo packages

Path	Package	Responsibility
apps/web	@arabic-itsm/web	User portal, queue UI, stats UI, admin screens
apps/api	@arabic-itsm/api	Auth-aware REST API and ticket orchestration
packages/shared	@arabic-itsm/shared	Shared routing thresholds and core types
packages/docs	@arabic-itsm/docs	VitePress technical documentation
supabase/migrations	n/a	Database schema, policies, and seed structure

Request lifecycle

Ticket submission

1. Web sends title_ar and description_ar to POST /api/v1/tickets.
2. API validates Arabic-only content.
3. API calls the classifier service.
4. API computes a routing decision from the returned confidences.
5. Ticket is inserted into tickets.
6. Assignment and notifications are triggered.
7. Web reloads queue or detail data from the API.

Routing decision model

Shared thresholds come from @arabic-itsm/shared:

• AUTO = 0.85
• REVIEW = 0.60

The API computes the minimum confidence across l1, l2, and optional l3.

Condition	Result
all available levels >= 0.85	routing_mode = auto, status = open
l1 >= 0.60 but not auto	routing_mode = review, status = pending_review
otherwise	routing_mode = manual, status = new

Department and assignment flow

• Department lookup is based on departments.l1_labels.
• auto tickets are assigned to the least-loaded agent in the matched department.
• review tickets are routed to Service Desk if available, otherwise to the matched department without direct assignment.
• manual tickets skip assignment and notify admins for triage.

Auth model

• API auth middleware reads a Supabase bearer token.
• It resolves the user with the Supabase admin client.
• Role and department_id are pulled from app_metadata.
• If auth data is missing, the request proceeds as anonymous context.

Realtime model

The platform uses Supabase Realtime rather than custom websocket infrastructure.

• notification UI subscribes to user-specific notification changes
• queue views subscribe to ticket changes relevant to the current department

This keeps the API stateless while still giving agents live updates.

Failure handling

If the classifier is unavailable or returns an upstream error:

• ticket creation still succeeds
• classification is stored as null
• routing falls back to manual
• admins are notified for manual triage

That fallback is central to keeping the helpdesk usable when the ML service is down.