API Service Overview

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/app.ts
• index.ts
• PROJECT_OUTLINE.md
• PROJECT_STRUCTURE.md
• package.json
• docker/docker-compose.yml
• app/workers/eventWorker.ts

The API Service serves as the primary entry point for the Glimpse analytics platform. It is a high-performance HTTP service built using the Hono framework and running on the Bun runtime. Its primary responsibility is to receive tracking events from client-side SDKs, extract request metadata such as IP addresses and headers, and route these events to a background processing pipeline via a job queue.

The service is designed with a "real-time first" philosophy, prioritizing low-latency ingestion of user sessions and traffic data. It handles CORS configuration for cross-origin tracking and provides health monitoring endpoints to ensure system reliability.

Sources: PROJECT_OUTLINE.md:43-46, app/api/app.ts:1-10, index.ts:1-9

Core Architecture and Runtime

The API Service is built on the Bun runtime and utilizes the Hono framework for routing and middleware management. It is designed to be containerized, typically running as an api service within a Docker environment.

System Components

• HTTP Server: Managed by Bun.serve, listening on port 3000.
• Routing Engine: Hono handles middleware (CORS) and routes traffic to specific controllers.
• Job Queue: Events are passed to BullMQ (backed by Redis) to decouple ingestion from heavy processing tasks like geolocation and database writes.
• Error Tracking: Integrated with Sentry for real-time error reporting and instrumentation.

Sources: index.ts:4-9, package.json:28-40, docker/docker-compose.yml:2-21, PROJECT_OUTLINE.md:16-25

Service Data Flow

The following diagram illustrates how a request moves from the client through the API service into the worker queue.

The API service focuses on rapid ingestion, offloading geolocation and persistence to background workers to minimize client wait times.
Sources: PROJECT_OUTLINE.md:130-150, app/api/app.ts:28-40

API Endpoints

The service exposes a focused set of endpoints for health monitoring, debugging, and data ingestion.

Endpoint Definitions

Endpoint	Method	Description
/check	GET	Health check endpoint returning { status: "ok" }.
/event	POST	Primary ingestion point for analytics events. Routes to eventRouter.
/	GET	Debug endpoint returning client IP and request headers.
/debug-sentry	GET	Test endpoint that throws an error to verify Sentry integration.

Sources: app/api/app.ts:21-39, PROJECT_OUTLINE.md:209-224

Request Context Extraction

The API specifically extracts metadata from the incoming request context to enrich event data before it reaches the worker.

app.get("/", (c) => {
  const ip = getIP(c);
  const headers = Object.fromEntries(c.req.raw.headers.entries());

  return c.json({
    ip,
    headers,
  });
});

Sources: app/api/app.ts:31-39

Configuration and Middleware

The service relies on environment variables for infrastructure connectivity and implements global middleware for security and observability.

Global Middleware

• CORS: Configured to allow all origins (*) by default, supporting standard methods (GET, POST, etc.) and specific headers like Authorization and Content-Type.
• Sentry: Preloaded via sentry.ts in the start script to provide automatic instrumentation of the Hono application.

Sources: app/api/app.ts:10-19, package.json:11-15

Environment Variables

Variable	Default/Context	Description
REDIS_HOST	redis	Hostname for the Redis instance used by BullMQ.
REDIS_PORT	6379	Port for Redis connectivity.
DATABASE_URL	N/A	PostgreSQL connection string for Prisma.
SENTRY_DNS	N/A	Data Source Name for Sentry error tracking.

Sources: docker/docker-compose.yml:14-20, README.md:55-65

Infrastructure Integration

The API service is designed to work in tandem with a Redis-backed worker system.

The API service remains stateless, allowing it to scale horizontally while the background workers handle the stateful operations and database interactions.
Sources: app/workers/eventWorker.ts:88-120, PROJECT_OUTLINE.md:135-160

Conclusion

The API Service is the lightweight, high-throughput gateway of the Glimpse platform. By leveraging Bun and Hono, it ensures that event ingestion is performed with minimal overhead. Its primary function is to act as a bridge between client-side tracking and the server-side processing pipeline, ensuring that every user interaction is captured, enriched with metadata, and reliably queued for analysis.