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.

Speakeasy high-level architecture diagram

System Flows

Critical request paths — same style as architecture deep-dives: one diagram per flow.

Practice session flow

Practice session flow diagram

Board interview flow

Board interview flow diagram

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.

EntityWhereNotes
Topic / SeenTopiclocalStorage (+ cloud)Fingerprints; synced in user_state when signed in
PracticeAttempt / HistorylocalStorage (+ cloud)Guest local; practice_history when signed in
Evaluation / StoredEvallocalStorage (+ cloud)Guest local; evaluations table when signed in
CandidateProfile (DAF)localStorage (+ cloud)Guest local; user_state.daf when signed in
BoardSession / TurnsNext memory MapUUID session; client may resend turns
BoardSession (optional)FastAPI SQLDurable when NEXT_PUBLIC_BACKEND_URL is set
ViolationsClient → debriefAdvisory 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