Lightweight, privacy-first analytics platform.
Pre-Alpha Prototype — Beacon is under active development. APIs may change.
- Lightweight and simple — Minimal API surface, robust/well-tested code, performance over feature bloat
- Tiny client SDK — <1KB worker gzipped (838B), runs in a Web Worker off the main thread
- Self-host friendly — Easy to fork and customize for your organization
- Privacy compliant — Built for FedRAMP and HIPAA, designed for healthcare
- Scale on simplicity — Push Postgres and Gleam (Erlang BEAM) as far as they go
| 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 | - |
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)Client App → @beacon/sdk (Web Worker) → WebSocket → Gleam API (BEAM) → PostgreSQL
↓
WAL (logical)
↓
SvelteKit Dashboard ←── Zero Cache
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.
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
# 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| 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 |
Required .env:
DATABASE_URL=postgres://beacon:beacon@localhost:5432/beacon?sslmode=disable
PORT=4000
MIT
