Mockio：面向拉美技术人的 AI 英语面试模拟器

Mockio

An AI interview simulator for Latin American tech professionals practising job interviews in English. A simulated hiring manager from a real company asks one question at a time; afterwards you get a structured evaluation of your English — vocabulary, structure, and the grammar errors that Spanish speakers actually make.

Built from the prompt architecture in gemini-code-1787546966301.md: a live Interviewer (Phase 1) and an async Evaluator (Phase 2).

• Backend — prompts, model routing across four vendors, an HTTP API with accounts, live sessions in Redis, durable progress in Postgres, and SSE streaming.
• Coaching — a second, non-blocking loop that reads each finished exchange and writes notes beside the transcript, so the interviewer never has to break character to help.
• Measurement — words per minute, filler rate, thinking time and vocabulary range, counted from the transcript rather than judged by a model, so they mean the same thing in every session.
• Progress and gamification — four per-axis trends, XP on an append-only log, levels, badges and a weekly league.
• Sectors — fintech, e-commerce, travel, social, developer tools and delivery. The sector sets the vocabulary and the metrics the interviewer demands, not just which companies are listed.
• Interviewer archetypes — five temperaments, each with its own prompt behaviour and its own speaking rate and pitch. A company defaults to the one its culture implies.
• Your context — upload a CV or portfolio and the interviewer opens on something you actually did, then presses where your CV is vague.
• Live transcription — streaming speech-to-text through Deepgram over a WebSocket, with the provider key kept server-side. Falls back to the browser's own recognition when no key is configured.
• Web — landing page, design system, and the product screens, with browser speech in and out.
• Benchmarks — the harnesses that chose the models, so the choice is reproducible rather than asserted.

Renamed from TechShadow 360. Cookie name, Redis key prefixes (rs:), and every environment variable (REALSESSIONS_*) changed with it. Existing Redis data written under the old prefixes is unreachable, and everyone signed in under the old cookie is signed out. Both are intentional and only matter if you had data from before the rename.

Setup

1. Prerequisites

2. Install

git clone https://github.com/jeangueva/real-sessions.git
cd real-sessions
npm install
cd web && npm install && cd ..

3. Configure

cp .env.example .env

Open .env and set, at minimum:

OPENROUTER_API_KEY=sk-or-v1-...

Create the database and point DATABASE_URL at it:

createdb realsessions

The schema is applied on every boot — every statement is IF NOT EXISTS, so there is no migration step to run or forget.

Everything else is optional locally and documented inline in .env.example. Two are worth knowing about:

• REALSESSIONS_SESSION_SECRET — signs identity cookies. Unset in development it is regenerated on every boot, so restarting signs everyone out. Required in production, where the server refuses to start without it:

  node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

• RESEND_API_KEY + EMAIL_FROM — real email. Without them, password-reset and confirmation links are printed to the server log instead of sent, which is fine locally and refused in production.

4. Run

Redis and Postgres come up with compose:

docker compose up -d          # redis + postgres, healthchecked

Three processes. The provider key lives only in the API — the browser never receives it.

docker run -d -p 6379:6379 redis:7-alpine   # terminal 1 — Redis (optional)
npm run serve                               # terminal 2 — API on :8787
cd web && npm run dev                       # terminal 3 — UI on :5173

Open http://localhost:5173 for the landing page and /app for the product. Sign-up is optional: you can practise as a guest, and that history transfers to an account if you create one from the same browser.

The API prints what it is actually using at startup, which is the fastest way to catch a missing variable:

Mockio API on http://localhost:8787 (sessions: redis, progress: postgres, rate limits: redis, email: console)

5. Verify

npm test              # fully stubbed — no network, no model key needed
npm run typecheck
cd web && npm run build

test/routes.test.ts boots the API on an ephemeral port and speaks HTTP to it, with in-memory stores and a stubbed model provider. Calling the handlers with request doubles would have skipped exactly what breaks: cookie round-trips, status codes, SSE frame ordering, the multipart reader, and which side of the authentication gate a route sits on. It found a live bug the first time it ran — GET /api/profile was registered twice, and the CV route shadowed the gamification one, so the Progress screen's level and badges had been reading the wrong shape.

The progress store is the one place where an in-memory implementation and a real database have to agree, so its suite runs against both. The Postgres pass is skipped unless you point it at a database of its own:

createdb realsessions_test
TEST_DATABASE_URL=postgresql://localhost:5432/realsessions_test npm test

