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
