frontend — Dashboard SPA
The customer-facing dashboard: live session monitoring, recordings replay, chats/ calls, leads, identity-graph admin, agency portal, billing, and the Nox surfaces.
- Stack: Vue 3 (Composition API) + Vite, Pinia, vue-router, TanStack Vue Query, vee-validate + zod, Socket.IO client, Twilio Video, rrweb, PostHog, Tailwind.
- Dev server:
:4000. The same source is wrapped bydesktop.
Build & release
scripts/bump-version.js drives build:release (patch), build:minor,
build:major. Vite injects __APP_VERSION__, __BUILD_DATE__, __GIT_COMMIT__,
__WHITE_LABEL__. Rollup splits ~14 manual chunks (vue, rrweb, twilio, charts,
quill, …). Containerized via Dockerfile.azure (multi-stage → nginx).
App structure (src/)
main.js Pinia + VueQuery + router + axios interceptors
router/ index.js (50+ routes, guards), admin.js, agency.js
store/ Pinia stores (persisted)
repositories/ API layer — plain async axios fns, grouped by area
composables/ useLiveSocket, useLiveReplayer, useKnoxVoice, usePostHog, …
views/ page components
components/ SessionPlayer (rrweb), form/ (vee-validate wrappers), knox/, …
layouts/ AppLayout (sidebar/header)
config/ env.config.js (API URLs, Stripe, Firebase)
utils/ platform.js (isElectron), socketManager.js, twilioCall.js
State (Pinia)
Stores persist to local/session storage via pinia-plugin-persistedstate. Main
ones: app (user/company/auth/theme/subscription/branding), sessions, chats,
calls, knox, nox* (noxActions, noxInsights, noxSettings,
noxRecentConversations), briefSession, notifications, onboarding,
update (Electron auto-updater).
GHL OAuth flows store auth in sessionStorage instead of localStorage — see the dynamic storage wrapper in
store/app.js.
Data layer
Repository functions in repositories/<area>/ call axios; TanStack Query wraps
them with keys from @lukemorales/query-key-factory (queryKeys.js per area).
QueryClient defaults: 5 min stale, 30 min gc, 1 retry, no refetch-on-focus. The
IDE-open file repositories/admin/identity.js is the identity-graph admin API
(persons, profiles, form submissions, maintenance, GHL reconcile). Trim Session
Events still streams NDJSON with an onProgress callback; newer maintenance
jobs start a background job and MigrationPanel polls its /jobs/:job_id.
The axios response interceptor (utils/authInterceptors.js) also watches the
backend's X-Result-Limit-Capped header: when it is set and the longest array
in the body is shorter than pagination.total, it console.warns
[api] <url> returned N of M rows. The rows array is found by shape because
endpoints name it differently (results, all_users, logs, members, …).
Routing & auth
router/index.js guards: requiresAuth → redirect to /login; role redirects
(admin → /admin, agency → /agency, owner → /dashboard); meta.permission
checked via memberHasPermission(); meta.feature gated against subscription
(appStore.isAllowInPackage); meta.ownerOnly; onboarding redirect. Admin
routes also check the staff member's sections (common/constants/adminSections.js);
ops_dev users only get /ops. Axios interceptors (utils/authInterceptors.js)
attach the bearer token and platform header only to our own services (backend,
ms-ai, ms-sessions, ms-communication) and log out only on a 401 with
code: 'SESSION_INVALID' from one of them (439ada0d) — any other 401 is left
to the caller, so the per-component axios instances that dodged the old
"any 401 logs out" rule are gone. Electron uses hash history; web uses HTML5 history.
Public (no-login) routes added this window: /t/:number (support ticket status),
/product-roadmap (+ /confirm/:token, /unsubscribe/:token), /creators/*
(Partner Hub taskers, own token), /updates/unsubscribe, /updates/video,
/update-video/:token. /changelog now redirects to VITE_PUBLIC_CHANGELOG_URL
(default the marketing-site changelog; white-label hosts go to /).
Realtime
Two sockets: window.main_socket (agent/internal notifications) and
window.socket (calls/chats/sessions). Notable events: update-live-session,
online-session/offline-session, twilio-webrtc-call-response,
new-call-request, new-session-message, session-page-context; emits
agent-available-for-call, call-accepted-by-agent, inbound-takeover events.
useLiveSocket.js and LiveCallListener.vue own the wiring. App.vue calls
setupSocketListeners() before the sockets connect (5f5cb868): the backend
emits user-status-update the moment the main socket joins, and waiting for all
three sockets lost it, leaving the sidebar dot offline until the 30 s ping.
Every socket built by utils/socketManager.js passes auth: (cb) => cb({ token: readAuthToken() }),
read on each (re)connect — since 2026-10-14 the backend, ms-communication and
ms-sessions only join a socket to its company / user:<id> room when that
token belongs to a user who can manage the company (564d8fa8; the playground
sends its owner token, 0ab6c8b0). See
Socket room auth.
App.vue reloads the sidebar wallet / subscription (company) or /user/me
(agency) on wallet-updated and company-settings-updated pushes, which now
reach agency users and staff too; the AI-paused banner re-checks on each
subscription reload (0c066828). utils/callLog.js batches per-call dashboard
steps and emits them every second on the call-log socket event (stored on the
service room — admin Call Logs).
Feature areas
| Feature | Where |
|---|---|
| Live sessions | LiveSessionsView.vue + useLiveSocket/useLiveSessionDetails/useLiveReplayer |
| Recorded replay | RecordedSessionsView.vue + components/SessionPlayer/ (rrweb) |
| Twilio video | call panel + utils/twilioCall.js + LiveCallListener.vue |
| Knox voice | views/settings/nox/ + useKnoxVoice + store/knox |
| Identity graph admin | /admin/identity/* + repositories/admin/identity.js (super-admin) |
| Agency portal | /agency/* |
| Billing | views/packages/* (Stripe) |
| Nox surfaces | settings/nox/ + nox* stores |
Recent additions (2026-07)
- Dashboard restructure —
/dashboardand/reportsare the same for every company (beta gate removed 2026-09-25,021eae6b):DashboardHome.vuerenders the command center (views/Dashboard/Index.vue) plus setup cards and the agency-pause banner;ReportsHome.vuerenders the six-tab analytics (views/Reports/Index.vue). LegacyReportsView.vueis deleted;DashboardView.vueis no longer routed. Since 2026-11-09 (6e0295af) the dashboard tabs are Today / Analytics (VALID_TABS); the funnel is its own Funnels page (Monitor group, routefunnel,/funnel,views/FunnelPage.vue) and/dashboard?tab=funnelforwards there. Analytics embedsReports/Index.vue(embeddedprop, sub-tab in?report=);?tab=impact|visitorsmap toanalytics|today. See Dashboard. - Wallet UI — sidebar wallet pill (
CompanyNavigationSidebar.vue),views/packages/Wallet.vuetransactions page,PackagesTabs.vue(Wallet/Add-ons/Payment Methods),composables/useBalanceAccess.js(now grants full self-service to agency sub-accounts). - Members layout —
views/members/MembersLayout.vuewith People/Teams/Branches tabs. - Playground — public
views/playground/+views/simple-playground/(no-login demo sandbox, shareable), agency lists underviews/agency/{playground,simple-playground}/, admin list with credits column. - PWA — installable with a per-tenant manifest (
App.vue,public/sw.js). - Admin surfaces —
views/admin/StorageMaintenance.vue, cost-tracking unit-economics cards, Nox funnel audit logs + contact trace, identity maintenance panels, visitor-watch History tab, playground credits column. - Startup perf — heavy chunks (charts, Knox tree) deferred out of startup; vite build warnings cleaned.
Recent additions (2026-08)
- Agent K standalone page — Agent K moved from a dashboard tab to its own
/agent-kpage (views/agentk/Index.vue: Feed with channel sub-filters + Reports with drill-down; stage narrative via itsSTAGE_WORDSmap; shared lead/stage formatting incommon/helpers/agentK.js). Settings split into 7 URL-synced tabs (views/settings/ai/agents/AgentK/index.vue— overview / icp / traffic / outreach / channels / delivery / dnc,?tab=+?highlight=), plus a standalone setup route (agent-k-setup→AgentK/Setup.vue) and a pricing modal (PricingModal.vue/PricingTable.vue+useAgentKPricing). - Nox Activity —
views/NoxActivityView.vue(in-app history) andviews/NoxActivityReportView.vue(authed print view — no share tokens). - Session details redesign —
components/sessions/SessionMoreInfoPanel.vue+SessionAgentKOutreach.vue(Agent K outreach shown in the panel). - Engage live visitor —
components/sessions/EngageVisitorModal.vuefrom the live session view; live sessions hide bot traffic by default. vitest is established (src/**/*.test.js): this window addedAgentKInbox.test.js,AgentKPanes.test.js,useLiveSocket.test.js,useLiveReplayer.test.js(+liveSessionTestKit.js),socketManager.reconnect.test.js,clipboard.test.js,ScheduleCallDialog.test.js,NoxTaskHistory.test.js,canvasOrder.test.js, and playground/integration tests. - 2026-08/09 — Calls screen rewritten as rail/thread/contact
(
components/calls/,useCallsFeed.js); Agent K three-pane inbox (views/agentk/); Nox Live standup mode, Task sheet, Scheduled overlay (components/knox/live/),KnoxConfigCard.vue; partner portal (views/partner/— invites, listing editor, sign-up links) and onboardingPartnerStep.vue; admin identity repair screens, Integrations Maintenance, Identity Maintenance cards (CRM smoke, crm_links backfill), Call Duration Backfill;utils/clipboard.js; 20 admin views on reactive route-param query keys; version 1.7.0;Dockerfile.azureon node:24-alpine (npm 10.9.8edgesOutcrash on vitest 5 peers — there is no lockfile by design, so CI re-resolves every build). - Integrations screen split —
views/settings/integrations/Index broken into ~24 per-card components insrc/components/integrations/; the old dashboard Campaigns tab now lives onManyReachCard.vue/ManyReachCampaigns.vue. - Platform APIs (agency) —
views/agency/settings/PlatformApis.vue,PlatformWebhookManager.vue+ deliveries view, andviews/auth/PlatformLoginView.vueat/platform-login/:code. - Partner certification — partner portal
views/partner/+ admin suiteviews/admin/certification/(Queue/Students/Tests/Settings, wallet rewards in dollars). - Push notifications — user push preferences + admin push tester; new
components/form/FormSearchSelect.vue. - Misc UI — Wallet shows Agent K line items; shared
components/DateRangeButton.vue; Quill rich-text standardized across Agent K drafts, Nox drafts, and the email signature editor. - Cross-tab session sync —
utils/sessionChannel.js(BroadcastChannel): stale tabs freeze when another tab switches user or logs out; app-store persist config fixed (field list was silently ignored); axios interceptors moved out ofmain.js. - GHL iframe silent re-auth — 401 inside the GHL iframe re-authenticates via
the stored secret instead of logging out (
views/auth/GoHighLevelAuthView.vue,store/app.js). - Dashboard tabs —
VALID_TABS = ['today', 'impact', 'visitors', 'funnel'](views/Dashboard/Index.vue); Campaigns tab removed; Nox briefing strip removed from the dashboard (Reports still rendersNoxStrip). - Traffic-source labels —
common/helpers/session.js:agent_k→ "Agent K Outreach",manyreach→ "ManyReach Campaign",ghl_backfill→ "CRM Email Link". - Route gates are data-driven —
partner_certification_enabled(+webOwnerOnlymeta) and the agency client-permission map (pages.*); theLINKEDIN_CHANNEL_UIbuild flag was removed.
Recent additions (2026-09, identity & platform)
- Identity display gating —
common/helpers/session.js:hasIdentityGraphMatch(person, bareperson_id/verified_person_id/claimed_person_id— the public single-session endpoint strips person/Apollo/ Snitcher data — orsuspected_identity) andhasKnownVisitor(graph match or a stated name/email/phone; placeholders andfirst_name/last_nameignored; mirrors backendknowsVisitor). Once known, every person-level provider fallback is closed on live + recorded sessions: name cascade, avatar (getSessionImageignores animageequal to the Apollo photo), Apollo city, decision makers, other contacts, Apollo person header. The Snitcher company card stays. Phone-only visitors display their number. SuspectedIdentityBadgecovers widget-id links (basis "returning browser") and hides once the session is verified, even though a passive verification keeps its shadow marker.- Admin identity — Delete person / Delete profile (ConfirmDialog, identity
queries invalidated); profile IP tab shows "hashed only" for Snitcher-wiped
rows; Person edit dialog seeds the phone country picker from the most recent
located session's
ip_info(vue-tel-input auto-detect fell back to Afghanistan); Identity Maintenance cards Unlink Apollo CRM Contacts, Backfill Device Claims, Merge Duplicate Persons (detach-shared-keys option, conflicting-cluster gate), Key IP Signals by Hash. - Force Logout — admin company detail action (
repositories/admin/companies.js). GHL iframe sessions silently re-auth from the stored secret, so they only stay out oncego_high_level.secret_keyis rotated;authInterceptors.forceLogout.test.jspins both 401 paths. - Admin Emails route —
/admin/emailsis a thin wrapper (views/admin/emails/Index.vue) so the router mounts a fresh instance instead of reusing Notifications with a stalechannelprop.
Recent additions (2026-10, admin & platform)
- Admin screens — Audit Trail (
views/admin/audit-logs/List.vue,6be764ec) and Call Logs (views/admin/call-logs/List.vue+CallLogTimeline.vue,460ff2a7) under Logs & Events; Form Abandonment queue + review detail (views/admin/form-abandonment/,2a6a515c) under Identity Graph, usingRecordingPlayer's newseekTo(absoluteTs)andloadedevent. See Audit Trail and Identity admin. - Admin list searches (
6a747516) — every admin search/filter input waits 500 ms after the last keystroke, and list repositories pass vue-query's abortsignalto axios so superseded requests are cancelled. Audit-log record/company IDs only enter the query once they're a full ObjectId. MigrationPanel— copy button + JSON highlighting on the raw result (8a99ec23); keeps polling a background job through transient poll errors, giving up after 20 consecutive failures or a 404 (ef7e3129).- Nox Funnel — the admin beta toggle is gone (
ac19403a); the Funnel settings menu, settings page, store and brief sections gate oncompany.nox_funnel.enabledonly.
Recent additions (2026-10-20 → 11-16, platform & security)
- Notifications replace What's New (
19638370) —WhatsNewHost/useWhatsNewdeleted; product announcements arrive asannouncementnotifications inNotificationsDrawer(agencies see only the All tab). A later/whats-new+/agency/whats-newpage exists but its menu item is hidden. - Alert popups (
4b21bd61) —components/AlertPopup.vuemounted inApp.vue; pollsGET /popups/activeevery 5 min and on focus; on desktop sends therequest-attentionIPC. Composer on/admin/notifications. See Media & Logs. - Hidden menu items —
common/constants/navVisibility.js:SHOW_SUPPORT_NAV(Help & Support + agency Client tickets),SHOW_ROADMAP_NAV,SHOW_WHATS_NEW_NAVare allfalse;?test_supporton any URL shows them for that tab (sessionStorage),?test_support=0hides them. - Help & Support (
views/Support.vue,views/agency/Support.vue,components/support/ScreenshotAttachments.vue— add/paste/capture up to 5 images) and agency Client tickets; Ops workspace (layouts/OpsWorkspaceLayout.vue,views/ops/*: Zij, support inbox, approvals, triage, announcements) and Partner Hub (layouts/PartnerHubWorkspaceLayout.vue,views/admin/partner-hub/*,router/creators.js). See Ops workspace, Partner Hub. - Admin — Team (
views/admin/team/Index.vue,PresenceAvatar), API Subscriptions, Voice Previews, Recording Retention / Empty Chat Archiving / Deleted Conversations / Archived Account Deletion cards on Settings, Feature Flags for platform switches, retired migration cards removed (5e191564,a5bdabda,c5fc8ab0). - Security —
utils/sanitizeHtml.js(own DOMPurify instance) on Nox replies, citations and notification text (964f30de); chat-list preview parsed withDOMParser(utils/stripHtml.js) and live replay withoutallow-scripts(61263b55); admin email logs in a sandboxed frame; Zapier/Lead API keys shown once; private files fetched through the API client / signed links (a31fdcd0,fc6b5a99). - Boot performance (
7352100b) — the Apple sign-in SDK loads only on auth screens; Stripe.js stays on every page (Stripe fraud guidance) but async, and Checkout/AddCardModal go throughutils/stripeJs.jsloadStripeJsinstead of the global. - Dashboard — the Funnel tab moved to its own Funnels page (
/funnel, alias/funnels; old?tab=funnellinks redirect); the client "Finish setting up your agents" strip is pinned above every page inAppLayout.
Analytics
PostHog (prod only, EU host) via usePostHog.js; pageview/pageleave on route
change; start_trial / subscribe events. Meta Pixel on register/onboarding.
Relationship to desktop & widget
Same source as desktop (Electron) — utils/platform.js isElectron() toggles
platform behavior. Widget setup/codegen lives in components/Widget/ and
settings/widget/, but the actual visitor widget is the separate
widget repo.