TEST_DATABASE_URL, never DATABASE_URL — these tests write real rows, and aiming them at the development database puts test XP on your own leaderboard.

The web suite renders components in happy-dom. Element.prototype.animate is deleted in the setup file, which pushes Framer Motion onto its JavaScript animation path: happy-dom's Web Animations implementation throws when a component unmounts mid-animation, and the noise landed exactly where a real failure would need to be visible.

A green suite means the wiring holds, not that any model does the job well. That is what the benchmarks below are for, and they need a key.

Voice

Two implementations behind one interface (SpeechInput in web/src/lib/voice.ts), chosen at runtime from what the server reports at /api/voice/config:

The browser sends audio over WS /api/voice; the server relays it to Deepgram and relays transcripts back. It is a proxy on purpose. Deepgram can be dialled straight from a browser, but only by shipping the key or a short-lived token to the client, and the premise of this server is that the provider key never leaves it. The hop costs a few milliseconds against the ~300ms the transcription itself takes.

endpointing is set to 700ms rather than Deepgram's 10ms default. It is the one number a candidate actually feels: it decides how long silence lasts before the utterance is declared over, and interviews are full of pauses for thinking.

The gateway closes with a code the client reads — 4001 means "not configured, use browser speech", 4011 means "it broke, tell them". A transcription outage degrades to typing, never to a stuck microphone.

Not verified against a live key. The gateway's auth, refusal and fallback paths are tested and were exercised against the running server; the transcription itself needs a Deepgram account.

The hero video

The app serves its own web/public/hero-2.mp4, transcoded from a 19 MB, 16 Mbit/s master down to 1.9 MB. A background loop sits behind a scrim and is never the thing being read, so the bitrate a master was graded at buys nothing and costs ten times the weight of the rest of the page.

VITE_HERO_VIDEO overrides it — a CDN in production, or an empty string to drop the video and render the CSS light field instead. That field is also what anyone with prefers-reduced-motion gets, and what everyone gets if the file fails to load.

The loop seam is the whole problem: the loop attribute cuts hard from the last frame to the first, and no CSS transition has an event early enough to hang on. So the fade is driven by hand on requestAnimationFrame — fade out over the last 0.55s, reset on ended, fade back in. Each fade cancels the one before it and resumes from the current opacity rather than snapping.

If you replace it, check what it weighs first. Transcoding is a one-liner:

ffmpeg -i master.mp4 -an -c:v libx264 -crf 30 -preset slow \
  -vf scale=1920:-2 -movflags +faststart web/public/hero-2.mp4

-an because it is muted anyway, and +faststart so playback begins before the whole file has arrived. A VP9/webm version was tried and came out larger than the h264 at equivalent quality, so only one file ships.

The business model

Two plans, split along one line: does this need to know who you are?

Free is a real product, not a trial with the ending cut off — the score is honest and the interview runs to the end. What you pay for is the version that knows you, which is why the CV, the company picker and the progress chart all sit on the same side of the line.

XP, levels and badges are free on purpose. A progress system that only rewards subscribers rewards nobody at the moment it would have earned one.

Every gate is enforced in src/entitlements.ts and checked server-side. The UI hides what you cannot use, but hiding a button is a courtesy, not a control.

Two ways that went wrong the first time, both worth knowing because the shape recurs:

• Gating the company name was not enough. industry and companyCulture are legitimately read from the request for a company outside the catalogue, so a free caller could send industry: "Fintech" and get the sector-grounded interview the picker is meant to sell. The free plan now takes a fixed context and reads neither field.
• A capability that is defined but never referenced is not a gate. advancedFeedback existed in the type for a while with zero call sites, and the measured metrics and actionable steps the pricing page sells went to everyone. Both are now stripped on the way out — on /evaluation and on /history/:id, which reads the same record straight back.

Grants live in the entitlements table as rows, not as a column on an account: a person can be granted premium more than once and for different reasons, and the effective plan is the best unexpired grant. A single mutable plan column loses why someone has access and makes an expiry impossible to audit.

Payments

Mercado Pago, not one of the international processors. This product is for Latin American candidates and Mercado Pago is what they already have; a checkout that demands an international credit card excludes exactly the people it is for.

Recurring billing there is a preapproval. The server creates one, sends the payer to Mercado Pago's own hosted checkout, and reconciles when the status changes. Card details never reach this application — the moment a form here collects a card number, this becomes a system that has to be PCI-audited.

