Agent Desktop¶

Source: ~/VSCodeProjects/Nexivo/nexivo-app
Tech Stack: React 18 + TypeScript, Vite, Fluent UI, Tailwind CSS, Redux Toolkit, Keycloak

Purpose¶

The Agent Desktop is the browser-based unified interface for human agents and supervisors. It surfaces interactions from all channels — voice, chat, WhatsApp, email — in a single application, and provides real-time tools for call handling, queue monitoring, and customer context.

Tech Stack¶

Layer	Technology
Framework	React 18.3 + TypeScript 5.6
Build	Vite 6 (SWC transpiler)
UI Library	Microsoft Fluent UI 8 / Fluent React Components 9
Styling	Tailwind CSS 3
State	Redux Toolkit 2 + redux-persist
Auth	Keycloak 26 (OAuth2 + PKCE)
HTTP	Axios 1.7
Real-time	SSE (agent status), WebSocket (live transcription), polling (live queue)
Charts	Recharts 2
Animations	Framer Motion 12
PWA	Vite PWA Plugin (Workbox)

Application Structure¶

src/
  pages/           # 30+ feature pages
  components/      # Reusable UI components (feature-organised)
  services/        # API layer — 40+ service files
  contexts/        # Global state (Auth, AgentStatus, LiveQueue)
  hooks/           # Custom hooks (useAuth, useAgentStatus, useFilter, …)
  store/           # Redux slices (layout, filters, modals)
  config/          # Auth, API endpoints, license flags, feature flags
  utils/api-connector/  # Axios HTTP client (base URL, auth headers)
  models/          # TypeScript interfaces / DTOs

Pages & Features¶

Dashboards¶

Path	Purpose
`/dashboards/overview`	Main analytics dashboard — trends, call volumes, agent stats
`/dashboards/live-queue`	Real-time agent and call monitoring
`/dashboards/ai`	AI call metrics
`/dashboards/service-level`	SLA and service level reporting

Live Queue Dashboard¶

The live queue dashboard polls Call Service (/live-queue/snapshot) every 10 seconds and displays:

Agent status distribution — donut chart (Available, On Call, Ringing, Wrap-Up, Away, Busy, DND, Break, Offline)
Waiting calls list — queue depth, customer info, wait time
Agent activity rows — per-agent status with elapsed time timer
Team filter — scope view to a specific team

Agent status values: AVAILABLE, BUSY, AWAY, DO_NOT_DISTURB, IN_A_CALL, OFFLINE, READY, INACTIVE, BREAK, AFTER_CALL_WORK

Channels¶

Path	Channel
`/calls`	Voice call history, recordings, AI summaries
`/chats`	Web chat conversations
`/whatsapp-chats`	WhatsApp Business conversations
`/email`	Email channel (configured)
`/tickets`	Ticketing / triage with Kanban board

Configuration & Admin¶

Path	Purpose
`/agents`	Agent roles and team management
`/ai-agents`	AI agent creation and configuration (backed by Compass)
`/knowledge-base`	Knowledge base articles and categories
`/workflow`	Visual workflow builder (ReactFlow)
`/campaigns`	Outbound campaign management
`/widgets`	Communication widget creation
`/opportunities`	Sales opportunity tracking

Real-Time Communication¶

Agent Status — Server-Sent Events (SSE)¶

AgentStatusContext maintains a persistent SSE connection to /contact-status. This streams live agent availability to the dashboard and status indicators across the app.

Fetch-based SSE (supports Authorization header — EventSource API does not)
Automatic reconnection with exponential backoff (max 5 retries)

Live Transcription — WebSocket¶

CallTranscription.tsx opens a WebSocket during an active call to stream the real-time transcript as the conversation progresses.

Live Queue — Polling¶

Dashboard data is refreshed every 10 seconds via REST calls to the Call Service live queue endpoints.

Authentication & Multi-Tenancy¶

Authentication is handled by Keycloak (realm: nexivo).

OAuth2 PKCE flow (pkceMethod: 'S256')
Token auto-refreshed every 30 seconds
All API requests carry Authorization: Bearer {token}
Tenant/organisation extracted from tokenParsed.organization in the Keycloak token

License-Based Feature Gating¶

Features are gated by license claims in the Keycloak token. The LicenseGuard component wraps routes and conditionally renders based on the organisation's active licences.

License Key	Feature
`CALL_TRACKING`	Voice calls
`WHATSAPP`	WhatsApp channel
`EMAIL`	Email channel
`WIDGET`	Web chat widget
`AI_AGENT`	AI agent management

Backend API Integration¶

Base URL: VITE_API_BASE_URL (e.g. https://api.nexivo.dev.cognitry.io/)

Key service files and the endpoints they cover:

Service File	Endpoints
`calls.service.ts`	`/calls` — history, recordings, notes, AI summaries
`live-queue.service.ts`	`/live-queue/snapshot`, `/summary`, `/teams`, `/waiting`, `/agents`
`channel.service.ts`	`/call-channels`, `/chat-channels`
`chats.service.ts`	`/chat-threads`
`whatsapp.service.ts`	`/whatsapp`
`agent.service.ts`	`/agent` — search, department assignment
`contact.service.ts`	Contact CRUD and search
`ai-agent.service.ts`	AI agent CRUD (proxies to Compass)
`knowledge.service.ts`	Knowledge base management
`campaign.service.ts`	Campaign management
`reports.service.ts`	Analytics and reporting
`skills.service.ts`	Agent skills
`teams.service.ts`	Team management

Call Record Model¶

interface Call {
  callId: string;
  callConnectionId: string;
  callingParty: Contact;
  participants: Participant[];
  startTime: string;
  connectedTime: string;
  endTime: string;
  duration: number;
  callOutcome: string;
  callDirection: string;
  language: string;
  status: string;
  channelId: string;
  channelName: string;
  channelType: string;
  monitoringStatus: string;
  tags: string[];
  notes: string;
  // recording metadata
}

Local Development¶

cd nexivo-app
npm install
npm run dev       # Start dev server at localhost:5173
npm run build     # Production build
npm run lint:fix  # Auto-fix linting issues
npm run format    # Prettier formatting

Required environment variables:

VITE_KEYCLOAK_BASE_URL=https://auth.dev.cognitry.io/
VITE_KEYCLOAK_REALM=nexivo
VITE_KEYCLOAK_CLIENT_ID=nexivo-dev
VITE_API_BASE_URL=https://api.nexivo.dev.cognitry.io/
VITE_CCS_URL=...
VITE_CONDUCTOR_URL=...