Poken

Learn by teaching. You explain a topic out loud; an AI student listens, watches your camera, whiteboard or screen, asks questions — and is deliberately wrong about 30% of the time so you have to catch it. You pick your student's persona — eager, skeptic, or confused.

Built on Gemini Live (native audio), Hono + ws, and a single vanilla-JS page. Hosted on Google Cloud Run. Handoff notes — architecture, the session-handover design, and known pitfalls — are in NOTES.md.

Run it

npm install
cp .env.example .env   # add GEMINI_API_KEY
npm run dev            # http://localhost:8000

npm run typecheck runs strict TypeScript over the server.

Deploy

Cloud Run, via Cloud Build:

gcloud builds submit --config cloudbuild.yaml --project poken-app-260919

Production: https://poken.live (also www.poken.live; the Cloud Run URL https://poken-7skula3n3a-uc.a.run.app still serves the same service). GCP project poken-app-260919. Needs the Secret Manager secret gemini-api-key in the project. cloudbuild.yaml sets the 60-minute request timeout, session affinity (required for WebSockets), and SESSION_TIMEOUT_S to match the timeout.

Built with Devin

Part of this codebase is implemented by Devin, Cognition's AI software engineer, working from specs the team writes as GitHub issues. Each task runs in its own draft PR: the kickoff /devin command, Devin's commits, its own verification summary, and the team's review are all on the PR.

Task	Issue	PR	Devin session
Traditional → Simplified Chinese conversion in transcripts	#1	#4 (merged)	cd128bce
Teacher transcription via ElevenLabs Scribe v2 Realtime	#2	#5 (merged)	4c4040ee
Dead-code removal (Firebase remnants, unused CDN script, unused route, dead state)	#7	#8 (merged)	f8431d3f
Coaching tips for typed teacher messages	#9	#13 (merged; cooldown fix added in review)	03a071b6
Demo hardening: pinned jsPDF, persona/language recap, protected /api/logs	#10	#14 (merged)

Layout

main.ts              process entry — listens on $PORT
api/server.ts        HTTP (Hono) + WebSocket + Gemini Live + prompts
server/              materials extraction, vision and video analysis
public/              index.html, app.js, logo.svg — served by the same process
Dockerfile           node:20-slim, tsx runtime (no build step)
cloudbuild.yaml      build → push → gcloud run deploy poken