Huddle

Huddle is a private, synthetic-only morning triage board built as a focused work sample for education-focused software. It helps a teacher or guide decide who to see first, why, and what to say first when adaptive academic software carries practice and adults carry motivation and intervention.

The portfolio demo is deliberately narrow: sign in, upload one fixed CSV, validate and commit it, refresh, inspect the ranked Evidence Desk, expand one exact-evidence disclosure, and see the report acknowledged. It is not a diagnosis product and makes no accuracy claim.

Demo

25-second walkthrough using only synthetic data: the attention queue, import/refresh, and one student report with teacher action guidance. Open the GIF · MP4 fallback · Try the live reviewer demo

Static synthetic-data detail: one ranked report with likely explanation, opening question, confident/struggling branches, listen-for cue, and suggested teaching move.

Why this is useful for educators

• Guide utility: one deterministic queue turns attempt-level activity into a short morning plan.
• Coach-like intervention: every report provides a visible teacher decision map, not another analytics chart.
• Responsible student data: the roster, activity, names, and evaluation corpus are visibly synthetic; real student data is rejected and remains out of scope.
• Trustworthy AI boundary: rules classify and rank without a model. Only an authenticated, manual refresh of synthetic data may call Claude with a bounded packet to draft the likely explanation, first question, and suggested teaching move. The confident/struggling follow-ups and listen-for remain deterministic; nightly refreshes and missing or rejected provider responses persist a complete deterministic fallback card.

Architecture and trust boundaries

Browser (Supabase Auth only)
  -> Next.js Server Components / narrow server actions
  -> @huddle/application use cases
  -> @huddle/db scoped SQL
  -> Supabase PostgreSQL

CSV -> strict synthetic-csv-v1 adapter -> immutable import receipt
    -> deterministic signal engine -> immutable board run/head
    -> Evidence Desk -> signed one-use reveal -> PostgreSQL acknowledgment ledger

Optional narration -> closed catalog + exact bundle slots
Deterministic ranking/evaluation -X-> model client

packages/db is the only package that owns pg; service/database credentials never enter browser code. Supabase Auth sessions are verified server-side and resolve exactly one synthetic guide/studio scope. Browser Data API privileges are revoked by migration. RLS, retention policy, and multi-guide access are mandatory before real data or a pilot and are intentionally not implemented here.

Authoritative deeper contracts: plan, application boundaries, and evaluation posture.

Clean local quickstart

Prerequisites: Node 22, npm, and one clean Supabase project with Postgres 16 + Auth. In Supabase Auth, create one private reviewer email/password account and copy its user UUID. Do not create any real student records.

npm ci
cp .env.example .env
# Fill the two public Auth values, DATABASE_ADMIN_URL, DATABASE_URL,
# SUPABASE_DB_CA_BASE64, HUDDLE_DEMO_AUTH_USER_ID, and
# HUDDLE_ACKNOWLEDGMENT_KEY_CURRENT.
npm run db:migrate
npm run demo:seed
npm run dev

Open http://localhost:3000/login. The reviewed demo uses HUDDLE_DEMO_BOARD_DATE=2026-07-27, so the fixed CSV remains reproducible rather than drifting with the wall clock.

Reset is explicit and scoped to the fixed synthetic demo identity:

npm run demo:reset -- --confirm-synthetic-only

The reset command refuses non-synthetic guide/student identities. Use it only in the dedicated demo project; it clears that synthetic scope's imports, board runs, evidence opens, and acknowledgments, then restores the four-person synthetic roster.

Fixed portfolio evaluation

unset ANTHROPIC_API_KEY
npm run eval:portfolio
npm run verify:quickstart

eval:portfolio regenerates eight deterministic fallback cases in memory and byte-compares them with fallback-corpus.json. Unknown catalog IDs and unauthorized evidence slots must hard-fail for every case. Output records modelCalls: 0 and writes artifacts/portfolio-eval-report.json.

This is evidence for deterministic fallback, grounding, and model-free execution only. It reports no precision, recall, F1, or diagnosis accuracy. The full simulator/holdout/permutation accuracy gate in the evaluation contract remains deferred before any pilot or accuracy-backed claim.

Vercel + Supabase reviewer deployment

vercel.json builds the npm workspace and packages apps/web. Configure these Vercel variables:

• NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
• server-only DATABASE_URL
• server-only SUPABASE_DB_CA_BASE64 (the public Supabase Server root CA, base64 encoded)
• server-only HUDDLE_ACKNOWLEDGMENT_KEY_CURRENT
• server-only ANTHROPIC_API_KEY for the authenticated manual synthetic-refresh draft only; never use a NEXT_PUBLIC_ name or expose it in source, logs, screenshots, or chat. Adding or changing any Vercel variable requires a new deployment before the runtime receives it.
• HUDDLE_DEMO_BOARD_DATE=2026-07-27
• INTERNAL_REFRESH_SECRET only if the protected nightly dispatcher will be used

Do not put DATABASE_ADMIN_URL, HUDDLE_DEMO_AUTH_USER_ID, a Supabase service-role key, or any credential in browser-visible variables. Run migrations and demo:seed from a trusted operator terminal before deployment. The reviewer-facing /board and /import operations require the Supabase account; unauthenticated requests expose no roster, evidence, or freshness.

The stable production alias, https://huddle-tsa-portfolio-demo.vercel.app, is intentionally reachable at the Vercel layer so reviewers can reach Huddle's sign-in page. Supabase application Auth protects /board, /import, roster, evidence, and freshness. Generated immutable deployment URLs may remain behind Vercel Authentication; do not change protection settings merely to make them public. Send the reviewer the separate Supabase guide credentials through a private channel.

Deploy from the repository root with the pinned CLI version so the committed vercel.json and workspace build are used consistently:

npx --yes vercel@48.8.0 deploy --prod

Create a Vercel Protection Bypass for Automation secret for the hosted smoke only, set it as VERCEL_PROTECTION_BYPASS in the operator's gitignored .env, and run:

npm run smoke:hosted -- --base-url https://YOUR-PRIVATE-DEMO.vercel.app

Use that smoke only with a protected generated deployment URL, not the stable production alias. It checks health/policy output, the sign-in page, the fixed synthetic CSV, and fail-closed anonymous board access through the protection wall. Never add the bypass value to Vercel's application environment or share it with the reviewer. The captain still performs the authenticated walkthrough below; the smoke command does not pretend to replace it.

Two-minute reviewer walkthrough

1. 0:00–0:15 — Sign in. Note the private Supabase Auth boundary and synthetic-only label.
2. 0:15–0:40 — Import. Open Import synthetic CSV, download/select the reviewed file, then validate and commit it. Refresh board now appears only after that select/validate/commit flow in the same browser session; there is no standalone refresh control. Repeating the reviewed sample is idempotent: existing rows are reported as duplicates, not duplicated. Call out the separate received/accepted/duplicate/unmapped/rejected counts and that validation stores no activity.
3. 0:40–0:55 — Refresh. Choose Refresh board now. The deterministic engine publishes one immutable ranked run and its board refresh timestamp advances. An accepted Claude draft is shown as Validated wording; Deterministic fallback means the complete safe fallback was persisted. Claude drafts only the likely explanation, first question, and suggested teaching move; nightly refresh and unavailable or rejected provider responses use the deterministic fallback.
4. 0:55–1:30 — Use the Evidence Desk. Open the top report. The visible teacher-decision map presents a hypothesis, first question, confident/struggling fork, listen-for, and teaching move. Only the three draftable fields are labeled AI-drafted wording; the fork and listen-for are deterministic teacher support. Expand Show exact contributing evidence for the sole detail. Exact attempt/session results, selected answers, and timing-aware durations remain readable in seconds without exposing internal record IDs, additional causes, or rule-quality internals. Severity determines rank; evidence confidence is shown separately.
5. 1:30–1:45 — Show trust behavior. Point to the teacher-reviewed-draft framing, a visible Working hypothesis when evidence is weak, and the visible “Seen” acknowledgment. Refresh/back navigation keeps the report and seen state.
6. 1:45–2:00 — Show engineering evidence. Run npm run eval:portfolio: eight fixed cases, hard-fail grounding injections, zero model calls, and an explicit no-accuracy-claim posture.

AI-assisted development workflow

The work was shaped spec-first, split into enforceable package boundaries, reviewed in independent agent passes, and checked with deterministic negative dependency tests. AI accelerated exploration, implementation, and review; committed contracts, tests, fixed artifacts, SQL constraints, and human walkthrough evidence remain the acceptance authority.