An AI-powered 1:1 math tutor that replicates the experience of learning with the world's best human teacher.
Most educational software is either passive (videos, worksheets) or impersonal (chatbots). Great tutoring is expensive and inaccessible. FreakingGenius bridges this gap by delivering personalised, conversational math instruction through a two-device model:
| Device | Role | Analogy |
|---|---|---|
| Tablet (Edge) | Silent, passive — like paper. Students write naturally. | The desk |
| Phone / Laptop (Tutor) | Watches strokes, listens, speaks feedback. | The teacher sitting next to you |
This separation mirrors real tutoring: the tutor sits beside you, watches your work, and talks to you — the paper doesn't distract with buttons or notifications.
Student writes on tablet
│
▼
Edge streams strokes (200 ms batches) ──► Bridge protocol ──► Tutor device
│
┌──────────────────────────┘
▼
Vision pipeline
(stroke → math AST)
│
▼
Behavior engine
(decide: praise / question / hint)
│
┌──────────┴──────────┐
▼ ▼
Voice pipeline Bridge → Edge
(speak to student) (annotate their work)
Target end-to-end latency: < 800 ms from the moment the student lifts their pen to the moment the tutor starts speaking.
| Layer | Package | What it does |
|---|---|---|
| Shared types | @fg/shared |
Canonical types for strokes, visual primitives, bridge protocol, and sessions |
| Voice pipeline | @fg/tutor/voice |
Microphone → VAD → STT → response generation → TTS → speaker |
| Vision pipeline | @fg/tutor/vision |
Stroke grouping → symbol recognition → math parsing → work analysis |
| Behavior engine | @fg/tutor/behavior |
FSM, intervention scheduling, hint escalation, persona management |
| Session manager | @fg/tutor/session |
Lifecycle orchestration, wall-clock tracking, durable checkpoints |
| Tutor bridge | @fg/tutor/bridge |
WebSocket client — sends render commands, receives strokes |
| Edge capture | @fg/edge/capture |
Pointer events → typed Stroke objects |
| Edge render | @fg/edge/render |
Canvas painting — exercises, live ink, committed strokes |
| Edge annotations | @fg/edge/annotation |
Tutor overlay — highlights, correction marks, drawings |
| Edge state | @fg/edge/state |
Observable device state store |
| Edge bridge | @fg/edge/bridge |
Protocol decoding, primitive rendering, capability reporting |
Detailed design specs are available for every major subsystem:
| Spec | Description |
|---|---|
| Architecture Overview | System topology, component boundaries, interaction flows, and key design decisions |
| Bridge Protocol | WebSocket wire protocol, semantic commands, capability negotiation, reconnection |
| Edge Contract | Device contract — what any Edge implementation must do (capture, render, report) |
| Stroke Format | Point format, normalised coordinates, binary wire encoding, batching strategy |
| Visual Primitives | Device-agnostic drawing commands — content, input zones, annotations, feedback |
| Vision API | Stroke → symbol → expression → work analysis pipeline and error detection |
| Tutor Behavior | State machine, Socratic pedagogy, intervention triggers, escalation policy |
| Voice Integration | STT/TTS pipeline, VAD, turn-taking, interruption handling, latency targets |
| Architecture Diagram | Visual system topology (SVG) |
| Phase | Status | Scope |
|---|---|---|
| Phase 1 | ✅ Complete | Monorepo scaffold, shared types, all module stubs with full JSDoc |
| Phase 2 | 🔜 Next | Bridge protocol, Vision API, Behavior engine — first working implementations |
| Phase 3 | 📋 Planned | Cloud services — Brain (AI model serving), Curriculum (exercise bank), DataPlane, ControlPlane |
| Phase 4 | 📋 Planned | Session flow, device pairing, parent dashboard |
