Helpdesk Visitor Live Map
An admin-only live, city-level map of the people currently in a Get Help conversation: a dot per participant at their approximate city, live online / active-now counters and a filterable visitor list, opened from the maximized helpdesk console.
On this page
What it is
The Visitor Live Map is a live, city-level map of the people who are
currently in a Get Help (helpdesk) conversation — a Crisp-style "who's on the
site right now" view for support. Each person in an open help chat shows as a dot
placed at their approximate city; where several people share a city they stack
under a single count bubble (a white circle with the number inside). A live
counter card floats over the map reading "N online / N active now", and a
filterable list rail on the left shows every current visitor (avatar, name or a
stable visitorNNNN fallback, tier/place line, country flag, and an online/active
status dot).
It is help-admin only — the same audience as the developer console's "Needs your reply" queue, and the same privacy class (it surfaces other users' presence). It is not a general analytics or tracking feature: it only ever shows people who are right now in a helpdesk conversation, at city granularity.
Approximate by design. Dots are city-centroid, derived from IP geolocation — never a street address and never the raw IP (see Privacy below). The UI presents location as approximate.
Where it lives
The map opens inside the Get Help console. An admin with the developer console
opens it from the Insights & Routing menu (the headset icon at the bottom of the
console's escalation-list rail) — a Visitor map item beside Insights and Routing.
It no longer has its own toolbar icon. On desktop, selecting it opens the map in the
maximized full-screen console: the filterable visitor list on the left, the map
filling the rest, the live counters floating top-left, and a control strip (Back
to queue · exit full screen · close). In the small corner widget / on mobile the
map fills the body with the counters floating over it (the wide filter rail is a
full-screen-console affordance).
The Leaflet map itself is lazy-loaded as its own chunk, so Leaflet never enters the main renderer bundle.
How presence works
Presence is ephemeral live state, streamed — never a persisted history:
- Online = a live SSE connection. When a person in a non-resolved help thread
has an open
helpdeskStreamconnection, the backend upserts a presence record; the connection's ~25s heartbeat refreshes theirlastSeen, and the stream closing removes them. - Active now = recent
/relayactivity. Typing, sending a message, or marking read on the relay bumps theirlastActiveAt. "Active now" is a strict subset of "online" — someone can be connected (online) but idle (not active). - Admin fan-out. The admin leg of
helpdeskStreamwatches the presence collection and emitsvisitorframes ({ type: 'upsert', presence }/{ type: 'remove', presenceId }) to every signed-in admin operator. - Desktop ingress → renderer. The desktop validates each frame at the ingress
boundary and pushes it on the
helpdesk:visitorchannel; the renderer keeps an in-memory map of visitors keyed bypresenceId, applying each upsert/remove idempotently. A local freshness prune drops any dot whoselastSeenhas aged past a ~60s cutoff, so a missed close (a socket blip or crashed producer) can never leave a stale dot on the map forever. Both counters derive from the same cutoff.
Privacy posture (coords-only, city-level)
The map is built to expose coordinates and city only — never a raw IP or a precise address, and this is enforced at every layer, not just by the UI:
- Coords-only wire shape. The presence record carries
lat/lng(city centroid), and optionalcity/region/countryCode/displayName/tier/avatar— and noipfield is ever written. The backend geo reader extracts only city + centroid + country from the GeoLite2 lookup and discards the rest. - Ingress validation strips anything else. Both the push-bus producer and the
desktop ingress boundary validate every frame through one shared coords-only Zod
schema; because the presence object is a plain object schema, parsing strips any
unknown field (notably a raw
ip) before the frame is ever forwarded to the renderer. A cross-cutting test drives anip-laden frame through the real ingress parse into the real renderer store and asserts it never survives. - Per-user opt-out (backend). There is no deploy switch — the map is part of
the app and presence is written whenever the other guards pass. For a signed-in
reporter, the backend honors the global-auth profile's
geoOptOutflag (a user who opted out of geolocation is not placed on the map). - Identity derived server-side. The presence identity (uid / display name / tier / thread) is read server-side from the reporter's own help threads, never trusted from the client, and presence is only written when the reporter has a receivable, non-resolved thread.
- Server-only storage. The Firestore
helpdesk_visitor_presencecollection denies all client reads/writes (server-only) and carries a TTL onexpireAtfor lazy garbage collection — the authoritative removal is the SSE close, not the TTL.
There is no desktop consent setting — visitor consent lives entirely on the
backend (geoOptOut), so there is nothing for a user to
misconfigure client-side.
Feature gating
The visitor map is no longer behind its own toggle (the helpdesk-visitor-map
feature is shipped). Like the Routing manager, it gates purely on the developer
console — the admin console capability plus the console flag:
| Gate | env var | settings key | Purpose |
|---|---|---|---|
helpdesk-dev-console |
AMC_SHOW_HELPDESK_DEV_CONSOLE=1 |
helpdeskDevConsoleEnabled |
The admin console the map lives in (admin-only) |
In the renderer this is visitorsGate = devConsoleVisible (HelpdeskPanel), and the
Visitor map entry is added to the console's Insights & Routing menu only when that
gate holds. If the gate is revoked while the map is open, the admin falls back to
their queue. The feature stays registered in the unreleased-feature registry (id
helpdesk-visitor-map) at status shipped so its settingKey still parses in
existing configs, but it no longer restricts the surface.
helpdeskVisitorMapEnabled is infrastructure for the gate, not a consent
setting — visitor consent stays backend-side as described above.
Key files
| Concern | File |
|---|---|
| Feature flag (registry) | src/shared/unreleased-features.ts (helpdesk-visitor-map) |
| Push channel + coords-only Zod schema | src/shared/ipc-channels/helpdesk.ts · src/shared/push-event-schemas/helpdesk.ts |
Desktop ingress parse boundary (strips ip) |
src/main/services/helpdesk/helpdesk-cloud-parse.ts (parseHelpdeskVisitorFrame) |
Frame forwarder (dedup + emitPush) |
src/main/services/helpdesk/helpdesk-visitor-listener.ts |
| Renderer store slice (in-memory presence + prune) | src/renderer/src/stores/slices/helpdesk-visitors-slice.ts |
| Read hook (list + live counters + prune tick) | src/renderer/src/features/helpdesk/use-fresh-visitors.ts |
| Map view (Leaflet, per-city bubbles, flyTo) | src/renderer/src/features/helpdesk/HelpdeskVisitorMapView.tsx |
| Visitor list rail + filter | src/renderer/src/features/helpdesk/HelpdeskVisitorList.tsx |
| Live counters card | src/renderer/src/features/helpdesk/HelpdeskVisitorCounters.tsx |
| Panel wiring (nav + gates + full-screen console) | src/renderer/src/features/helpdesk/HelpdeskPanel.tsx |
| Push consumer (feeds the slice) | src/renderer/src/hooks/useHelpdeskPushEvents.ts |
Backend presence writer, SSE hooks, and the geo reader live in the amc-back
apps/helpdesk-api service (visitor-presence.ts, visitor-geo.ts, stream.ts,
relay.ts) — the desktop consumes the visitor SSE frames it emits.
Related
- helpdesk.md — the Get Help panel + developer console this map lives in
- unreleased-feature-gating.md — how Omniscio hides in-development features until they ship