Beacon

Lightweight, privacy-first analytics platform.

Pre-Alpha Prototype — Beacon is under active development. APIs may change.

Goals

1. Lightweight and simple — Minimal API surface, robust/well-tested code, performance over feature bloat
2. Tiny client SDK — <1KB worker gzipped (838B), runs in a Web Worker off the main thread
3. Self-host friendly — Easy to fork and customize for your organization
4. Privacy compliant — Built for FedRAMP and HIPAA, designed for healthcare
5. Scale on simplicity — Push Postgres and Gleam (Erlang BEAM) as far as they go

Stack

Component	Tech	Port
API	Gleam on BEAM (Mist HTTP/WS)	4000
Dashboard	SvelteKit + Tailwind + Zero	5173
Zero Cache	Rocicorp Zero (sync engine)	4848
Database	PostgreSQL (Docker)	5432
Client SDK	TypeScript, Web Worker, WebSocket	-

Quick Start

Prerequisites

• Node.js 24+
• pnpm 10.x
• Gleam 1.13+
• Docker
• Just
• dbmate

Setup

git clone https://github.com/devdumpling/beacon.git
cd beacon
cp .env.example .env
just setup    # Install deps, start Postgres, run migrations
just dev      # Start API (4000) + Dashboard (5173)

Architecture

Client App → @beacon/sdk (Web Worker) → WebSocket → Gleam API (BEAM) → PostgreSQL
                                                                            ↓
                                                                      WAL (logical)
                                                                            ↓
                                              SvelteKit Dashboard ←── Zero Cache

SDK Usage

import { init, track, identify, page, flag } from "@beacon/sdk";

init({ url: "https://beacon.example.com", apiKey: "bk_your_api_key" });

track("button_clicked", { button_id: "signup" });
identify("user_123", { plan: "pro" });
page();

if (flag("new_feature")) {
  // Show new feature
}

See sdk.md for full API reference.

Project Structure

beacon/
├── apps/
│   ├── api/              # Gleam backend
│   ├── dashboard/        # SvelteKit dashboard
│   ├── example-react/    # React example app
│   └── example-vanilla/  # Vanilla JS example
├── packages/
│   ├── sdk/              # Client SDK (@beacon/sdk)
│   └── example-shared/   # Shared example styles
├── docs/                 # Documentation
├── infra/
│   ├── docker-compose.yml
│   └── migrations/
└── justfile

Commands

# Development
just dev              # Start all services
just dev-api          # Gleam API only
just dev-dashboard    # SvelteKit only

# Database
just db-migrate       # Run migrations
just db-reset         # Drop and recreate
just db-shell         # Open psql

# Test
just test-api         # Gleam unit tests
just test-sdk         # SDK unit tests
just test-integration # Integration tests (requires running server)

# Benchmark
just bench-sdk-size   # Measure SDK bundle sizes
just bench-load       # Run k6 throughput tests (requires server + k6)
just bench-connections # Run k6 connection limits test
just bench-validate   # Verify load test events persisted

# Build
just build            # Build all packages
just lint             # Lint and format

Documentation

Document	Description
Quickstart	Get running in 5 minutes
Roadmap	Road to alpha milestones
SDK Reference	Client SDK installation and API
API Reference	Server endpoints and architecture
WebSocket Protocol	Wire protocol specification
Identity Tracking	User identification system
Benchmarking	Performance benchmarks
CI/CD	GitHub Actions workflows

Environment

Required .env:

DATABASE_URL=postgres://beacon:beacon@localhost:5432/beacon?sslmode=disable
PORT=4000

License

MIT