Rabbithole

AI-powered Socratic tutoring platform at Tradewinds Center for Advanced Learning. Scholars work on projects with Claude (AI tutor) while teachers monitor, analyze, and guide learning through a real-time dashboard.

Features

Scholar workspace — Streaming chat with Claude, voice dictation, image uploads, code artifacts, AI image generation
Dimension system — Personas, units, perspectives, and guided processes overlay the AI's system prompt
Teacher dashboard — Real-time monitoring of all scholars, whisper injection, topic tracking, observations
Observer analysis — Automatic concept mastery tracking, session signals, cross-domain connections

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, Chakra UI 3
Backend	Convex (real-time queries, mutations, actions, HTTP actions)
AI	Anthropic Claude via streaming SSE
Voice	OpenAI Whisper (transcription via Convex action)
Auth	@convex-dev/auth with Password provider

Prerequisites

Node.js 22 (minimum 20 — the Convex CLI and vitest fail on 18). The repo pins 22.16.0 in mise.toml.
pnpm (npm install -g pnpm, or brew install pnpm)
A Convex account (free — Andy will add you to the team)

This repo uses pnpm. Running npm install or yarn will be blocked by a preinstall check.

Recommended: mise. With mise installed (brew install mise), it reads this repo's mise.toml and provisions/activates the pinned Node automatically — including in git worktrees and non-interactive shells. (Any Node 20+ from another manager works too; you just have to manage the version yourself.)

Setup

1. Install dependencies

pnpm install

2. Set up Convex

Contact Andy at andy@tradewinds.school to get added to the Convex team. Once added:

Create a free account at dashboard.convex.dev (if you don't have one)
Run npx convex dev and select the existing rabbithole project — this gives you your own isolated dev deployment
This generates .env.local with your NEXT_PUBLIC_CONVEX_URL

Keep this terminal running — it watches for changes and deploys automatically.

3. Convex environment variables

API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) are configured as project-level defaults, so your dev deployment should have them automatically. Verify with:

npx convex env list

If any are missing, ask Andy.

4. Seed the database

With npx convex dev running in another terminal:

pnpm db:seed

This creates test users, personas, perspectives, units, and processes. It also imports Common Core standards data.

5. Start the dev server

pnpm dev

The app runs at http://localhost:1041.

6. Log in

Use any of the seeded test accounts:

Role	Username	Password
Teacher	`test-teacher-001`	`test-teacher-001`
Scholar	`test-scholar-001`	`test-scholar-001`
Scholar	`test-scholar-002`	`test-scholar-002`
Scholar	`test-scholar-003`	`test-scholar-003`

Or create a new account from the login page.

Project Structure

app/                    # Next.js pages and layouts
  login/                # Username/password login
  scholar/              # Scholar workspace (project view)
  teacher/              # Teacher dashboard
components/             # React components
hooks/                  # Custom React hooks
convex/                 # Convex backend
  schema.ts             # Database schema
  auth.ts               # Auth configuration
  http.ts               # HTTP actions (SSE streaming, analysis)
  projects.ts           # Project CRUD + messaging
  projectHelpers.ts     # System prompt builder
  observer.ts           # AI observer (mastery, signals, seeds)
  seedData.ts           # Database seed data
  lib/                  # Auth helpers, custom function wrappers
scripts/                # Utility scripts
mcp-server/             # MCP server for parent access
public/                 # Static assets (avatars, logos)

Commands

pnpm dev                # Next.js dev server (port 1041)
pnpm build              # Production build
npx convex dev          # Convex dev server (run alongside pnpm dev)
pnpm db:seed            # Seed data (non-destructive)
pnpm db:reset           # Wipe all tables and re-seed

Production Deployment

Prod auto-deploys on merge to master by two mechanisms: Vercel via its own GitHub integration (production on every master push), and Convex via .github/workflows/deploy.yml (only when convex/** changed). The manual commands below are the out-of-band / fallback path (a hotfix, or re-deploy after a failed Action), and are how a widen→migrate→narrow migration is sequenced by hand.

# 1. Deploy Convex backend to prod (no deploy key here — confirm the slug)
npx convex deploy

# 2. Deploy Next.js frontend to Vercel prod (project `makawulu`, scope `tradewinds-school`).
#    This wrapper self-heals the project link + verifies learn.tradewinds.school.
bash scripts/deploy-vercel-prod.sh    # or: pnpm deploy:vercel:prod

Without CONVEX_DEPLOY_KEY, npx convex deploy targets production regardless of CONVEX_DEPLOYMENT. Vercel branch previews instead use a Preview-scoped deploy key through pnpm vercel-build. Read the first line of its output to confirm the deployment slug before proceeding.

The Vercel CLI defaults to the wrong scope — the prod project is makawulu under tradewinds-school. The script above pins --scope tradewinds-school and relinks if .vercel/project.json (gitignored, per-checkout) points elsewhere.