Project Structure
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Glimpse is a real-time user analytics platform designed for live mapping and event visualization. The project architecture follows a monorepo-style structure that separates core application logic, shared packages, and infrastructure configuration. The system is designed to track user sessions anonymously, focusing on traffic patterns and global visualization rather than individual identities.
Sources: PROJECT_OUTLINE.md:3-8, README.md:1-5
The project's scope encompasses a client-side SDK for event tracking, a high-performance backend API for data ingestion, and a worker system for asynchronous processing. This modular approach allows for scalability, where ingestion (API) is decoupled from heavy processing (Workers) via a job queue.
Sources: PROJECT_STRUCTURE.md:73-81, PROJECT_OUTLINE.md:103-125
Core Directory Architecture
The repository is organized into four primary functional areas: /app for service-specific logic, /packages for reusable modules, /docker for infrastructure, and /test for validation.
/app - Application Services
The app directory contains the executable services that power the platform:
api/: Implements the HTTP and WebSocket endpoints using Hono. It handles incoming event data, performs initial validation, and extracts client metadata such as IP addresses.workers/: Contains background processes using BullMQ. These workers handle geolocation lookups, session management in Redis, and batching events for database persistence.web/: A Next.js frontend application providing the user interface for the live map and dashboard.
Sources: PROJECT_STRUCTURE.md:21-41, PROJECT_OUTLINE.md:65-101
/packages - Shared Modules
Shared logic is abstracted into internal packages to ensure consistency across the API and worker services:
analytics-web: The client-side JavaScript SDK for tracking page views, clicks, and custom events.db: Manages the database connection and the Prisma ORM schema.shared: Contains Zod validation schemas and common utilities like Redis clients and IP extraction logic.
Sources: PROJECT_STRUCTURE.md:43-66, PROJECT_OUTLINE.md:127-151
System Architecture and Data Flow
The architecture utilizes a producer-consumer pattern where the API enqueues jobs into Redis, which are then consumed by background workers.
The diagram above illustrates how events flow from the client SDK through the API for validation, into the BullMQ queue, and finally through the worker for enrichment (geolocation) and storage.
Sources: PROJECT_OUTLINE.md:180-213, docker/docker-compose.yml:1-67
Data Models
The system uses Prisma as an ORM to interact with a PostgreSQL database. The schema focuses on events, sessions, and aggregated analytics data.
| Model | Description | Key Fields |
|---|---|---|
| Event | Individual tracked actions from users. | projectId, name, sessionId, ip, country, lat, lon |
| AnalyticsSession | Groups events into timed sessions. | projectId, sessionId, startedAt, eventCount |
| DailyEventAggregate | Pre-calculated daily counts per event type. | projectId, date, eventName, count |
| DailyPageAnalytics | Aggregated page-level metrics. | projectId, pagePath, views, bounces |
Sources: packages/db/prisma/schema.prisma:13-111
Infrastructure and Deployment
The project is containerized using Docker, allowing for a reproducible development and production environment. The docker-compose.yml file orchestrates the interaction between the application services and their dependencies.
Service Configuration
| Service | Image/Context | Port | Dependencies |
|---|---|---|---|
api | Bun (Custom Dockerfile) | 3000 | postgres, redis |
worker | Bun (Custom Dockerfile) | N/A | postgres, redis |
postgres | postgres:16 | 5432 | None |
redis | redis:7 | 6378 (Mapped) | None |
Sources: docker/docker-compose.yml:3-85, README.md:120-135
Technical Stack Summary
The project leverages modern TypeScript-based technologies for performance and type safety.
This technology stack is selected to support real-time data streaming and 3D visualization of global traffic.
Sources: PROJECT_OUTLINE.md:14-30, README.md:214-222
Summary
The Glimpse project structure is designed for high-throughput event processing. By separating the web SDK, API ingestion, and background worker logic into distinct modules and containers, the architecture ensures that real-time visualization remains responsive even during high traffic volumes. The use of Redis as a buffer and job queue is central to this stability, providing a bridge between the stateless API and the persistent storage layer.
Sources: PROJECT_STRUCTURE.md:73-90, PROJECT_OUTLINE.md:237-251