Uptimizr
3D scene analytics — like web analytics, but for 3D applications.
Documentation · Quickstart · Run the collector
Uptimizr captures and visualizes how people actually use 3D scenes: where they
look (view-direction heatmaps), where they point and click (2D + 3D raycast
heatmaps), which meshes they interact with, how the scene performs (FPS, device/GPU,
asset load times), and any custom events a developer wants to track. It can also
replay an individual session inside the developer's own scene.
Web analytics is built for 2D HTML pages and custom events; it has no concept of a
camera, a view vector, or a mesh. Uptimizr fills that gap.
Self-hostable, open source
Uptimizr is an open-source data-collector — a self-hostable SDK + ingestion + dashboard,
licensed Apache-2.0. Run it on a single embedded DuckDB file with no external database service,
or switch to a Postgres, SQL Server or ClickHouse store when you need multi-writer scale.
Live demo
Try it with zero setup at demo.uptimizr.com — a fully
in-browser test drive: the playground and dashboard run side-by-side, and the analytics database
runs on your device via DuckDB-Wasm. No account, no server, nothing uploaded; closing the tab
wipes everything. From source, run it with pnpm dev:web (demo on http://localhost:4320). See
oss/apps/demo.
Tech stack
- Monorepo: pnpm workspaces + Turborepo · TypeScript everywhere
- Ingestion/query API: Fastify (ADR 0005)
- Dashboard: Next.js + Tailwind
- Event store (default): a single embedded DuckDB file holds events and metadata — no
external database service (ADR 0020)
- Event store (optional): a single-tenant Postgres store (
COLLECTOR_STORE=postgres) for
self-hosters who already run Postgres, a single-tenant SQL Server store
(COLLECTOR_STORE=mssql) for shops standardized on SQL Server / Azure SQL, or the ClickHouse scale tier
(COLLECTOR_STORE=clickhouse) for high-volume ingestion
(ADR 0002)
- 3D connectors: Babylon.js, Babylon Lite, three.js, react-three-fiber, PlayCanvas, and
A-Frame (WebXR)
- Privacy: cookieless / GDPR-first by default (ADR 0003)
Repository layout
oss/ Open-source product (Apache-2.0)
apps/ collector-server (Fastify), dashboard (Next.js), demo (in-browser test drive),
docs (documentation site), web (landing site)
packages/ schema, sdk-core, replay, react (embeddable panels), heatmap,
create-uptimizr (scaffolder);
the agent layer: metrics (semantic metric registry), agent-core (generated read-tool
catalog + agent loop), mcp (read-only MCP server), agent-eval (private evaluation
harness, not published);
the stores: db (DuckDB + dialect-agnostic contracts), db-postgres, db-mssql and
db-clickhouse (optional);
and the connectors: sdk-babylon, sdk-babylon-lite, sdk-three, sdk-r3f, sdk-playcanvas,
sdk-aframe, plus the web-export tier (web-export foundation + unity, godot, unreal)
examples/ playground — multi-engine demo scene for end-to-end testing
infra/ docker-compose for the optional ClickHouse, Postgres and SQL Server engines
docs/ architecture, phase plans, and ADRs
Getting started
There are two ways in, depending on whether you're using Uptimizr in your own app or working on
the project itself.
Use Uptimizr in your app (from npm — no clone)
You don't need this repo to use Uptimizr. Install a connector from npm and run the collector
straight from npm:
npm i @uptimizr/babylon # or @uptimizr/three, @uptimizr/r3f, @uptimizr/playcanvas, @uptimizr/aframe, @uptimizr/unity, @uptimizr/godot, …
npm create uptimizr@latest # scaffold a self-host (prompts to add the dashboard + a demo)
# …or run the collector CLI directly:
npx -p @uptimizr/collector-server uptimizr init # create the DuckDB store + a project + owner API key
npx -p @uptimizr/collector-server uptimizr serve # ingestion + query API on http://localhost:4318
See the Quickstart and
Run the collector for the full guide.
Work on Uptimizr from source (contributors)
The commands above are all you need to use Uptimizr. The rest of this section is for contributing
to the project itself — clone the repo and run it from source. The open-source collector stores
everything in a single DuckDB file, so running from source needs no external database service:
pnpm install
pnpm build # turbo build across all packages
pnpm lint && pnpm typecheck && pnpm test
cp .env.example .env # DUCKDB_PATH defaults to ./data/uptimizr.duckdb
pnpm db:setup # create the DuckDB file + seed a project & API key
pnpm dev:collector # Fastify ingestion + query API (COLLECTOR_STORE=duckdb)
pnpm dev:dashboard # optional: the analytics dashboard
- Back up = copy the
.duckdb file. Reset = delete it and re-run pnpm db:setup.
- Single-writer constraint: DuckDB is embedded and single-writer — only one process may open
the file read-write at a time. Run a single collector per file. For multi-writer / horizontal
scale, use the optional Postgres, SQL Server or ClickHouse store (
COLLECTOR_STORE=postgres /
COLLECTOR_STORE=mssql / COLLECTOR_STORE=clickhouse, local servers via infra/docker)
(ADR 0020).
To run the full stack locally and verify it end-to-end (collector, dashboard, Babylon
playground, replay), follow the manual testing guide and the
run-local-stack skill. See CONTRIBUTING.md for conventions and house rules.
Documentation
License
The open-source product (oss/, examples/, infra/, docs/) is licensed under
Apache-2.0.
