From 88fc74392873599ab6c90ad6c9fd515de8a01378 Mon Sep 17 00:00:00 2001 From: saridsa2 Date: Mon, 23 Mar 2026 09:47:42 +0530 Subject: [PATCH] docs: add team onboarding README with architecture and troubleshooting guide Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 217 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 176 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 79d9123..cb7ed05 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,191 @@ -# Untitled UI starter kit for Vite +# Helix Engage — Frontend -This is an official Untitled UI starter kit for Vite. Kickstart your Untitled UI project with Vite in seconds. +Call center CRM frontend for healthcare lead management. Built on the FortyTwo platform. -## Untitled UI React +**Owner: Mouli** -[Untitled UI React](https://www.untitledui.com/react) is the world’s largest collection of open-source React UI components. Everything you need to design and develop modern, beautiful interfaces—fast. +## Architecture -Built with React 19.1, Tailwind CSS v4.1, TypeScript 5.8, and React Aria, Untitled UI React components deliver modern performance, type safety, and maintainability. - -[Learn more](https://www.untitledui.com/react) • [Documentation](https://www.untitledui.com/react/docs/introduction) • [Figma](https://www.untitledui.com/figma) • [FAQs](https://www.untitledui.com/faqs) - -## Getting started - -First, run the development server: - -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev +``` +┌─────────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐ +│ helix-engage │ │ helix-engage-server │ │ FortyTwo Platform │ +│ (this repo) │────▶│ (sidecar) │────▶│ (backend) │ +│ React frontend │ │ NestJS REST API │ │ GraphQL API │ +│ Port 5173 (dev) │ │ Port 4100 │ │ Port 4000 │ +└─────────────────────┘ └──────────────────────┘ └─────────────────────┘ + │ │ + │ SIP/WebRTC │ Ozonetel CloudAgent APIs + ▼ ▼ + ┌───────────┐ ┌──────────────┐ + │ Ozonetel │ │ Ozonetel │ + │ SIP (444) │ │ REST APIs │ + └───────────┘ └──────────────┘ ``` -Open [http://localhost:5173](http://localhost:5173) with your browser to see the result. +**Three repos:** +| Repo | Purpose | Owner | +|------|---------|-------| +| `helix-engage` (this) | React frontend | Mouli | +| `helix-engage-server` | NestJS sidecar — Ozonetel + Platform bridge | Karthik | +| `helix-engage-app` | FortyTwo SDK app — entity schemas (Call, Lead, etc.) | Shared | -You can start editing the app by modifying the components in `src/` folder. The page auto-updates as you edit the file. +## Getting Started -## Resources +```bash +npm install +npm run dev # http://localhost:5173 +npm run build # TypeScript check + production build +``` -Untitled UI React is built on top of [Untitled UI Figma](https://www.untitledui.com/figma), the world's largest and most popular Figma UI kit and design system. Explore more: +### Environment Variables (set at build time or in `.env`) -**[Untitled UI Figma:](https://www.untitledui.com/react/resources/figma-files)** The world's largest Figma UI kit and design system. -
-**[Untitled UI Icons:](https://www.untitledui.com/react/resources/icons)** A clean, consistent, and neutral icon library crafted specifically for modern UI design. -
-**[Untitled UI file icons:](https://www.untitledui.com/react/resources/file-icons)** Free file format icons, designed specifically for modern web and UI design. -
-**[Untitled UI flag icons:](https://www.untitledui.com/react/resources/flag-icons)** Free country flag icons, designed specifically for modern web and UI design. -
-**[Untitled UI avatars:](https://www.untitledui.com/react/resources/avatars)** Free placeholder user avatars and profile pictures to use in your projects. -
-**[Untitled UI logos:](https://www.untitledui.com/react/resources/logos)** Free fictional company logos to use in your projects. +| Variable | Purpose | Dev Default | Production | +|----------|---------|-------------|------------| +| `VITE_API_URL` | Platform GraphQL | `http://localhost:4000` | `https://engage-api.srv1477139.hstgr.cloud` | +| `VITE_SIDECAR_URL` | Sidecar REST API | `http://localhost:4100` | `https://engage-api.srv1477139.hstgr.cloud` | +| `VITE_SIP_URI` | Ozonetel SIP URI | — | `sip:523590@blr-pub-rtc4.ozonetel.com` | +| `VITE_SIP_PASSWORD` | SIP password | — | `523590` | +| `VITE_SIP_WS_SERVER` | SIP WebSocket | — | `wss://blr-pub-rtc4.ozonetel.com:444` | -## License +**Production build command:** +```bash +VITE_API_URL=https://engage-api.srv1477139.hstgr.cloud \ +VITE_SIDECAR_URL=https://engage-api.srv1477139.hstgr.cloud \ +VITE_SIP_URI=sip:523590@blr-pub-rtc4.ozonetel.com \ +VITE_SIP_PASSWORD=523590 \ +VITE_SIP_WS_SERVER=wss://blr-pub-rtc4.ozonetel.com:444 \ +npm run build +``` -Untitled UI React open-source components are licensed under the MIT license, which means you can use them for free in unlimited commercial projects. +## Tech Stack -> [!NOTE] -> This license applies only to the starter kit and to the components included in this open-source repository. [Untitled UI React PRO](https://www.untitledui.com/react) includes hundreds more advanced UI components and page examples and is subject to a separate [license agreement](https://www.untitledui.com/license). +- **React 19** + TypeScript + Vite +- **Tailwind CSS 4** with semantic color tokens (`text-primary`, `bg-brand-section` — never raw colors like `text-gray-900`) +- **React Aria Components** for accessibility (imports always prefixed `Aria*`) +- **Jotai** for SIP/call state +- **React Context** for auth, data, theme +- **FontAwesome Pro Duotone** icons +- **Untitled UI** component library (`src/components/base/`, `src/components/application/`) -[Untitled UI license agreement →](https://www.untitledui.com/license) +## Project Structure -[Frequently asked questions →](https://www.untitledui.com/faqs) +``` +src/ +├── pages/ # Route-level pages +│ ├── call-desk.tsx # Main CC agent workspace — THE CORE PAGE +│ ├── login.tsx # Auth page (centered card on blue bg) +│ ├── call-history.tsx # CDR log viewer +│ ├── my-performance.tsx # Agent KPI dashboard +│ ├── team-dashboard.tsx # Supervisor overview +│ ├── all-leads.tsx # Lead master table +│ └── campaigns.tsx # Campaign listing +│ +├── components/ +│ ├── call-desk/ # ⚡ Call center components — WHERE MOST WORK HAPPENS +│ │ ├── active-call-card.tsx # In-call UI + post-call disposition flow +│ │ ├── worklist-panel.tsx # Agent task queue with tabs + sub-tabs +│ │ ├── context-panel.tsx # AI assistant + Lead 360 sidebar +│ │ ├── disposition-form.tsx # Post-call outcome selector +│ │ ├── appointment-form.tsx # Book appointment during/after call +│ │ ├── agent-status-toggle.tsx # Ready/Break/Training/Offline toggle +│ │ ├── transfer-dialog.tsx # Call transfer +│ │ ├── enquiry-form.tsx # General enquiry capture +│ │ ├── live-transcript.tsx # Real-time transcription (Deepgram) +│ │ └── phone-action-cell.tsx # Click-to-call in table rows +│ ├── base/ # Untitled UI primitives (Button, Input, Select, Badge) +│ ├── application/ # Complex UI (Table, Modal, Tabs, DatePicker, Nav) +│ ├── layout/ # Sidebar — role-based navigation +│ └── dashboard/ # KPI cards, charts, missed queue widget +│ +├── providers/ +│ ├── sip-provider.tsx # SIP WebRTC — call lifecycle management +│ ├── auth-provider.tsx # User session, roles (executive/admin/cc-agent) +│ ├── data-provider.tsx # Bulk entity loader (leads, campaigns, calls) +│ └── theme-provider.tsx # Light/dark mode +│ +├── hooks/ +│ ├── use-worklist.ts # Polls sidecar /api/worklist every 30s +│ ├── use-call-assist.ts # Live transcript via Socket.IO +│ └── use-sip-phone.ts # Low-level SIP.js wrapper +│ +├── lib/ +│ ├── api-client.ts # REST + GraphQL client (auth, queries, sidecar calls) +│ ├── queries.ts # Platform GraphQL query strings +│ └── format.ts # Phone/date formatting +│ +├── state/ +│ └── sip-state.ts # Jotai atoms (callState, callerNumber, isMuted, etc.) +│ +└── types/ + └── entities.ts # Lead, Patient, Call, Appointment, etc. +``` + +## Troubleshooting Guide — Where to Look + +### "The call desk isn't working" +**File:** `src/pages/call-desk.tsx` +This is the orchestrator. It uses `useSip()` for call state, `useWorklist()` for the task queue, and renders either `ActiveCallCard` (in-call) or `WorklistPanel` (idle). Start here, then drill into whichever child component is misbehaving. + +### "Calls aren't connecting / SIP errors" +**File:** `src/providers/sip-provider.tsx` + `src/state/sip-state.ts` +Check `VITE_SIP_*` env vars. Ozonetel SIP WebSocket runs on **port 444** — VPNs block it. If WebSocket hangs at "connecting", turn off VPN. Also check browser console for SIP.js registration errors. + +### "Worklist not loading / empty" +**File:** `src/hooks/use-worklist.ts` +This polls `GET /api/worklist` on the sidecar every 30s. Open browser Network tab → filter for `/api/worklist`. Common causes: sidecar is down, auth token expired, or agent name doesn't match any assigned leads. + +### "Missed calls not appearing / sub-tabs empty" +**File:** `src/components/call-desk/worklist-panel.tsx` +Missed calls come from the sidecar worklist response. The sub-tabs filter by `callbackstatus` field. If all sub-tabs are empty, the sidecar ingestion may not be running (check sidecar logs for `MissedQueueService`). + +### "Disposition / appointment not saving" +**File:** `src/components/call-desk/active-call-card.tsx` → `handleDisposition()` +Posts to sidecar `POST /api/ozonetel/dispose`. Errors are caught silently (non-blocking). Check browser Network tab for the dispose request/response, then check sidecar logs. + +### "Login broken / Failed to fetch" +**File:** `src/pages/login.tsx` + `src/lib/api-client.ts` +Login calls `apiClient.login()` → sidecar `/auth/login` → platform GraphQL. Most common cause: wrong `VITE_API_URL` (built with localhost instead of production URL). **Always set env vars at build time.** + +### "UI component looks wrong" +**Files:** `src/components/base/` (primitives), `src/components/application/` (complex) +These come from the Untitled UI library. Design tokens are in `src/styles/theme.css`. Brand colors were rebuilt from logo blue `rgb(32, 96, 160)`. + +### "Navigation / role-based access" +**File:** `src/components/layout/sidebar.tsx` +Navigation groups are defined per role (admin, cc-agent, executive). Routes are registered in `src/main.tsx`. + +## Data Flow + +``` +User action + │ + ▼ +Component (e.g. ActiveCallCard) + │ + ├──▶ Sidecar REST API (via apiClient.post/get) + │ e.g. /api/ozonetel/dispose, /api/worklist + │ + ├──▶ Platform GraphQL (via apiClient.graphql) + │ e.g. leads, appointments, patients queries + │ + └──▶ SIP.js (via useSip() hook) + Call control: answer, hangup, mute, hold +``` + +**Key pattern:** The frontend talks to TWO backends: +1. **Sidecar** (REST) — for Ozonetel telephony operations and worklist +2. **Platform** (GraphQL) — for entity CRUD (leads, appointments, patients) + +## Conventions + +- **File naming**: kebab-case (`worklist-panel.tsx`) +- **Colors**: Semantic tokens only (`text-primary`, `bg-brand-section`) +- **Icons**: `@fortawesome/pro-duotone-svg-icons` + `faIcon()` wrapper in `src/lib/icon-wrapper.ts` +- **React Aria**: Always prefix imports (`Button as AriaButton`) +- **Transitions**: `transition duration-100 ease-linear` + +## Git Workflow + +- `dev` — active development +- `master` — stable baseline +- Always build with production env vars before deploying