Omniscio

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 helpdeskStream connection, the backend upserts a presence record; the connection's ~25s heartbeat refreshes their lastSeen, and the stream closing removes them.
  • Active now = recent /relay activity. Typing, sending a message, or marking read on the relay bumps their lastActiveAt. "Active now" is a strict subset of "online" — someone can be connected (online) but idle (not active).
  • Admin fan-out. The admin leg of helpdeskStream watches the presence collection and emits visitor frames ({ 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:visitor channel; the renderer keeps an in-memory map of visitors keyed by presenceId, applying each upsert/remove idempotently. A local freshness prune drops any dot whose lastSeen has 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 optional city / region / countryCode / displayName / tier / avatar — and no ip field 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 an ip-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 geoOptOut flag (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_presence collection denies all client reads/writes (server-only) and carries a TTL on expireAt for 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.

  • 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