Web Application Overview
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Glimpse Web Application serves as the frontend interface for a real-time user analytics platform. Its primary purpose is to provide users with a visual dashboard—including a live map and event visualization—to monitor website traffic and user interactions as they occur. By tracking sessions rather than individuals, the application emphasizes traffic patterns and real-time activity over personal identities.
The web application is built using the Next.js framework and React, utilizing Three.js and React Three Fiber for 3D visualizations, such as the live global map. It integrates with the broader Glimpse ecosystem, which includes a Bun-based backend API and a BullMQ worker system for processing analytics events.
Sources: PROJECT_OUTLINE.md:5-13, README.md:1-10, README.md:144-149
Core Architecture
The web application is structured as a modern Next.js project using the App Router directory. It is positioned within a monorepo structure, allowing it to share database clients and schema definitions with the backend and worker services.
Framework and Stack
The application leverages a specific set of technologies to achieve real-time rendering and consistent styling:
| Category | Technology |
|---|---|
| Framework | Next.js 15.1.6 (React 19) |
| Styling | Tailwind CSS 4, Lucide React icons |
| Visualization | Three.js, React Three Fiber |
| Database ORM | Prisma |
| Type Safety | TypeScript |
Sources: app/web/package.json:20-33, PROJECT_OUTLINE.md:21-34, README.md:144-150
Application Flow
The following diagram illustrates how the web application interacts with the Glimpse backend and data layers to display real-time analytics.
Note: The web application consumes processed data from Redis and PostgreSQL while receiving real-time updates via WebSockets.
Sources: PROJECT_OUTLINE.md:140-180, app/web/src/app/page.tsx:2-3
Component Structure and Styling
The application utilizes a standardized component configuration and global styling system to maintain a consistent "Dark Mode" aesthetic.
Global Configuration
The project uses components.json to manage UI component standards, including the use of Tailwind CSS variables and the Lucide icon library.
- Style: New York
- Base Color: Neutral
- CSS Variables: Enabled
- Font: Geist Sans (Sans) and Geist Mono (Mono)
Sources: app/web/components.json:1-20, app/web/src/app/layout.tsx:5-14
Theming and UI Layers
Styling is managed through Tailwind CSS 4 and a series of OKLCH color variables defined in the global CSS. The system is optimized for a dark interface while supporting standard UI components like cards, popovers, and sidebars.
Sources: app/web/src/app/globals.css:50-135
Data Integration
The web application directly imports shared packages from the Glimpse monorepo to maintain data consistency.
Shared Modules
The application uses TypeScript path aliases to access shared database and utility packages:
@glimpse/db/*: Points to the shared Prisma client and database logic.@glimpse/shared/*: Points to shared Zod schemas and utility functions.
Sources: app/web/tsconfig.json:21-25
Database Connectivity
Server-side components within the web application, such as page.tsx, initialize connections to both Redis and PostgreSQL (via Prisma) to fetch session counts and event logs.
import { redis } from "@glimpse/db/redis";
import { prisma } from "@glimpse/db/client";
Sources: app/web/src/app/page.tsx:2-3
Deployment and Environment
The web application is designed to run alongside the API and Worker services.
| Environment Variable | Purpose |
|---|---|
DATABASE_URL | Connection string for PostgreSQL |
REDIS_HOST | Hostname for the Redis server |
PORT | Port for the web server (defaults to 3001 in dev to avoid conflicts) |
Sources: README.md:111-125, README.md:41-45
Conclusion
The Glimpse Web Application provides the visual layer of the analytics ecosystem. By leveraging Next.js for structure and React Three Fiber for 3D mapping, it enables a real-time, session-based view of global traffic. Its integration with shared monorepo packages ensures that the frontend remains synchronized with the backend processing pipeline and database schema.
Sources: PROJECT_OUTLINE.md:5-10, README.md:144-150