Two rules run through src/billing/mercadopago.ts, both about not trusting the wire:

• The webhook body is never believed. A notification says "something happened to id X"; the status is then read back from the provider's API. The body is an unsigned claim about our own billing state, and treating it as truth turns a forged POST into a free subscription. There is exactly one path from a payment to an entitlement — reconcileSubscription — so the webhook and the post-checkout poll cannot disagree.
• The signature is checked first, in constant time, with a freshness window. A missing secret fails closed rather than skipping the check. Without the timestamp window a single captured notification would be replayable forever.

Subscriptions and entitlements are separate tables on purpose. They diverge in the case that matters: someone cancels on the 3rd having paid through the 30th. The subscription is cancelled, the grant runs to the end of the period, and collapsing them would either cut them off early or leave them premium forever.

MERCADOPAGO_AMOUNT and MERCADOPAGO_CURRENCY are required rather than defaulted. Mercado Pago charges in the seller's currency, so "$9" is a different product decision in Buenos Aires than in São Paulo, and the server refuses to build a checkout rather than invent a price.

Not verified against live credentials. The signature verification, the status mapping, the store and the route's refusal paths are tested; creating a real preapproval needs a merchant account.

Early adopters

The landing page collects an email, a target role, and optionally a company, and promises six months of premium. The grant is keyed by email because it is captured before anyone has an account; it is claimed when a confirmation link consumed from that inbox proves the address, because typing it at sign-up proves nothing about owning it. A shared address cannot mint premium twice.

Contributed questions

The interviewer's questions are generated, which makes them plausible rather than real. /#contribute closes that gap from the only source that has the answer: people who sat the interview.

Two promises, both kept in the backend rather than in the copy:

• Anonymous. The stored row carries a salted one-way hash of the identity, kept so one contributor cannot flood a company and so duplicates collapse. It cannot answer "who wrote this".
• Reviewed. Everything lands as pending. Nothing contributed reaches an interview prompt until a human confirms it — otherwise anyone could shape what the product asks by volume, and a rumour would be laundered into an authoritative question.

ContributionStore.verified() is still the only prompt reader. POST /api/review/:id calls decide to mark pending reports verified or rejected, and only an allowlisted account with a verified address can reach it.

Reviewing

REALSESSIONS_REVIEWERS is a comma-separated list of account emails. Unset, the review routes 404 for everyone and nothing is ever verified.

It is an environment variable rather than a role column for two reasons. The reviewers are meant to be a handful of working recruiters, changing rarely — a table and an admin screen would be more machinery than the problem has. And a list that lives outside the database cannot be granted to yourself by anything that reaches the database.

An unverified email address is never a reviewer. The allowlist names an address, so an unconfirmed one is a claim rather than a fact; without that check, registering with a reviewer's address would be enough.

A non-reviewer gets 404 from /api/review, not 403 — whether this deployment has a queue at all is not something to confirm to everyone who asks.

Verified questions reach the Phase 1 prompt fenced and labelled as source material, with an explicit instruction that anything inside them reading like a command is a candidate's recollection and is to be ignored. Human review is the real mitigation for text from strangers landing in a system prompt; that fence is the second line.

Where this goes

1. Now — candidates report questions; they sit in pending.
2. Next — working recruiters and hiring managers verify them per company, and verified questions inform the prompt for that employer.
3. Later — those same interviewers run sessions themselves. Step 3 is a product, not a column, and nothing here presumes it.

Deploying

DEPLOY.md has the full procedure, the required variables and why each one refuses to degrade. render.yaml declares the whole stack, so connecting the repo in Render's dashboard is the shortest path — no CLI, no browser callback with a deadline.

One image serves the API and the built web app:

docker build -t realsessions .
docker run -p 8787:8787 --env-file .env.production realsessions

Two stages, so the web toolchain does not ship. The server runs TypeScript through tsx rather than being compiled — a deliberate trade, since adding a backend build here would mean the thing running in production is not the thing the tests run against.

--include=dev on the install is load-bearing: NODE_ENV=production is already set by then, which makes npm omit devDependencies, and tsx is one. Without it the image has no tsx, npx fetches it on every boot, and the container needs network access at startup to run at all.

Static serving sits in front of the authentication gate. The page a visitor loads is what obtains the identity cookie, so serving it only to callers who already have one is a door locked from the inside. API paths are excluded, so a mistyped /api/… still answers as an API rather than returning HTML.

