Live Map Visualization
Relevant source files
The following files were used as context for generating this wiki page:
The Live Map Visualization is a core feature of the Glimpse platform designed to provide real-time, geographical insights into user activity. It allows administrators to see where users are located globally and monitor their actions as they happen, shifting the focus from individual identities to aggregate traffic patterns and session-based behaviors. Sources: README.md:9-12, PROJECT_OUTLINE.md:5-7
This system relies on a high-performance pipeline that ingest events from client-side SDKs, enqueues them for background processing, performs IP-based geolocation, and stores the resulting spatial data in Redis for rapid retrieval and visualization. The visualization layer utilizes Three.js and React Three Fiber to render these data points on an interactive map. Sources: README.md:162-167, PROJECT_OUTLINE.md:120-135
Data Ingestion and Geolocation Pipeline
The visualization starts with the ingestion of events containing metadata required for geographical mapping. The eventWorker processes incoming jobs from the eventQueue, extracting the client's IP address to perform a lookup against the MaxMind GeoIP Lite database. Sources: app/workers/eventWorker.ts:85-103, PROJECT_OUTLINE.md:88-92
Geolocation Data Points
When an event is processed, the system retrieves the following geographical attributes to power the live map:
| Field | Description | Source |
|---|---|---|
country | The country name where the IP is registered | packages/db/prisma/schema.prisma:41 |
region | The specific administrative region or state | packages/db/prisma/schema.prisma:42 |
city | The city associated with the session | packages/db/prisma/schema.prisma:43 |
lat | Latitude coordinates for map placement | packages/db/prisma/schema.prisma:45 |
lon | Longitude coordinates for map placement | packages/db/prisma/schema.prisma:46 |
Processing Flow
The following diagram illustrates how event data flows from the web client to the visualization-ready state in Redis and the primary database.
Real-Time Session Tracking
To ensure the map reflects "Live" data, the system maintains a set of active sessions in Redis. Every time a user triggers an event (e.g., a Page View or Scroll Depth milestone), the worker updates the session's geographical coordinates and sets a Time-To-Live (TTL) of 300 seconds. This ensures that inactive users automatically disappear from the live visualization after 5 minutes of inactivity. Sources: app/workers/eventWorker.ts:119-126, PROJECT_OUTLINE.md:154-158
Redis Key Structure
The visualization engine queries these specific Redis keys to populate the map:
- Session Metadata:
session:${projectId}:${sessionId}- Stores a hash of geographic data (lat, lon, city, country). - Active Set:
active_sessions:${projectId}- A Redis Set containing all currentsessionIdstrings for a specific project.
Sources: app/workers/eventWorker.ts:114-124, PROJECT_OUTLINE.md:168-171
Frontend Visualization Architecture
The frontend is built with Next.js and styled with Tailwind CSS, optimized for dark mode to enhance the 3D visualization. Sources: README.md:162-167, app/web/src/app/globals.css:1-10
Rendering Technologies
- Three.js / React Three Fiber: Used for the primary 3D map rendering.
- GeoJSON / TopoJSON: Provides the mathematical boundaries and structures for the global map projection.
- WebSockets: (Planned) Used for streaming event markers directly to the map interface as they are processed by the workers.
Sources: README.md:162-167, PROJECT_OUTLINE.md:179-183
Visualization Events
The map displays real-time markers based on the following automated triggers from the analytics-web SDK:
Data Schema for Geolocation
The events table in the database mirrors the information available for visualization, allowing for historical replays of traffic patterns.
model Event {
id BigInt @id @default(autoincrement())
projectId String
name String
occurredAt DateTime
sessionId String
// Geographical Data for Mapping
country String?
region String?
city String?
lat Float?
lon Float?
@@index([projectId, occurredAt])
@@map("events")
}
Sources: packages/db/prisma/schema.prisma:22-48
Conclusion
The Live Map Visualization system in Glimpse integrates client-side auto-tracking with a robust Redis-backed processing worker to provide immediate geographical feedback. By utilizing 3D rendering technologies and precise IP geolocation, it transforms abstract event data into a tangible representation of global user activity.