Skip to content
Joe BI Platform
Esc
↑↓navigate↵open⌘Jpreview
On this page

Joe BI Platform Handbook

How to use Joe's internal BI and reporting platform - dashboards, scheduled reports, embeds, and the data behind them.

Joe BI Platform Handbook

This is the operating manual for Joe’s BI platform: the system replacing Looker. It covers everything an analyst needs: where the dashboards live, how the data flows, how scheduled reports work, and how to get new reports built.

The platform in one picture

Aurora (source of truth, production app DB)
   |
   |  nightly ledger sync (~05:20 UTC) + 20-second live feed for today
   v
Data plane (PlanetScale Postgres + Cloudflare Worker at data-plane.joe.coffee)
   |  fact tables, transaction ledger, bi.* views  <- the semantic layer
   |
   +--> Metabase (joe-metabase.fly.dev) ........ internal dashboards + ad-hoc SQL
   +--> Scheduled reports (email CSV/XLSX/PDF) .. replaces Looker schedules
   +--> Signed embeds ........................... merchant-facing dashboards
   +--> Webhook feeds ........................... Zapier / POS integrations

Two rules explain almost everything about this system:

  1. Metrics are computed once, at ingestion. Every consumer (Metabase, emails, embeds, exports) reads the same pre-computed values and only does SUM / GROUP BY. Nobody re-derives net sales in a dashboard formula. If a metric definition needs to change, it changes in the sync code and in the data dictionary, and every surface picks it up automatically.
  2. There are two data paths. The reporting path (nightly-synced ledger and fact tables) is complete through yesterday. The live path (20-second feed) covers today. Reports about closed days use the reporting path; anything about “right now” uses the live path. If a number for today looks different from a number for yesterday, this is why.
Surface Where
Metabase (dashboards + SQL) https://joe-metabase.fly.dev
Reports admin (subscriptions) https://data-plane.joe.coffee/v1/reports/admin
Stable merchant dashboard links https://data-plane.joe.coffee/e/<reportKey>/<shopUuid>
API reference (OpenAPI) https://data-plane.joe.coffee/docs
This handbook’s source joe-data-plane/docs/handbook/

Use /e/<reportKey>/<shopUuid> for human-friendly dashboard links. Plain links check the viewer’s shop access at click time and never expire; the reports admin can generate 7/30/90-day signed versions for recipients without a session. See Merchant-facing embeds and links.

Where to start

Was this page helpful?