Production refuses to start without REDIS_URL, DATABASE_URL, REALSESSIONS_SESSION_SECRET, and RESEND_API_KEY + EMAIL_FROM. Each of those failures is silent data loss or a security hole if it degrades instead.

Commands

Troubleshooting

Usage as a library

import { InterviewSession, evaluateInterview } from "./src/index.js";

const context = {
  candidateName: "Mariana",
  targetRole: "Senior Product Designer",
  companyName: "Stripe",
  companyCulture: "Craft, user obsession, high trust",
  industry: "Fintech",
  interviewStage: "Behavioral",
};

const session = new InterviewSession(context);

// Phase 1 — stream each turn straight into TTS.
let turn = await session.startStream((chunk) => speak(chunk));
while (!turn.isComplete) {
  const answer = await transcribeCandidateAudio();
  turn = await session.submitAnswerStream(answer, (chunk) => speak(chunk));
}

// Phase 2 — after `[INTERVIEW_COMPLETE]`, typically on a queue.
const evaluation = await evaluateInterview(context, session.transcript);

License

MIT. Note that this covers the prompt architecture too — the interviewer and evaluator prompts in src/prompts/ are the substance of the product, and MIT lets anyone use them commercially. That is the intent; it is worth knowing it is the intent.

The rest of this file is engineering notes: what was measured, what was chosen, and what is deliberately not done yet.

The two benchmarks

npm run benchmark runs both and ends with one recommendation — the cheapest model that cleared every check for each phase, the combined cost per interview, and the two env vars to set:

npm run benchmark
npx tsx examples/benchmark.ts --interviewers qwen3.5-flash,claude-haiku-4-5 \
                             --evaluators   qwen3.7-plus,claude-sonnet-5

Run the two individually when you want the full transcripts and per-turn verdicts rather than the summary tables.

Both feed a scripted adversarial candidate through the real prompts and check what a unit test cannot: whether a given model actually does the job. Each model needs its vendor key in the environment; a model whose key is missing errors on its own row instead of aborting the run, so a partial comparison still works.

Phase 1 — npm run persona-compare

Seven probes against the interviewer, one rule each:

Mechanical asserts per turn: word count, one question mark, TTS-safe plain prose (no markdown/bullets/emoji), no identity leak. Reports measured tokens, median turn latency, and cost per interview.

Defaults, cheapest first:

qwen3.5-flash → deepseek/deepseek-chat → gemini-3.1-flash-lite → claude-haiku-4-5

npm run persona-compare
npx tsx examples/persona-compare.ts qwen3.5-flash claude-sonnet-5   # pick your own
npm run persona-check                                               # one model, full transcript

persona-check runs a single model and prints every turn with its per-rule verdict — use it to read tone and follow-up depth, which no assert covers.

Phase 2 — npm run evaluator-probe

A fixed transcript with five planted Spanish-L1 interference errors, plus two control phrases that are informal but correct English:

Three things are checked: the JSON validates against EvaluationSchema, the model catches the planted errors, and it does not flag the control phrases. Over-correction matters as much as missed detection — a model that marks correct informal English as broken produces demoralizing feedback for a real user. Bar to pass: 3+ caught, zero false positives.

Defaults, cheapest first, with the current default last as the bar to beat:

qwen3.5-flash → qwen3.7-plus → claude-sonnet-5

npm run evaluator-probe
npx tsx examples/evaluator-probe.ts gemini-3.1-flash-lite deepseek/deepseek-chat

Cost and latency come from real usage reported by each provider, not from an estimate. A single run is a smoke test, not a verdict — rerun a candidate a few times before trusting it with the half of the product users pay for.

Layout

Decisions that differ from the spec doc

• Vendor is inferred from the model id. One ModelProvider interface (chat + json) behind four routes, so switching either phase to another vendor is a model-string change, not a rewrite:

  Model id	Vendor	Key
  claude-*	Anthropic SDK	ANTHROPIC_API_KEY
  gemini-*	@google/genai	GEMINI_API_KEY
  qwen*	DashScope international, OpenAI-compatible	DASHSCOPE_API_KEY
  vendor/model (has a slash)	OpenRouter	OPENROUTER_API_KEY

  Unknown ids throw rather than guessing a vendor. OpenAICompatibleProvider covers the last two and anything else speaking the OpenAI wire format (DeepSeek, Groq, Together, a local runtime) — only baseURL changes.

