Development Workflow
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The development workflow for Glimpse is designed around a monorepo structure using Bun as the primary runtime and package manager. The project follows a decoupled architecture where the API, background workers, and frontend web application operate as distinct services coordinated via Docker or individual process runners. This workflow supports real-time data processing by integrating high-performance tools like Redis for queuing (BullMQ) and PostgreSQL for long-term persistence.
The environment is built to facilitate rapid iteration through hot-reloading (via bun --watch) and a containerized infrastructure that mirrors production environments. Developers interact with multiple layers of the stack, including a Web SDK for event ingestion, a Hono-based API for reception, and TypeScript-driven workers for geolocation and database buffering.
Sources: PROJECT_STRUCTURE.md, PROJECT_OUTLINE.md, README.md
Local Development Environment
The Glimpse project provides two primary methods for setting up the development environment: a containerized Docker-based approach for full-stack orchestration and a standalone service approach for focused development on specific modules.
Service Orchestration
The project uses Docker Compose to manage the lifecycle of various dependencies and application services. This ensures that the database, cache, and application layers are correctly networked.
The diagram shows the service interdependencies defined in the Docker configuration.
Development Commands
Developers use the following scripts defined in the root and sub-package manifests to execute the application:
| Command | Action | File Context |
|---|---|---|
bun run dev | Starts the API server with hot-reload and Sentry preloading. | package.json |
bun run worker | Starts the background event processing worker. | package.json |
bun run prisma:migrate | Synchronizes the database schema with Prisma models. | package.json |
bun run dev (in /app/web) | Starts the Next.js frontend application. | app/web/package.json |
Sources: package.json:11-19, app/web/package.json:6-14
Frontend & SDK Integration
The frontend development involves working with a Next.js application and the analytics-web SDK. The SDK is designed to be embedded in web pages to capture user interactions automatically or manually.
SDK Event Lifecycle
The analytics-web package manages session lifecycles and event transport. It uses various triggers to capture data, such as visibilitychange for page focus and beforeunload for session termination.
This sequence illustrates how the SDK captures and transmits events during a typical user session.
Sources: packages/analytics-web/events/auto.js:1-125, PROJECT_OUTLINE.md
Backend Data Processing Workflow
The backend workflow is centered on asynchronous job processing. When the API receives an event, it is not immediately written to the database; instead, it enters a high-speed pipeline.
Event Processing Pipeline
- Ingestion: The API validates the event against a Zod schema and pushes a job to the
eventQueuein Redis. - Worker Processing: The
eventWorkerpicks up the job, performs GeoIP lookups, and updates active session counts in Redis. - Buffering: To optimize performance, events are stored in an in-memory
eventBuffer. - Batch Persistence: The buffer is flushed to PostgreSQL using Prisma's
createManywhen it reaches 100 events or every 1000ms.
Diagram representing the asynchronous path from event reception to database storage.
Sources: app/workers/eventWorker.ts:40-140, PROJECT_OUTLINE.md
Database & Schema Management
Developers use Prisma ORM to manage the data model. The workflow requires generating the Prisma client after any schema changes to maintain type safety across the monorepo.
| Entity | Purpose | Key Fields |
|---|---|---|
Event | Stores granular user interactions. | projectId, name, occurredAt, ip, lat, lon |
AnalyticsSession | Tracks aggregated session state. | sessionId, eventCount, startedAt |
DailyPageAnalytics | Stores pre-aggregated metrics for the dashboard. | pagePath, views, uniqueUsers |
Sources: packages/db/prisma/schema.prisma:17-112, package.json:15-18
Summary
The Glimpse development workflow prioritizes performance through a "queue-first" architecture. By leveraging Bun for execution and BullMQ for task management, the system ensures that the ingestion of analytics events remains non-blocking. Developers manage the system through a combination of Docker orchestration and localized Bun scripts, ensuring a consistent environment from SDK integration to database persistence.
Sources: PROJECT_OUTLINE.md, README.md