Monorepo Design & Packages
Relevant source files
The following files were used as context for generating this wiki page:
Glimpse is organized as a modular monorepo that separates core application logic, shared infrastructure, and client-side SDKs. The design leverages Bun workspaces to manage dependencies across various internal packages, ensuring a unified development environment while maintaining strict boundaries between the frontend, backend API, and background worker systems.
The architecture is built to support real-time data ingestion and visualization, utilizing a centralized database package for schema management and shared utility packages to maintain type safety across the entire stack.
Sources: PROJECT_STRUCTURE.md, package.json:11-14, PROJECT_OUTLINE.md:162-170
Workspace Architecture
The project utilizes a monorepo structure defined in the root package.json under the workspaces field. It categorizes code into two primary directories: apps/ for deployable services and packages/ for reusable modules and shared infrastructure.
The diagram illustrates the dependency relationship where applications consume shared logic and database clients from the packages directory.
Key Workspace Definitions
| Workspace Category | Path | Purpose |
|---|---|---|
| Packages | packages/* | Shared libraries including DB clients, schemas, and the Web SDK. |
| Applications | apps/* | Deployable units like the Next.js frontend. |
| Core Apps | app/* | Direct application logic for the API and background workers. |
Sources: package.json:11-14, PROJECT_STRUCTURE.md:39-86, tsconfig.json:11-15
Core Packages
Database Package (/packages/db)
The database package serves as the single source of truth for the system's data models. It contains the Prisma schema and handles client initialization for both PostgreSQL and Redis. This package is shared across the API, workers, and web application to ensure consistent data access.
Key Components:
- Prisma Schema: Defines entities for
events,analytics_sessions, and various daily aggregates. - Client Initialization: Exports configured instances of the Prisma and Redis clients.
Sources: PROJECT_STRUCTURE.md:65-70, packages/db/prisma/schema.prisma:1-125
Shared Package (/packages/shared)
This package contains cross-cutting concerns that do not belong to a specific service. It primarily focuses on validation and utility functions.
- Schemas: Centralized Zod definitions for event validation (
AnalyticsEvent). - Utilities: Shared logic for IP extraction and Redis connection management.
Sources: PROJECT_STRUCTURE.md:72-78, PROJECT_OUTLINE.md:112-121
Analytics Web SDK (/packages/analytics-web)
A client-side JavaScript SDK designed for integration into external websites. It manages event lifecycle, session state, and automated tracking.
- Auto-tracking: Automatically captures page views, scroll depth (10%, 25%, 50%, 75%, 90%, 100%), and outbound link clicks.
- Transport: Utilizes a sender module to dispatch events to the Glimpse API via HTTP.
Sources: packages/analytics-web/events/auto.js:9-38, PROJECT_STRUCTURE.md:54-63
Data Modeling & Schema
The system uses a highly indexed PostgreSQL schema via Prisma to support real-time querying and historical analysis.
The ER diagram shows the relationship between individual events and their parent sessions, scoped by project ID.
Primary Data Structures
| Model | Description | Primary Key |
|---|---|---|
Event | Individual tracked user actions with GeoIP data. | id (BigInt) |
AnalyticsSession | Aggregated session-level data and activity tracking. | [projectId, sessionId] |
DailyEventAggregate | Pre-computed daily counts for events per project. | [projectId, date, eventName] |
Sources: packages/db/prisma/schema.prisma:17-50, packages/db/prisma/schema.prisma:52-70, packages/db/prisma/schema.prisma:73-84
Development & Build Configuration
The monorepo uses a unified TypeScript configuration with path mapping to allow seamless importing of packages without relative path complexity.
Path Mapping
The project uses the @glimpse/ namespace to reference internal packages. These are defined in tsconfig.json to point to the relevant package directories.
"paths": {
"@glimpse/db/*": ["packages/db/*"],
"@glimpse/shared/*": ["packages/shared/*"]
}
Sources: tsconfig.json:11-15, app/web/tsconfig.json:20-23
Service Orchestration
Docker Compose is used to orchestrate the various services and their dependencies (Postgres, Redis). Each service builds from the root Dockerfile but executes different entry points.
| Service | Entry Point | Purpose |
|---|---|---|
api | index.ts | HTTP/WebSocket event ingestion. |
worker | workers.ts | BullMQ background job processing. |
analytics-worker | app/analytics-worker/analyticsWorker.ts | Data aggregation and pipeline logic. |
Sources: docker/docker-compose.yml:2-63, package.json:15-22
Summary
The Glimpse monorepo design facilitates a clear separation between the client-side SDK (analytics-web), the data persistence layer (db), and the application services (api and workers). By utilizing Bun workspaces and centralized TypeScript path mappings, the architecture ensures that breaking changes in the database schema or shared validation logic are immediately reflected across all consuming services.
Sources: PROJECT_STRUCTURE.md:1-105, PROJECT_OUTLINE.md:1-170