• Reasoning is turned off per vendor dialect. Qwen spends the entire max_tokens budget thinking and returns empty content with finish_reason: "length" — a 30-word interviewer turn does not need it. OpenRouter only honors reasoning: { enabled: false } (enable_thinking is silently ignored there); DashScope-direct uses enable_thinking: false. Endpoints that refuse to disable reasoning (Gemini via OpenRouter returns 400 Reasoning is mandatory) are retried once without the flag.

• Server-side fallback routing. fallbackModels on either call site emits OpenRouter's models: [primary, ...fallbacks], and ChatResponse.servedBy reports which one ran. Note OpenRouter validates the primary id up front, so an unknown model is a hard 400, not a failover — fallbacks cover saturation and provider errors on a valid model. Providers without server-side routing ignore the field.

• Defaults come from a live benchmark, not a price table. The doc names claude-3-5-sonnet-latest for both phases. Both now default to qwen/qwen3.7-flash via OpenRouter, measured 2026-08-30:

  Phase	Result	Cost
  Interviewer	0 rule failures, 1056ms median turn — fastest of the three models that passed	$0.0002
  Evaluator	5/5 planted Spanish-L1 errors caught, 0 false positives — beat qwen3.7-plus (4/5) at an eighth of the cost	$0.00013

  $0.00033 per interview end to end ($0.33 per 1000), against ~$25 per 1000 for the Claude Haiku + Sonnet 5 pair this started on. Reproduce with npm run benchmark. Override with REALSESSIONS_INTERVIEWER_MODEL / REALSESSIONS_EVALUATOR_MODEL, REALSESSIONS_MODEL for both, or per call site.

  Caveat worth keeping in view: deepseek/deepseek-v4-flash also passed every Phase 1 rule but at a 6026ms median turn, which is disqualifying for voice. Latency, not just cost, decided this.

• effort is omitted where unsupported. Haiku 4.5 and Sonnet 4.5 reject output_config.effort with a 400, so supportsEffort() gates the field instead of sending a default that breaks the cheap path.

• JSON is enforced, not requested. Phase 2 uses the API's structured-output format built from EvaluationSchema instead of the doc's "output raw JSON, no backticks" instruction, so a stray markdown fence can't corrupt a row. The response is re-validated locally, which also gives you a validator for data read back out of Supabase.

• The completion flag never reaches TTS. [INTERVIEW_COMPLETE] is stripped from both buffered and streamed output — including when a chunk boundary splits the flag mid-token.

• Turn cap is enforced in code. The prompt asks for 5–7 turns; on the final allowed turn the session appends an operator note instructing the model to close, rather than trusting it to count.

• Voice output rule added. The prompt now forbids markdown, bullets, and emoji, since every response is read aloud.

• Refusals are typed. stop_reason: "refusal" raises InterviewRefusalError / EvaluationParseError instead of surfacing as an empty response.

The HTTP boundary

src/server.ts exists for one reason: the provider key must never reach the browser. Anything in a client bundle is public, so InterviewSession and evaluateInterview run server-side and the web app talks to three endpoints:

Streaming

Send Accept: text/event-stream to either interview route and the turn arrives token by token. EventSource is not usable on the client — it only issues GET requests and cannot carry the interview payload — so this is SSE framing over POST, read with fetch and a stream reader.

event: session   data: {"sessionId":"…"}     ← first, so a mid-stream failure is recoverable
event: delta     data: {"text":"Hi"}         ← repeated
event: turn      data: {"turn":{…}}          ← final, authoritative
event: error     data: {"error":"…"}         ← failure after headers were sent

Measured on a live turn: first token at ~900ms, full turn at ~1274ms. The UI shows text as it generates rather than after, and the typewriter effect on the live screen is now the model actually generating instead of a timed animation.

Two details that are easy to get wrong and are handled:

• [INTERVIEW_COMPLETE] never reaches a delta, including when a chunk boundary splits the flag mid-token. Verified against a live stream.
• Errors after headers are sent cannot become a JSON status response, so they are emitted as an error event on the open stream instead.

The non-streaming JSON responses still work unchanged — the header decides.

Voice

web/src/lib/voice.ts wraps the browser's SpeechRecognition and speechSynthesis behind SpeechInput / SpeechOutput interfaces, so a cloud provider replaces either half without the interview screen changing.

Three things this had to get right:

