Builder: apps/admin/ — admin dashboard (analytics, engagement, ops)

[0800tim]

Builder agent assignment. This issue is the canonical handoff for apps/admin/ — the VTorn admin dashboard. Paste the prompt below into a fresh Claude Code / Cursor / Aider session opened in the repo root.

The prompt complements AGENT-PROMPTS.md (which targets the AR-FR demo) — this is the next major lane.

Design pointers:

• docs/23-analytics-and-marketing-insights.md — the events, engagement scoring, and surfaces this dashboard exposes.
• docs/22-deployment-and-tunnels.md — port assignments, caching matrix, performance budgets.

When you ship: open a PR against main with the agent:admin label and link this issue with Closes #N. The reviewer agent picks it up from there.

---

You are a code agent building apps/admin/ — the VTorn admin dashboard.

REPO ROOT: VTorn at GitHub 0800tim/vtorn (private). PRs #1, #2, #7, and
#9 (infra/conventions) are merged on main; the four parallel AR-FR
builders are working in their own worktrees and will land in parallel.
You are the admin-dashboard agent.

START HERE
1. Read CLAUDE.md fully — agent operations protocol + performance/caching review.
2. Read docs/23-analytics-and-marketing-insights.md fully — your contract.
3. Skim docs/22-deployment-and-tunnels.md for port assignments and the
   caching matrix.
4. Skim docs/09-agent-task-breakdown.md for where this fits in the agent
   matrix.
5. The events table schema and engagement scoring formulas in doc 23 are
   your data model. The events table doesn't physically exist yet — your
   PR ships a Prisma migration that creates it, plus a seeding script
   that fills it with realistic dev fixtures so the dashboard renders
   non-empty.

WHAT YOU'RE BUILDING

A Next.js 14 (app router) + React + Tailwind + shadcn/ui app at
apps/admin/, served on:
- Dev:  https://vtorn-admin.aiva.nz   → http://localhost:3330  (you must
        request the orchestrator add this tunnel — DO NOT touch
        cloudflared yourself; open a PR-comment requesting it)
- Prod: https://admin.vtorn.com (later)

Routes (read-only first; editing controls in a follow-up PR):
- /                    Live counters (concurrent viewers, predictions/min,
                       latest signups, latest shares). Updates via
                       /v1/admin/live SSE endpoint backed by Redis stream.
- /today               DAU, signups, predictions, share-clicks, conversion
                       funnel (signup → first match → first prediction →
                       first share). Cards + a small chart per metric.
- /trends              Last 7 / 30 days: cohort retention, engagement-score
                       distribution histogram, geo heatmap, channel
                       attribution table.
- /users               Search + paginated list. Engagement-score, geo,
                       last-active, prediction count, share count.
- /users/[id]          Drilldown: events timeline, engagement breakdown,
                       bot interactions, predictions w/ IQ.
- /tournaments         List + detail; v1 read-only.
- /audit               Admin action audit log (read-only feed).

Auth: bearer-token middleware against an env-configured ADMIN_EMAILS
allowlist (Tim email + a few). Token rotation later. Don't ship
hard-coded credentials.

Data sources:
- Postgres events table (Prisma).
- Redis (engagement scores in `vtorn:eng:{user_id}`, live stream
  `vtorn:events`).
- GA4 Data API (only for /trends channel attribution; gate with a
  feature flag because tokens may not be configured in dev).

Performance:
- p95 TTFB < 400ms on cached pages. Use Next 14 server components +
  cache() for the read-side.
- Live counters: stream via SSE; fall back to a 5s poll if SSE fails.
- 60fps interactions (charts virtualised; no heavy DOM blow-ups).

Stack details:
- pnpm. The app belongs in pnpm-workspace.yaml.
- shadcn/ui for primitives; Tailwind for styling.
- Recharts (or Tremor) for charts — pick the smaller bundle.
- Prisma for the events schema migration.
- vitest + Playwright e2e (smoke: log in as admin, see today page,
  navigate to a user drilldown).

ACCEPTANCE
- Visiting https://vtorn-admin.aiva.nz with a valid admin bearer token
  shows the live page with non-zero (seeded) data.
- /today shows the conversion funnel from seeded events.
- /users search finds a user by email or username (case-insensitive).
- /users/[id] shows their events timeline and engagement score.
- Playwright smoke (log in → today → drilldown) passes in CI.
- Bundle size for the dashboard root route ≤ 180KB gzipped (warning if
  over).
- All read endpoints have a documented Cache-Control policy matching
  docs/22.

OPS DISCIPLINE (mandatory)
- You are in a git worktree. `pwd` shows your isolated working dir.
- Branch: feat/admin-dashboard.
- Session note: sessions/2026-05-09_admin-builder_initial-build.md.
- Set local git config: user.name "Tim Thomas", user.email "0800tim@gmail.com".
- Conventional Commits + DCO sign-off (git commit -s).
- Open the PR with: gh pr create --base main \
    --title "feat(admin): admin dashboard MVP (read-only)" \
    --body-file <path>.
  PR body ends with "Closes #N" pointing at this issue.

DO NOT
- Modify the spec or packages/spec.
- Modify cloudflared. Request the orchestrator add the
  vtorn-admin.aiva.nz tunnel via a PR comment.
- Add raw PII to logs. Hash IP/UA per doc 23.
- Hardcode the admin email allowlist — read from env.
- Block on the engagement-scorer or apps/api existing — stub their
  outputs from a seed script and wire them as TODO once they ship.
- Push to main directly.

When your PR is open, report back with: PR URL, branch name, what's
covered, what's deferred (bot policy editor / tournament editing / GA4
trends if API token absent), and any open questions for the orchestrator.
Then stop.