Introduction to Glimpse
Relevant source files
The following files were used as context for generating this wiki page:
Glimpse is a real-time user analytics platform designed for live mapping and event visualization. Its core philosophy focuses on tracking sessions and traffic patterns rather than individual identities, providing a clear, real-time view of user activity across websites or applications.
The system is built to provide immediate insights through interactive live maps, allowing developers and stakeholders to observe user sign-ups, feature usage, and errors as they occur. By utilizing a high-performance stack including Bun, Redis, and WebSockets, Glimpse ensures low-latency event processing and visualization.
Sources: README.md:1-12, PROJECT_OUTLINE.md:1-10
System Architecture
Glimpse follows a decoupled architecture consisting of a client-side SDK, a backend API, a background worker system, and a persistence layer.
Architectural Overview
The following diagram illustrates the high-level data flow from the client-side SDK through the ingestion pipeline to storage.
The architecture leverages BullMQ for reliable asynchronous event handling and an LRU cache for optimized geolocation lookups.
Sources: PROJECT_OUTLINE.md:144-180, PROJECT_STRUCTURE.md:74-90
Core Components
1. Analytics Web SDK
The analytics-web package is a client-side JavaScript SDK responsible for session management and event tracking. It supports both manual tracking via an API and automatic tracking for common web interactions.
| Feature | Description |
|---|---|
| Session Management | Uses UUID v7 for session identification with a 300s timeout. |
| Auto-Tracking | Page views, scroll depth, element visibility, and outbound links. |
| Manual Tracking | Developers can trigger custom events with arbitrary properties. |
| Error Tracking | Automatically captures JS errors and unhandled promise rejections. |
Sources: packages/analytics-web/index.js, packages/analytics-web/events/auto.js:1-100, PROJECT_OUTLINE.md:120-140
2. Backend API
The API layer, built with Hono and running on Bun, serves as the ingestion point. It extracts client metadata (IP, User Agent), validates the event schema using Zod, and enqueues tasks into BullMQ.
Key Endpoints:
GET /check: Health check.GET /: Returns requester IP and header information.POST /event: IngestsAnalyticsEventdata.
Sources: PROJECT_OUTLINE.md:95-108, PROJECT_STRUCTURE.md:21-30
3. Worker System
The Worker system processes jobs from the ingest-event queue. It performs heavy lifting such as GeoIP lookups and session state management.
Data Schema
The system uses Prisma ORM for structured data storage in PostgreSQL. The schema is designed for time-series analytics and aggregation.
Key Models in schema.prisma
| Model | Purpose | Key Fields |
|---|---|---|
| Event | Raw event data | projectId, name, occurredAt, sessionId, properties, lat, lon |
| AnalyticsSession | Aggregated session state | projectId, sessionId, startedAt, lastSeenAt, eventCount |
| DailyEventAggregate | Pre-computed daily metrics | date, eventName, count, users, sessions |
Sources: packages/db/prisma/schema.prisma:14-80, packages/db/prisma/migrations/20260131205756_newb/migration.sql:35-100
Tech Stack Summary
Glimpse utilizes a modern, performance-oriented stack to handle real-time requirements:
- Runtime: Bun (TypeScript) PROJECT_OUTLINE.md:14
- Frontend: Next.js & Three.js (for 3D visualization) README.md:160-165
- Real-time: WebSockets PROJECT_OUTLINE.md:16
- Queue: BullMQ with Redis PROJECT_OUTLINE.md:17
- Database: PostgreSQL with Prisma ORM package.json:40-45
- Geolocation: MaxMind GeoIP Lite README.md:27
Summary
Glimpse provides a robust pipeline for real-time analytics by combining an automated web SDK with a scalable queue-based worker architecture. Its emphasis on session-based tracking and visual data allows for immediate interpretation of user traffic patterns without compromising individual privacy.