• The microphone closes while the interviewer speaks. Otherwise the browser transcribes the synthesised voice and feeds the interview its own words back.
• Speech is queued by sentence, not by token. Speaking each streamed token stutters; waiting for the whole turn discards the latency the streaming work bought. takeSpeakablePhrases splits on sentence boundaries and holds a partial sentence back — including not splitting on a decimal point.
• Typing stays a first-class path. Firefox has no speech recognition, and the voice toggle only appears when both halves actually exist.

Verified in Chrome against the running app. Two bugs only a real browser found:

• Chrome refuses to speak until the page has had a trusted user gesture (SpeechSynthesisUtterance fails with not-allowed). The opening turn streams in before the candidate has touched anything, so it can never be spoken automatically. Turning voice on is now the gesture, and it speaks the turn already on screen; a refusal surfaces a "Play this turn" button instead of silence with no explanation.
• The microphone guard flickered open between phrases. speechSynthesis.speaking briefly reads false between queued utterances, which re-enabled the mic mid-turn — the exact echo case the guard exists to prevent. Speaking state now tracks an explicit queue depth. Measured after the fix: 43 samples while speaking, mic disabled in all 43.

Measured on a live turn with voice on: first text on screen at 251ms, first speech at 1005ms.

Speech recognition is covered by driving createSpeechInput through a fake SpeechRecognition (17 tests in web/test/), which exercises the parts that only run while someone is talking: interim-versus-final accumulation, error mapping, stop semantics, and transcript reset between turns. That found a real bug — Chrome re-sends the full results list on every event, and appending each final phrase blindly duplicated text once an answer ran long. Final phrases are now keyed by result index, so a re-delivered phrase overwrites instead of appending.

The fix was then re-verified in Chrome by installing a driveable SpeechRecognition on the page before the interview screen mounted, which exercises the real React path — recognition event, live transcript, release the mic, answer submitted — without speaking. Re-delivering an already-final phrase produced "I led the onboarding redesign. We cut drop-off by half." with no duplication, the answer was sent, and the interview advanced to turn 2.

Still unverified: actual audio. Whether Chrome transcribes real speech accurately, and how it behaves with accented English — which is precisely this product's audience — needs a person and a microphone.

Verified end to end against live models: a full seven-turn interview followed by an evaluation that caught every planted L1 error.

Accounts

Email and password, chosen because it is the only method testable here — magic links need an email provider and OAuth needs registered credentials, neither of which this deployment has. AccountStore is narrow enough that either can be added beside it rather than replacing it.

• Passwords are hashed with scrypt at the OWASP-recommended cost (N=2^15, r=8), salted per password, with the cost parameters stored alongside each hash so they can be raised later without invalidating anyone. Verified in constant time.
• Requirements favour length over composition — 12 characters minimum, no symbol theatre. A passphrase resists guessing better than Pa$$w0rd!.
• Failed sign-in returns one message for "no such account" and "wrong password", so the endpoint cannot be used to enumerate registered addresses.
• Sign-in is rate limited on two axes: per IP (20 / 15 min) and per email (8 / 15 min). Per-IP alone lets a botnet spread guesses across addresses; per-email alone lets an attacker lock someone out by failing their login.
• Guest practice carries over. Signing up from a browser that has already practised moves that history onto the account — otherwise creating an account discards the very thing that motivated it.
• Account tokens last 30 days, against 12 hours for a guest. History hangs off the account, and a half-day window would lose it weekly.

Password reset

POST /api/auth/forgot → emailed link → POST /api/auth/reset.

• Reset tokens are 256 bits of randomness, stored hashed (SHA-256, not scrypt — there is no dictionary to slow down against that much entropy). A store dump yields nothing usable.
• Single use. Redis GETDEL makes read-and-delete atomic, so two requests racing on the same link cannot both win.
• Thirty-minute expiry.
• The request endpoint answers identically whether or not the address is registered — unlike sign-up, staying quiet here costs nothing in usability. Limited per email as well as per IP, so it cannot be used to flood an inbox.
• The password is validated before the token is consumed, so typing a short one does not burn the only link and force another request.
• Resetting signs out every other session. Tokens are stateless, so each account carries a passwordChangedAt and any token issued before it is refused. Without this, resetting after a compromise would leave the attacker signed in — which is the whole reason someone resets.

Email verification

A confirmation link goes out on sign-up (POST /api/auth/verify, POST /api/auth/verify/resend). It shares the reset flow's token machinery — 256-bit token, stored hashed, single use — with a 24-hour expiry, because a stale confirmation link only proves an address whereas a stale reset link would change a password.

