docs
Dashboard

Dashboard

The internal staff tool at web/apps/dashboard — crash reports, team, resources.

Lives at web/apps/dashboard, port 3002 locally. Next.js, no relation to the marketing site's design beyond sharing @repo/ui's brand tokens — this is an internal tool, not a public-facing page, and robots.ts says so.

A second, separate identity system

Signing in here has nothing to do with the iOS app's device tokens. A dashboard account is a named person with a real password (dashboard_users, Argon2-hashed) — see Authentication for how the two systems stay apart.

Pages

  • Overview (/dashboard) — a 14-day report trend and a status breakdown, built with recharts.
  • Crash Reports (/dashboard/crash-reports) — search, filter by platform/severity/status, and a per-status count strip that doubles as a filter (click a tile to filter by it). Each report's detail page has an inline-editable status/severity panel and, for admins, a "Publish to GitHub" button — once published, status stays in sync with the linked issue in both directions, see Admin & Crash Reports → GitHub status sync.
  • Products (/dashboard/products) — browse/search the product catalogue and edit the curated field set (name, brand, category, ingredients, allergens, nutrition facts, additives, and a few classification flags). Verifying a product is a separate admin-only action from editing its data. See Admin & Crash Reports → Products.
  • Users (/dashboard/users) — read-only: search app users (device rows, not dashboard staff) by device id, email, or name, filter by active Plus status, and see contribution stats per user. No edit actions — this closes a visibility gap, not an editing one.
  • Team (/dashboard/team) — every account with dashboard access. Admins can change a role, reset a locked-out teammate's password, invite a new teammate, grant a member product-edit rights, or remove an account — the last admin can't demote or remove themselves, so the team can't lock itself out.
  • Activity (/dashboard/activity, admin-only) — an audit log of who changed what: role changes, password resets, invites, removals, crash report status changes (including ones synced in from GitHub), and product edits/verifications.
  • Resources (/dashboard/resources) — static links grouped by audience (newcomer, contributor, staff), out to this docs site and the GitHub repo. Nothing here needs the backend.

Roles & Permissions

Three roles define access across the dashboard:

RolePermissions & Access
adminFull access. Manage team roles, reset passwords, grant product edit rights, remove members, verify products, publish crash reports to GitHub, view activity logs.
memberFull workspace browsing. View overview, browse/search products and user accounts, view team list, triage crash reports. Can edit products if granted can_edit_products.
new-userLimited newcomer access. Self-registered accounts start here. Can view crash reports, manage their own profile and password, and request access/elevation from an administrator.

The first account ever registered becomes admin automatically. Invited teammates start as member. Self-registered accounts start as new-user.

Access Requests & Webhooks

When a new-user submits an access request (or when an admin elevates permissions), the backend triggers an instant webhook notification (configured via NOTIFICATION_WEBHOOK_URL) to notify connected Slack, Discord, or custom webhook channels. Admins can promote new-user accounts directly from the Team tab.

Where crash reports come from

Two paths into the same crash_reports table, distinguished by source:

  • app — the iOS app's own CrashReporter (MetricKit) posts to the unauthenticated POST /api/v1/crash-reports on a later launch after a real crash. See iOS Architecture. reported_by is null.
  • manual — a staff member uses the dashboard's "New report" form for anything with no automated path yet (a TestFlight crash log, a user email). reported_by is set to whoever filed it.

Local dev

cd web/apps/dashboard
cp .env.example .env
bun install
bun run dev   # :3002

DATABASE_URL in that .env points Prisma at the same Postgres database the Rust backend uses — for typed local queries only. backend/migrations/ stays the one migration authority; never run prisma migrate against it. NEXT_PUBLIC_API_URL is where the browser sends requests (defaults to http://localhost:8080), and NEXT_PUBLIC_DOCS_URL is what the Resources page links out to.

GitHub publishing and sync need their own config

The "Publish to GitHub" button calls the backend's POST /admin/crash-reports/{id}/github-issue, which needs GITHUB_TOKEN and GITHUB_REPO set in backend/.env. Syncing a status change back in from GitHub needs a webhook registered on the repo plus GITHUB_WEBHOOK_SECRET set. Any of these left unset just means that one piece fails with a clear error — everything else keeps working. See Admin & Crash Reports → GitHub status sync for the webhook setup.

On this page