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, A-Frame (WebXR), and Unity, Godot and Unreal web exports
• 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 (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;
            godot-web-export and unity-web-export — engine sample projects
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

• Manual testing guide
• Architecture overview
• Phase plans
• Architecture Decision Records
• Contributing
• Agent guide (AGENTS.md)

License

The open-source product (oss/, examples/, infra/, docs/) is licensed under Apache-2.0.