• Purposes are namespaced. A confirmation token is rejected by the reset endpoint and vice versa; without that, a link mailed to confirm an address would also let its holder set a password.
• Confirming does not sign anyone in. A link opened from an inbox proves the address, not that the person clicking it is at their own device.
• Resend answers identically whether or not a mail went out, so a stolen cookie learns nothing about the account's state.
• Verifying twice does not move the timestamp — it records when the address was first proven, not the last click.

Unverified accounts can still practise. Blocking the product on a click in an inbox costs more than it protects here; what an unverified address really costs the user is password recovery, so Settings says exactly that. Verification is checked in exactly two places: claiming an early-access grant and reaching the review queue. Billing and outgoing mail do not require it.

Verified end to end: mail sent on sign-up, emailVerified false then true, the confirmation token rejected by the reset endpoint, the link failing on reuse, resend refused without a session and silent for an already-verified account.

Email delivery

ResendEmailSender posts to https://api.resend.com/emails. Resend was chosen for the simplest surface of the common providers — one POST with a bearer token; SES, Postmark, or Mailgun are another class implementing EmailSender and nothing else changes.

Set RESEND_API_KEY and EMAIL_FROM (an address on a domain verified with the provider, or every send is rejected). With neither, the console sender logs links instead of sending them, and production start is refused — a reset link in a log file is a reset link for anyone with log access. With only one of the two set, it warns loudly: half-configured is a likelier deployment mistake than deliberately running without email.

• Ten-second timeout. A hanging provider must not hang a sign-up.
• One retry on 429 or 5xx, none on a rejected request — retrying something the provider will never accept only doubles the delay.
• The API key never appears in a thrown error or a log line. The recipient does, because operators need to answer "did that reset mail go out".
• A delivery failure never reaches the response. It is logged and swallowed. Letting it propagate would 500 a sign-up that already created the account — and on the forgot-password route it would make a real address fail while an unknown one succeeded, rebuilding the enumeration oracle those identical responses exist to prevent.

Verified against a local mock provider: the exact request shape (to is an array — a bare string is silently rejected), retry on 429, no retry on 422, the key absent from errors, and a refused connection failing rather than hanging. Verified against a live server with a deliberately bad key: sign-up still returns 201, both forgot-password paths still return an identical 202, the failure is logged, and the key is not in the log.

Not verified: actual delivery. That needs a real key and a verified sending domain.

Full flow, driven in Chrome

Sign up → confirmation link → practise → history → sign out → forgot password → reset link → new password, all through the UI against live models and Redis. Everything held: history followed the account, the confirmation and reset links each worked once, the old password stopped working, and the reset landed the user signed in.

Dates are pinned to en-US through one helper rather than following the browser locale: a Spanish-locale browser rendered "31 ago" next to English copy, which reads as "31 ago" rather than "31 August".

That run surfaced an accessibility bug worth naming. Chrome reported prefers-reduced-motion: reduce, and the CSS rule in index.css covers only CSS animations — every Framer Motion entrance still ran, and because those entrances are what fade content in, four panels of a feedback report sat at opacity 0 permanently. The design system README had claimed reduced motion was honored globally; it was not. Motion components now drop out entirely under that setting rather than animating to a visible state, since an animation needs a frame to commit and a throttled tab may never provide one.

Verified end to end: identical responses for known and unknown addresses, the token stored only as a hash, a short password rejected without burning the link, successful reset, the same link failing on reuse, the old password rejected, and every prior session refused afterwards.

Known leak, stated rather than hidden: sign-up reveals whether an address is already registered (409). Avoiding that means always returning success and emailing the existing owner instead, which needs an email provider. Silently failing a sign-up is worse than the leak, so it stands until email exists.

Verified end to end: guest practises, signs up, history carries over; signing in from a clean browser finds that history; wrong password and unknown account return identical responses; sign-out clears the cookie; the stored record holds scrypt$32768$8$1$… and never the password.

Identity and limits

POST /api/auth issues an HMAC-SHA256 signed, 12-hour identity in an httpOnly, SameSite=Lax cookie. Every other route requires it, and every interview is owned by the identity that created it — presenting someone else's session id returns 404, not 403, so the response does not confirm the id exists.

This is not a user-account system: there is no user store, so what it provides is an attributable caller, which is what rate limiting and ownership need. Set REALSESSIONS_ACCESS_CODE to gate who can obtain an identity at all (compared in constant time), and REALSESSIONS_SESSION_SECRET to sign tokens — the server refuses to start in production without one, and warns loudly in development.

