Geolocation Service

Relevant source files

The following files were used as context for generating this wiki page:

• app/workers/lib/geolookupIp.ts
• packages/shared/lib/getIp.ts
• app/workers/eventWorker.ts
• app/workers/lib/lru.ts
• README.md
• packages/db/prisma/schema.prisma
• PROJECT_OUTLINE.md

The Geolocation Service in Glimpse is responsible for identifying the physical location of users based on their IP addresses during event ingestion. It serves as a critical component for the platform's live mapping and traffic visualization features, allowing the system to transform raw network data into geographic insights such as country, city, and coordinates.

The service is integrated into the asynchronous event processing pipeline, ensuring that every tracked session is enriched with spatial metadata before being stored in the database or visualized on the live dashboard.

Sources: README.md:3-8, PROJECT_OUTLINE.md:52-56

Architecture and Data Flow

The geolocation logic is primarily executed within the eventWorker, which processes jobs from the eventQueue. When an event is ingested, the worker extracts the client's IP address and utilizes a specialized lookup utility to retrieve geographic information.

Geolocation Pipeline

1. IP Extraction: The API layer extracts the client IP from request headers (supporting proxies via X-Forwarded-For).
2. Job Enqueueing: The event, including IP metadata, is added to BullMQ.
3. Lookup & Caching: The worker calls geoLookupIp, which first checks a local LRU cache before querying the MaxMind GeoLite2 database.
4. Enrichment: The resulting geographic data is attached to the event and session objects.

The diagram above illustrates how the system minimizes external lookups by utilizing a multi-layered resolution strategy involving memory caching and the geoip-lite library.

Sources: app/workers/eventWorker.ts:86-103, app/workers/lib/geolookupIp.ts:38-55, PROJECT_OUTLINE.md:104-122

Core Components

Geolocation Lookup Utility

The primary entry point for geolocation is the geoLookupIp function. It cleanses the IP address (handling IPv6 mapping) and manages the cache lifecycle.

Function	Description	Source
geoLookupIp(ip)	Main wrapper that handles IP normalization, cache checking, and database lookup.	geolookupIp.ts:38-55
GetIPInfo(ip)	Internal function that interfaces directly with geoip-lite and normalizes return values.	geolookupIp.ts:15-35

Data Structures

Geolocation results are standardized into a GeoResult type to ensure consistency across the worker and database layers.

export type GeoResult = {
    country?: string;
    region?: string;
    city?: string;
    timezone?: string;
    lat?: number;
    lon?: number;
} | null;

Sources: app/workers/lib/geolookupIp.ts:4-11

Caching Strategy

To ensure high performance and low latency during high-traffic bursts, the service employs an LRU (Least Recently Used) cache.

• Implementation: lru-cache library.
• Capacity: 20,000 entries.
• TTL: 1 hour (3,600,000 ms).
• Key Format: geoip-{ipAddress}.

Sources: app/workers/lib/lru.ts:4-7, app/workers/lib/geolookupIp.ts:40

Integration with Storage

Once geolocation data is resolved, it is persisted in two primary locations:

1. Redis Session Store

The worker updates a Redis hash for the session, allowing real-time components to access location data without re-calculating it. This data has a 300-second TTL to match the session window.

2. PostgreSQL Event Log

The eventBuffer flushes batched events to the events table. Geolocation fields are mapped from the GeoResult to the Prisma model.

Database Field	Source Property	Type
country	geo.country	String
city	geo.city	String
lat	geo.lat	Float
lon	geo.lon	Float

Sources: packages/db/prisma/schema.prisma:35-40, app/workers/eventWorker.ts:44-67

Configuration and Setup

The service relies on the MaxMind GeoLite2 database. Users must provide a license key in the environment configuration to enable or update the geolocation data.

• License Key: GEOLITE_LICENSE_KEY must be set in the .env file.
• Update Command: cd node_modules/geoip-lite && npm run updatedb license_key=...
• Docker Integration: The license key is passed as a build argument to the Dockerfile to ensure the database is available within the container.

Sources: README.md:43-45, README.md:104-110, docker/docker-compose.yml:7-8

Conclusion

The Geolocation Service provides the spatial intelligence required for Glimpse's real-time visualizations. By combining local file-based databases (geoip-lite) with memory caching (LRU), it achieves the high throughput necessary for processing analytics events at scale while maintaining a simple configuration footprint for developers.