Architecture Overview

This document provides an overview of Bklit's architecture and how components work together.

System Architecture

Bklit is built as a modern, scalable analytics platform with the following architecture:

Frontend Applications

• Dashboard - Next.js app for viewing analytics
• Website - Marketing site
• Playground - SDK testing app
• Docs - Documentation site

Backend Services

• API Layer - tRPC for type-safe APIs
• Analytics Service - ClickHouse for analytics data
• Database - PostgreSQL for application data
• Auth Service - Better Auth for authentication

Data Flow

1. SDK connects to WebSocket server (wss://bklit.ws)
2. WebSocket Server validates tokens and enriches with geolocation
3. Events queued in Redis for reliable processing
4. Worker processes queue in batches and stores in ClickHouse
5. WebSocket broadcasts events instantly to connected dashboards
6. Dashboard receives real-time updates (under 1 second latency)

Technology Stack

Frontend

• Next.js 15 (App Router)
• React 19
• TypeScript
• Tailwind CSS v4
• shadcn/ui components

Backend

• tRPC for APIs
• Prisma for database
• Better Auth for authentication
• ClickHouse for analytics

Infrastructure

• PostgreSQL database
• ClickHouse for analytics
• Resend for email
• Polar.sh for billing

Monorepo Structure

See Monorepo Structure for detailed structure.

Data Storage

PostgreSQL

Stores:

• Users and authentication
• Organizations and projects
• API tokens
• Event definitions
• Funnels

ClickHouse

Stores:

• Page view events
• Custom events
• Session data
• Analytics aggregates

Authentication Flow

1. User signs in with GitHub/Google
2. Better Auth handles OAuth
3. Session created and stored
4. Protected routes check session
5. tRPC procedures verify authentication

Analytics Flow (WebSocket Architecture)

Bklit uses WebSocket architecture for instant real-time analytics:

Event Tracking

1. SDK establishes WebSocket connection to wss://bklit.ws
2. Events sent over persistent connection (pageviews, custom events)
3. Token validation with Redis caching
4. IP geolocation via ip-api.com
5. Events queued in Redis for processing
6. Instant broadcast to connected dashboards

Background Processing

1. Worker polls Redis queue every 1 second
2. Pops up to 100 events in batch
3. Looks up EventDefinition UUIDs from Postgres (cached)
4. Creates/updates sessions in ClickHouse
5. Batch inserts events to ClickHouse
6. Publishes to Redis pub/sub for real-time updates

Real-time Updates

1. Worker publishes processed events to Redis
2. WebSocket server subscribes to Redis channel
3. Broadcasts to connected dashboard clients
4. Dashboard UI updates instantly

Benefits

• 100x faster ClickHouse writes (batch vs single inserts)
• Zero data loss - Redis queue with AOF persistence
• Scalable - Add more workers for higher throughput
• Observable - /terminal UI shows complete pipeline

Billing Flow

1. User upgrades via Polar checkout
2. Polar webhook received
3. Organization plan updated
4. Features enabled/disabled
5. Usage limits adjusted

Related Documentation

• Monorepo Structure - Project structure
• Getting Started - Setup guide