Limits are tuned by cost, per identity, per hour:

A tripped limit returns 429 with Retry-After. Counters live in Redis under rs:rl:*, so N instances enforce one shared limit rather than N times it. Increment and expiry run as a single Lua script: as two commands, a process dying between them leaves a key with no TTL, and that caller is rate-limited forever with nothing to explain why.

If Redis is unreachable the limiter fails open and logs it. Failing closed would lock every user out of an otherwise working product; failing open risks cost. Open is the lesser harm, and it is loud rather than silent.

Verified live: unauthenticated requests 401, forged cookies 401, a second identity reading another's session 404s, and — across two instances sharing one Redis — the thirteenth start in an hour 429s regardless of which instance serves it.

Session durability

Interviews live in Redis, keyed rs:session:<uuid> with a rolling one-hour TTL that refreshes on every answer — an active interview is never expired out from under someone still typing.

InterviewSession is serialized to a plain SessionSnapshot and rehydrated per request, so any instance can pick up any interview. The system prompt is deliberately not stored: it is rebuilt from the context, so a prompt fix reaches conversations already in flight instead of only new ones. The snapshot is written back only after a turn succeeds, leaving a failed call retryable from exactly where it was.

In production a missing or unreachable REDIS_URL is fatal. Degrading quietly to memory would lose interviews under load with nothing in the logs to say why.

Verified: an interview mid-conversation survived killing and restarting the API process, and an interview started on one instance continued correctly on a second one sharing the same Redis.

History and preferences

Completed interviews are recorded when their evaluation succeeds, not when the last turn is spoken — an interview with no evaluation has nothing to show. Records live under rs:history:<identity> as a capped list (50 per identity, 90-day TTL); preferences under rs:prefs:<identity>.

The list endpoint strips the evaluation body, so the history page does not get heavier the longer someone practises; the detail endpoint returns it. Both are scoped to the identity, and another caller's id reads as 404 rather than 403.

PUT /api/preferences clamps rather than rejects — interview length is bounded to the 5–7 turns the prompt is written for, free text is capped — and echoes what it stored, so the form shows any clamping instead of silently disagreeing.

Verified end to end: an interview, its evaluation, the record appearing in history with the evaluation retrievable, and a second identity seeing neither.

History follows the account once someone signs up, and guests keep the browser-scoped behaviour described above.

Still not production-ready

• Verification is enforced in two places. An early-access grant is claimed only after a confirmation link is consumed, and the review routes require an allowlisted account with a verified address. Other routes do not require verification.
• Voice uses Deepgram when DEEPGRAM_API_KEY is configured, otherwise the browser's speech APIs. In the browser fallback, Chrome sends microphone audio to Google, and Firefox cannot do speech recognition at all.

Known gaps in the spec (not implemented here)

• Native voice-to-voice. None of the wired models do native audio, so voice runs as a pipeline around the text interview: speech-to-text in (Deepgram over the server WebSocket when DEEPGRAM_API_KEY is set, browser recognition otherwise) and text-to-speech out (Deepgram Aura, with browser synthesis as the fallback). The alternative is gemini-3.1-flash-live-preview ($0.005/min audio in, $0.018/min out), which removes the STT and TTS vendors entirely but does not fit the request/response chat() interface — bidirectional audio needs its own session adapter.
• Prompt-injection surface. The candidate's transcribed speech is untrusted input. "No breaking character" is a prompt-level instruction, not a guarantee.
• Scoring calibration. overall_score_percentage is a model judgement with no rubric anchors; scores are not comparable across sessions until you add anchored examples or a fixed rubric.

Adding a vendor

Implement ModelProvider (src/providers/types.ts) — two methods, chat() and json() — then add the id prefix to vendorFor(). Nothing else in the codebase touches a vendor SDK. GeminiProvider is the reference for a non-Anthropic implementation: it maps the assistant role to Gemini's model, counts thoughtsTokenCount as output (or the cost report understates spend), and parses defensively because a truncated response still arrives as invalid JSON even with a server-side schema.

Notes on the installed SDK

@anthropic-ai/sdk@0.71.x is what this is written against. It predates adaptive thinking, server-side refusal fallbacks, and mid-conversation system messages, so none of those are used: effort is set through output_config on the beta messages endpoint (evaluator only), and the wrap-up nudge rides on the user turn. Structured outputs come from betaZodOutputFormat, which requires zod v4.