Speakeasy — Engineering Overview
Deep dive into design, architecture, workflows, and core engineering decisions.
System Overview
Speakeasy is a speech and essay practice studio for competitive exams and open practice — generative topics, timed sessions, transcription, evidence-based scoring, and a local growth profile. Alongside practice sits a government-style board interview driven by a Detailed Application Form (DAF).
The system is intentionally client-heavy: topic generation, capture, and default STT run in the browser. Thin Next.js serverless APIs handle evaluation and board orchestration on the same origin so the live product (spkeasy.in) works on any PC without a developer laptop process.
This page is the engineering breakdown — requirements-shaped thinking, high-level design, data placement, critical flows, and the trade-offs behind v0.
Features
Combinatorial banks across modes, fields, and difficulty — not a short static list. Device fingerprints avoid repeats.
Tech Stack : What & Why
Every choice below is tied to performance, privacy, deployability, or scoring integrity — not novelty for its own sake.
Application framework
Next.js (App Router) + React
- Single deployable surface for UI and APIs — ideal for a portfolio product on Vercel.
- Server routes keep evaluator keys off the client while pages stay fast and cacheable.
Language
TypeScript
- Shared types across UI, API payloads, and board session shapes reduce interface drift.
- Makes rubric and DAF contracts explicit for contributors.
Styling & motion
Tailwind CSS + Framer Motion
- Utility-first UI with a small token set (void / panel / accent) keeps the product coherent.
- Motion is used for stage transitions, not decoration noise.
Speech-to-text
Browser Whisper (@huggingface/transformers) + Web Speech API
- Default path is private and free — models download once in the user’s browser.
- Captions cover flaky recognition; cloud Whisper remains optional.
Evaluation
EVALUATOR_URL → Ollama → local-strict grader
- Remote examiner when you host one; Ollama for local research; local heuristics as reliability floor.
- Protects scoring integrity when models are down or answers lack evidence.
Board orchestration
BoardMemory + answer analyze → persona thread + optional FastAPI
- Each turn understands the last answer, updates shared memory, and routes follow-ups to the owning panelist.
- Brain order: free hosted EVALUATOR_* (e.g. Groq) → Ollama speakeasy-board → banks. FastAPI optional for local tools/eval.
Proctoring
MediaPipe Tasks Vision
- Client-side face / presence cues for discipline debrief without shipping video to a server by default.
- Keeps practice numeric scores honest to content, not camera heuristics.
Deployment
Vercel + custom domain (spkeasy.in)
- CDN-backed Next hosting matches the App Router model.
- DNS points apex and www at Vercel; secrets stay in project env vars.
Core Modules
Speakeasy is a modular monolith on Next.js — clear domain boundaries without eight deployable microservices (unnecessary for v0 scale).
PracticeApp
Session state machine for filters, topic spin, timers, capture, and review.
Topic engine
Combinatorial generation, exam catalog, fingerprints, deep-research templates.
Evaluation service
POST /api/evaluate — rubric selection, model waterfall, local-strict fallback.
BoardInterview
DAF intake → live panel → silence handoff → debrief UI.
boardAgent
Personas, follow-up heuristics, question generation, in-memory session store.
Profile / storage
localStorage for guests; Supabase Postgres when signed in (evals, history, streak, settings, DAF).
Proctor overlay
Face / tab / fullscreen violations feeding the discipline report.
Optional FastAPI
Persistent board sessions, current-affairs tools, eval harness — local only.
High-Level Design (HLD)
Interactive-style architecture map: clients → same-origin Next APIs → data stores and optional external / local services.
System Flows
Critical request paths — same style as architecture deep-dives: one diagram per flow.
Practice session flow
Board interview flow
Data Design
v0 stores learner state on the device. Server state for board is ephemeral on the Next path; optional FastAPI persists when used locally.
| Entity | Where | Notes |
|---|---|---|
| Topic / SeenTopic | localStorage (+ cloud) | Fingerprints; synced in user_state when signed in |
| PracticeAttempt / History | localStorage (+ cloud) | Guest local; practice_history when signed in |
| Evaluation / StoredEval | localStorage (+ cloud) | Guest local; evaluations table when signed in |
| CandidateProfile (DAF) | localStorage (+ cloud) | Guest local; user_state.daf when signed in |
| BoardSession / Turns | Next memory Map | UUID session; client may resend turns |
| BoardSession (optional) | FastAPI SQL | Durable when NEXT_PUBLIC_BACKEND_URL is set |
| Violations | Client → debrief | Advisory proctor / conduct events |
Deep Dives
Why client-side topic generation?
Topic spin should feel instant and cost nothing at scale for a practice studio. Combinatorial banks plus on-device fingerprints meet that bar without a topic microservice.
Why a scoring waterfall?
Remote models improve coaching quality when available, but competitive-exam feedback cannot go blank when APIs fail. local-strict is the always-on floor; LLM scores are capped when evidence is thin.
Why same-origin /api/board?
A board that requires uvicorn on the user’s laptop cannot be a public demo. Next routes keep production self-contained. Session Map volatility is an accepted v0 trade-off mitigated by resending profile and turns.
Why optional accounts?
Guest practice stays on-device for a short privacy story and zero-friction demos. Supabase Auth unlocks owned sync of evaluations, history, streak, and DAF across browsers — login is never required to practice or score.
Future Enhancements
- Done: optional Supabase Auth + per-user ownership of evaluations / history / DAF
- Durable board session store (Redis or SQL) for serverless multi-instance
- Rate limits and spend caps on evaluate / transcribe when paid keys are set
- Async queues for heavy STT on low-end devices
- Account delete + export for profile archives (retention policy)
- Numeric board scoring aligned with practice rubrics + longitudinal trends