High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Glimpse is a real-time user analytics platform designed to track sessions and visualize traffic patterns globally through live mapping and event dashboards. The system follows a philosophy of tracking sessions rather than individual identities, providing a clear, live view of user behavior on websites or applications.
The architecture is built on a modular monorepo structure, utilizing a modern tech stack centered around Bun, TypeScript, and Redis-backed job queues to ensure real-time performance and scalability.
Sources: PROJECT_OUTLINE.md:5-10, README.md:1-10
System Components
The Glimpse architecture is divided into four primary layers: the Client-side SDK, the Backend API, the Background Worker System, and the Storage Layer.
| Component | Technology | Description |
|---|---|---|
| Backend Runtime | Bun | High-performance JavaScript runtime for API and workers. |
| Frontend Framework | Next.js / React | Powering the live map and dashboard visualizations. |
| Job Queue | BullMQ (Redis) | Manages asynchronous event ingestion and processing. |
| Database | PostgreSQL | Persistent storage for events and session aggregates via Prisma. |
| Geolocation | MaxMind GeoIP | IP-based location lookups for live mapping. |
Sources: PROJECT_OUTLINE.md:15-30, docker/docker-compose.yml:1-85
Core Architecture Overview
The following diagram illustrates the high-level interaction between the client, API, workers, and data stores.
The system uses a producer-consumer model where the API acts as the producer, sending events to a Redis-backed queue for asynchronous processing by the workers.
Sources: PROJECT_OUTLINE.md:144-180, PROJECT_STRUCTURE.md:40-60
Data Ingestion & Processing Flow
1. Event Collection (Client-Side)
The analytics-web SDK automatically captures various user interactions including page views, scroll depth milestones (10%, 25%, 50%, etc.), form submissions, and outbound link clicks. It also tracks session lifecycle events such as "Session Start" and "Session End" (via beforeunload).
Sources: packages/analytics-web/events/auto.js:1-120, PROJECT_OUTLINE.md:118-135
2. API Ingestion
The Backend API (built with Hono) serves as the entry point. It extracts the client's IP address and User Agent, validates the incoming payload using Zod schemas, and immediately enqueues an ingest-event job into BullMQ to ensure low latency for the client.
Sources: PROJECT_OUTLINE.md:76-88, PROJECT_STRUCTURE.md:25-35
3. Asynchronous Worker Processing
The eventWorker.ts process handles the heavy lifting of event enrichment and storage:
- Session Management: Generates UUID v7 session IDs and manages session state in Redis with a 300-second TTL.
- Geolocation: Performs IP-based lookups to retrieve country, region, city, and coordinates, utilizing an LRU cache to minimize external lookups.
- Buffering: Collects events in an in-memory buffer, flushing them to the database every 5 seconds or when reaching 100 events to optimize write performance.
Sources: PROJECT_OUTLINE.md:90-110, app/workers/todo.md:1-10
Data Model (Storage Layer)
The system uses Prisma ORM to interface with a PostgreSQL database. The schema is optimized for both granular event tracking and aggregated analytics.
The events table stores full metadata including geolocation and context, while analytics_sessions and daily_event_aggregates provide pre-calculated data for the dashboard.
Sources: packages/db/prisma/schema.prisma:18-85, packages/db/prisma/migrations/20260131205756_newb/migration.sql:35-130
Deployment & Infrastructure
The project is containerized using Docker, with a multi-service docker-compose.yml orchestrating the environment:
- api: Hono server on port 3000.
- worker: BullMQ event processor.
- analytics-worker: Specialized worker for aggregate processing.
- postgres: Relational storage.
- redis: Job queue and session caching.
Sources: docker/docker-compose.yml:1-75, README.md:65-95
Conclusion
Glimpse's architecture emphasizes real-time responsiveness by offloading intensive tasks (geolocation, DB writes, and session tracking) to a background worker system. This design allows the API to remain highly available and performant under heavy event loads.
Sources: PROJECT_OUTLINE.md:205-215