Developer guide
The project README: features, models and architecture, then how to set up, run and deploy your own copy.
On this page
A free, open-source AI coach for the new 2026 TOEFL iBT, built with Meta's Muse models.
Try the live app · Read the docs · User guide · VR Study Room · How it works · Why I built it
A learner writes a study plan, and AI builds a personal set of practice questions for all 12 task types of the TOEFL iBT that started in January 2026. The set comes with pictures, listening audio in the accents the learner chose, a vocabulary list and a week-by-week schedule. The learner gets instant AI scores for writing and speaking, can take a full timed mock test, and earns a certificate that anyone can verify online with a band of 4.0 or higher.
On a Meta Quest, the learner can also practise in the VR Study Room: a hands-first virtual classroom with 9 of the TOEFL tasks, the learner's own questions and the same scoring, signed in with a code instead of a password. Anyone can try it first with Try the demo, no account.
#Why it exists
I live in Dili, Timor-Leste, and I'm preparing for my first TOEFL so I can study in the United States. The prep books I ordered from Indonesia cost $50, took two weeks to arrive, and covered the old test. Official practice tests cost $49 each, and the free materials give no feedback on writing or speaking. As a data and AI engineer, I built the coach I couldn't find, free to start and open to everyone.
Read the full story: Why I built LafaekTOEFL (on GitHub).
#Why VR
Preparing for the TOEFL alone is hard to keep up. A book or a laptop looks the same every day, a phone is one notification away, and speaking practice means talking to an empty screen. Many learners drop the routine because it gets boring, not because the material is too hard. The VR Study Room on Meta Quest turns the same practice into a place you go to and something you do with your hands:
- A place to study, not another tab. You sit at your own desk in a bright classroom inspired by Timor-Leste, with Dili outside the windows, and only the next question in front of you.
- Learn by doing. In Build a Sentence you pick up word tiles and put them in order, so grammar becomes a puzzle for your hands. Answers are cards you point at and pinch.
- Speak to someone, not to a laptop. Lafaek, a 3D crocodile interviewer, sits across the desk and asks each question out loud with its mouth moving, which feels much closer to the real Take an Interview task.
- Hear who is talking. In Listening, 3D people stand or sit to your left and right. Each voice comes from where that person is (spatial audio), their mouth and hands move while they speak, and each question brings different people from a cast of ten.
- Short, seated sessions. Everything works from a chair, within arm's reach, with hands only. One activity takes a few minutes, and the room continues where you stopped.
- A reason to come back. The hub counts your study days. Turn around, and a live progress wall behind you shows your questions answered, accuracy, study days, progress in each skill, mock-test band and certificate, updated every time you return to the hub.
- The same coach. The room uses your own study-plan questions and the same AI scoring, and everything counts in your progress on the website.
Read more in the VR Study Room guide (on GitHub).
#What it does
| Feature | Details |
|---|---|
| AI study plan | Level, target band (1–6), test date, study days, minutes per day and accents become a dated, day-by-day plan. Muse Spark personalises each week. |
| All 12 TOEFL 2026 task types | Complete the Words, Read in Daily Life, Academic Passage, four listening tasks, Build a Sentence, Write an Email, Academic Discussion, Listen and Repeat, Take an Interview |
| Personal questions | About 133 questions per plan, written by Muse Spark in the real 2026 formats and checked before a learner sees them. The full plan is ready in 10–15 minutes. |
| AI scores and coaching | Emails, discussion posts and interview answers get a band (1–6) with feedback, based on ETS's 2026 scoring criteria |
| Real accents | American, British, Australian, Indian and African English voices, matched to each speaker's gender |
| Vocabulary | Words chosen from the learner's own questions, with IPA, meaning, example and pronunciation |
| Full mock test | All 12 task types, timed by section, with no pause or replay. Every section gets a band and a CEFR level. |
| VR Study Room (Meta Quest) | 4 zones with 9 TOEFL tasks in a seated virtual classroom inspired by Timor-Leste. Hands only: point and pinch, grab word tiles, touch nearby buttons. A cast of ten 3D speakers and a 3D crocodile interviewer that move their mouths and hands as they talk. Continues where you stopped. Same questions, scoring and progress as the website. |
| Try the VR demo without an account | One tap signs a visitor in as a temporary guest with sample questions, real scoring and their own progress. Limited spoken answers and AI scores; leaving the VR area signs the guest out; guests are deleted after 48 hours. |
| Sign in on Quest with a code | No password on the headset: a signed-in phone or laptop shows a code, the Quest enters it, and the phone approves. An account can be signed in on up to 3 devices, listed in Settings. |
| Verifiable certificates | An overall band of 4.0 or higher (B2) earns a certificate with an ID and QR code, checked on a public page |
| Free to start | Starter is free for life (1 plan, 1 mock test). A Boost Pack costs $5 (+1 plan, +2 mock tests). The project is MIT open source. |
| Cheap to run | One complete study plan costs about $3.16 in AI calls, measured on the live app. See Cost per study plan. |
See every screen in the user guide (on GitHub).
#Built with Meta's models
| Provider | Model | Used for |
|---|---|---|
| Meta | muse-spark-1.3 |
Main text model: questions, vocabulary, study schedules, AI scores and coaching |
| Meta | muse-spark-1.2 |
Fallback, used automatically when 1.3 is unavailable |
| Meta | muse-image-1.0 |
Pictures for practice questions |
| Meta | muse-voice-transcribe-1.0 |
Speech-to-text for spoken answers |
| ElevenLabs | eleven_multilingual_v2 |
Listening audio and word pronunciation (Meta has no text-to-speech model) |
#Architecture
- Web app on Vercel: Next.js 15, React 19 and TypeScript. It serves all pages and API routes, and scores practice answers instantly.
- Background worker on Render (Singapore, 0.5 CPU / 512 MB): handles the long AI work. It writes questions, makes pictures and audio, chooses vocabulary, plans schedules and rates mock tests.
- PostgreSQL on Render: all data, plus the job queue and rate limits. The web app and the worker never call each other; they share work through the queue.
- AWS S3: a private bucket for media. The browser only gets 5-minute signed links.
- VR Study Room on Vercel: a static IWSDK build at
/vr/room, served next to the web app. It runs in the Meta Quest Browser (WebXR) and calls the same API routes with the same session cookie.
Seven diagrams explain each flow step by step, including the VR room and signing in on Quest: How it works (on GitHub).
#Documentation
All docs are published at lafaektoefl.tech/docs, with search, and are also readable here on GitHub.
| Guide | What's inside | Read |
|---|---|---|
| Our story | Why the app exists | Docs · GitHub |
| VR Study Room | Why VR, and how to use the hands-first room on Meta Quest | Docs · GitHub |
| User guide | Every screen, with screenshots | Docs · GitHub |
| How it works | Architecture, generation, mock test, auth, database, VR Study Room and Quest sign-in diagrams | Docs · GitHub |
| Cost per study plan | What one plan really costs in AI calls (measured: about $3.16) | Docs · GitHub |
| Developer guide | This README: setup, technical details, deployment | Docs |
#Run it yourself
Stack: Next.js 15 (App Router) · React 19 · TypeScript · Tailwind CSS 4 · PostgreSQL (Prisma 6) · Meta Model API · ElevenLabs · Amazon S3 · Nodemailer (Gmail SMTP) · GSAP · Vitest.
npm install # also runs `prisma generate`
cp .env.example .env.local # fill in values locally; never commit .env.local
npm run db:deploy # apply migrations (uses DATABASE_URL from the environment)
npm run db:seed # load the shared, hand-written starter set (idempotent)
npm run dev # web app on http://localhost:3000
npm run worker # background generation worker (separate terminal)
npm run vr:dev # optional: the VR room with IWSDK's browser XR emulatornpm run verify:providers checks Meta, ElevenLabs, SMTP and AWS access with minimal calls and prints no secrets.
#Environment
All variables are listed in .env.example.
- Anything without
NEXT_PUBLIC_is server-only. - The app checks its configuration per feature, only when that feature is used. A missing integration (for example
S3_BUCKET) disables only that feature. - The error message names the missing variable, never its value.
#Technical details
Browser ──fetch──▶ Next.js route handlers (app/api/*) ──▶ PostgreSQL (source of truth)
│ ▲
├─ Meta: AI scoring, speech-to-text │
└─ S3: short-lived signed URLs │
Worker (npm run worker) ── claims jobs from the queue ──────┘
├─ study_schedule: Meta outline of the learner's calendar → validated → dated days
├─ task_pack: Meta text → Zod validate → bounded repair → store questions
├─ vocabulary_pack: Meta picks words from those questions → stored per learner
├─ asset_image: Meta image → S3
├─ asset_audio: ElevenLabs speech → S3
└─ mock_scoring: transcribe + rate the mock test's open answers- Auth.
- Email and password. Passwords are hashed with
scrypt. - Sign-up is confirmed with a 6-digit email code. The code is stored only as an HMAC, expires after 10 minutes, allows 5 attempts and works once.
- Sessions are a random token in an
HttpOnly,SameSite=Laxcookie (__Host-andSecurein production). Only the token's SHA-256 hash is stored. - Every request that changes data checks
Origin. - Login, email codes, generation, feedback and uploads are rate-limited in PostgreSQL.
- Forgot-password points to the configured administrator (
ADMIN_CONTACT_EMAIL). - Guest demo (
lib/server/auth/guest.ts): "Try the demo, no account" on/vrand in the room creates a guest user (no password, no credits) and signs it in. Guests see a read-only view of one account's questions (DEMO_CONTENT_EMAIL), keep their own answers and progress, and have tight per-guest and all-guest daily limits on spoken answers and AI scores. Guests stay inside the VR area: the app layout and the "Leave the demo" link send them throughGET /api/auth/guest/exit, which signs a guest out (never a real account, and never on a link prefetch) and opens the home page. On a computer without WebXR the room makes Preview the room its main button. The worker deletes guests after 48 hours. LeaveDEMO_CONTENT_EMAILempty to turn the demo off. - Sign in another device (
lib/server/auth/device-link.ts,/link).- A signed-in device shows an 8-character code and QR code (no look-alike characters). It is stored only as an HMAC and expires in 5 minutes.
- The new device enters it, which only claims the code and gives that device a secret to poll with. The signed-in device then shows "Meta Quest browser wants to sign in" with Approve and Deny.
- Only after Approve does the new device get a normal session. Deny, or closing the code window, cancels it.
- Device limit. An account keeps at most 3 sessions. A 4th sign-in revokes the one used longest ago, so nobody is locked out. Settings lists the devices, with Sign out for each.
- Email and password. Passwords are hashed with
- Authorization.
- The
(app)layout requires a valid server session. - Every query is scoped to the signed-in user, and "not yours" returns the same 404 as "not found".
- The
- Content.
- Each learner sees the shared starter set (hand-written, original) plus their own personalised items.
- Personalised items are generated once per study plan: one batch per user and plan version, behind an idempotency key.
- Answer keys stay on the server. Objective tasks are scored with versioned logic (
objective-1). - Answer choices are shuffled per item, so the correct answer is not always "A".
- Study plans.
- Dated schedule.
- The plan counts the days from the learner's local "today" to the test date, which can be the same day or up to one year ahead.
- Study days fall on the weekdays the learner chose, up to the day before the test.
- Without a test date, the length depends on level: 6–12 weeks.
- Code:
lib/server/study-plan-builder.ts.
- Daily content.
- Each study day is filled within the learner's daily minutes, from the week's priority tasks (weak skills first), plus vocabulary review.
- A mock test is placed 3–6 days before the test, and the last study day is a light review.
- AI personalisation.
- Saving a plan shows the rule-based schedule at once and queues a
study_schedulejob. - In the worker, Meta proposes a week-by-week outline. It is validated against the real calendar, and invalid parts keep the rule-based week.
- Code:
lib/server/generation/study-schedule.ts.
- Saving a plan shows the rule-based schedule at once and queues a
- Credits.
- Every save uses one study-plan credit (the first plan, an edit, or a new plan).
- Without a credit, the server returns
402 UPGRADE_REQUIREDand the page shows Upgrade · $5.
- Dated schedule.
- Generation jobs.
- Job types:
study_schedule;task_pack: 12 per plan, 133 questions in total, with default counts inlib/config/practice-types.ts;vocabulary_pack,asset_image,asset_audio,mock_scoring,delete_user_assetsandreconcile_media.
- Reliability. Jobs use leases with heartbeats, expired-lease recovery, exponential backoff with jitter, per-user concurrency limits and per-item checkpoints. Completed items are never regenerated.
- Two lanes.
- Question packs (
task_pack) run in a long lane:WORKER_CONCURRENCY, default 3. - Everything else runs in a quick lane with its own slots:
WORKER_QUICK_CONCURRENCY, default 6, and up to 4 per learner. That covers audio, pictures, vocabulary, the schedule and mock-test rating. - Short jobs never wait behind a pack that takes minutes.
- Question packs (
- Build a Sentence is written and checked in batches of 5 with low model reasoning (
reasoning_effort: "low"). That is about 8× faster, with the same pass rate on the grammar check. - Model problems.
- On
model_not_found, Meta calls retry 3 times, then useMETA_TEXT_FALLBACK_MODEL(muse-spark-1.2). - A rejected key waits as
PROVIDER_CONFIGinstead of failing. - Usage events are idempotent by provider request ID.
- On
- Job types:
- Question formats.
- Generated questions follow the TOEFL iBT 2026 formats (lengths, question counts and question types), checked against published practice tests.
- The content is always original.
- Complete the Words blanks are made in code, the same way as the real task (
lib/server/content/c-test.ts).
- Vocabulary.
- There is no fixed word list. When a practice type's questions are finished, a
vocabulary_packjob asks Meta for up to 10 useful words from those questions. - Words that do not occur in the texts, or that the learner already has, are dropped.
- Pronunciation comes from ElevenLabs. The clip is made the first time a word is played and stored privately in S3.
- There is no fixed word list. When a practice type's questions are finished, a
- Voices.
Each speaker has a gender, and the picture shows the same people, so a woman in the picture speaks with a female voice.
Voices follow the accents chosen in the study plan (American, British, Australian, Indian, African), rotating across items.
Every accent has a female and a male voice. American and British voices are ElevenLabs standard voices built into the app. The others come from the ElevenLabs Voice Library and are listed in
ELEVENLABS_VOICE_IDSasid:accent:gender.Production voices (all tested on 2 November 2026):
Accent Female Male American Sarah, Laura, Jessica, Matilda, Aria (built in) Brian, Chris, Eric, Will, Liam, Roger (built in) British Alice, Lily (built in) George, Daniel (built in) Australian Voice Library p43fx6U8afP2xoq1Ai9fCharlie (built in), Voice Library 7AJyv0vI6pBx5JTb9p6CIndian Smita ctgnaLIeDdomGMnEAjYfSaagar 2DRBj9T2XZ7Jmkcm6WCZAfrican (South African English) Annabel nV2afREa5mKDMAIpqMu0Sizwe qp5KnBkVXn1iOyKYgIDATo use the same voices in your own copy:
- Add each Voice Library voice to your own ElevenLabs account (Add to My Voices).
- Set the following line:
ELEVENLABS_VOICE_IDS=ctgnaLIeDdomGMnEAjYf:indian:female,2DRBj9T2XZ7Jmkcm6WCZ:indian:male,nV2afREa5mKDMAIpqMu0:african:female,qp5KnBkVXn1iOyKYgIDA:african:male,p43fx6U8afP2xoq1Ai9f:australian:female,7AJyv0vI6pBx5JTb9p6C:australian:maleSet it on the worker (listening audio) and on Vercel (word pronunciation). The new voices apply to newly generated audio; questions that already exist keep their voices.
If an accent has no voice of the speaker's gender, the learner's other chosen accents are used.
- Speaking.
- The browser converts recordings to 16 kHz mono WAV, and Meta
muse-voice-transcribe-1.0transcribes them. - Listen and Repeat counts as correct when at least 80% of the words match.
- Recordings are discarded after transcription unless the learner turns on Keep my speaking recordings.
- The browser converts recordings to 16 kHz mono WAV, and Meta
- Writing and interview scores.
- Emails, discussion posts and interview answers get an AI score (band 1–6) plus coaching, in about 10–15 s (
POST /api/practice/items/:id/feedback). - The criteria are shared with the mock test (
lib/server/rating-criteria.ts, based on ETS's 2026 scoring dimensions).
- Emails, discussion posts and interview answers get an AI score (band 1–6) plus coaching, in about 10–15 s (
- Plans and upgrades (
lib/config/pricing.ts,lib/server/credits.ts). There is no subscription, and credits never expire.- Starter, free for life: 1 study plan and 1 mock test.
- Boost Pack, $5 per pack: +1 study plan and +2 mock tests. Learners email the admin, and the admin adds the packs (see Upgrade an account).
- Open Source: self-host from GitHub for personal, non-commercial use. Business use needs the admin's agreement.
- Credits are used atomically under a per-user advisory lock, so two requests at once cannot overspend.
- Mock test (
lib/server/mock-test.ts).- Contents: all 12 task types, about 80 questions in about 90 minutes.
- Reading: Complete the Words 1, Read in Daily Life 3, Academic Passage 2.
- Listening: Choose a Response 5, Conversation 2, Announcement 2, Academic Talk 2.
- Writing: Build a Sentence 10, Email 1, Academic Discussion 1.
- Speaking: Listen and Repeat 1 (7 sentences), Interview 1 (4 questions).
- Starting uses one mock credit. Reloading resumes the test without using another credit.
- Signed form: the browser gets the chosen questions in an HMAC-signed token, so a submission scores exactly those questions, once, for that user.
- Timing: Reading 30, Listening 29, Writing 23 and Speaking 8 minutes. There is no pause, audio plays once, spoken answers cannot be re-recorded, and right or wrong is not shown during the test.
- Scoring.
- Reading, Listening and Build a Sentence are scored on submit.
- The email, the discussion post and the interview are rated by AI in the worker (
mock_scoring). - Recordings are deleted after rating.
- Every section gets a band (1–6), and the overall band is their average.
- Certificates.
- An overall band of 4.0 or higher earns a certificate with an ID and QR code.
- Anyone can check it at
/verify/<ID>(lib/server/certificates.ts). - Learners without one can open a watermarked preview.
- Contents: all 12 task types, about 80 questions in about 90 minutes.
- VR Study Room (source in
vr/, built intopublic/vr/room/).- Built with Meta's IWSDK (
@iwsdk/core, on Three.js) as a Vite app. The room is made from simple shapes and small canvas textures to stay at 72 fps or more on Quest. /vr(Next.js) checks that the browser supports immersive VR and that the learner is signed in with a study plan, then links to/vr/room.- Hands first: hand tracking is on, presses act on release, and Build a Sentence tiles can be grabbed. The dock above the desk accepts a fingertip touch, a far pinch and a pinch right next to a button. Controllers also work.
- Characters: ten Listening speakers and the interviewer are glTF models made with Meshy AI from our own design pictures (about 15,000 to 20,000 triangles each, see
vr/public/models/CREDITS.md).vr/src/speakers.tspicks who appears by the voice's gender, the scene and the title. They have no skeleton: a vertex shader (vr/src/talk.ts) opens the jaw by the loudness of the voice and turns the forearms while speaking. - Progress: each activity resumes at the first unanswered question, shows a live "Welcome back" bar, and has Start over (the website's reset endpoint).
- Sound: spatial voices, a recorded spoken introduction on the start screen, and background music that plays only on the quiet screens and can be turned off on the dock.
- Built with Meta's IWSDK (
- AI call logs (
lib/server/providers/meta.ts,lib/server/call-context.ts). Every Meta API call writes onemeta.api.callline (JSON) to the server logs: host and endpoint, the model Meta returned, Meta's request or session id, duration, status, token usage or audio length, a preview of the response (400 characters;LOG_AI_RESPONSES=offremoves it), and the source:client: "vr-room"(the room sendsX-Lafaek-Client: vr-room),"web"or"worker"with the job type. Failures writemeta.api.error. Searchmeta.api.callin Vercel's or Render's logs; real examples from the VR room.- Questions, answers and scores use the same routes as the website (
/api/practice/...). Pictures and audio load through/api/media/[id]/file, because WebGL and Web Audio cannot read cross-origin S3 links. Spoken answers are converted to 16 kHz WAV in the headset. - URL options:
?mode=previewopens the room in a normal browser,?open=<station>starts at one activity, and?fps=1shows a frame-rate readout. - Vercel does not build
vr/. After changing it, runnpm run vr:buildand commitpublic/vr/room/.
- Questions, answers and scores use the same routes as the website (
- Docs site (
app/docs,lib/server/docs.ts)./docsrenders the Markdown guides listed inlib/config/docs.tsat build time, with search, a table of contents and GSAP motion.- Images are resized to WebP during the build.
- Interface motion (GSAP). Every animation is turned off when the device asks for reduced motion (
lib/client/motion.ts).- The loading screen is the crocodile logo breaking into pieces and snapping back together.
- Pages, results, flashcards and toasts have short entrance effects.
- The mock test has a "preparing" screen and a submit screen with a progress ring.
#Commands
| Command | What it does |
|---|---|
npm run lint / npm run typecheck / npm run build |
Quality gates |
npm test |
Unit and integration tests (integration uses the isolated lafaek_test schema) |
E2E_BASE_URL=http://localhost:3200 npx vitest run tests/e2e |
HTTP end-to-end tests against a server started with the test schema |
node scripts/check-secrets.mjs |
Fails if any secret value appears in client bundles or git-tracked files |
npm run db:status / npm run db:deploy |
Migration status / apply |
npm run worker / npm run worker:prod |
Generation worker (--once drains the queue and exits) |
npm run vr:dev / npm run vr:build |
VR room with the IWSDK emulator / build it into public/vr/room/ (commit the result) |
npm run upgrade:grant -- <email> [packs] [note] |
Upgrades an account with Boost Packs (uses the .env.local database) |
npm run upgrade:grant:prod -- <email> [packs] [note] |
The same on the production worker (Render Shell) |
New migrations: change prisma/schema.prisma, then create a migration with prisma migrate diff and apply it with db:deploy. Render users usually cannot create the shadow database that migrate dev needs.
#Upgrade an account (Boost Pack)
There is no subscription. The paid upgrade is the Boost Pack ($5): each pack adds 1 study plan and 2 mock tests, for life. Learners ask for it by email: the Upgrade button opens a prefilled message to the admin. After they have paid, the admin adds the packs:
# From your computer (uses DATABASE_URL in .env.local)
npm run upgrade:grant -- learner@example.com # 1 pack: +1 study plan, +2 mock tests
npm run upgrade:grant -- learner@example.com 3 "paid by bank transfer" # 3 packs, with a note
# On the server: Render dashboard → the worker → Shell
npm run upgrade:grant:prod -- learner@example.com 1 "paid by bank transfer"- The email must belong to an existing account, and each command adds 1 to 20 packs.
- Every grant is recorded in
credit_grants, and the learner's Usage page shows the new plan, for example "Starter + 1 Boost Pack". - An admin user (
role = 'admin') can do the same throughPOST /api/admin/upgrades, which also writes an audit event.
#Deployment
- Web (Vercel).
- Set the variables from
.env.examplefor each environment in Vercel's settings. - Use Render's external database URL with
sslmode=require. - Run
prisma migrate deployonce per release. - Set
APP_URLto the custom domain on both Vercel and the worker. It is used for links in emails. - The VR room ships as the committed static build in
public/vr/room/, so it needs no extra deployment step.
- Set the variables from
- Worker (Render Background Worker). Vercel only runs short request handlers, so the worker needs its own host. Without it, generation jobs stay queued.
- Region: Singapore. Meta's API lists no models to Render's Ohio network, but works from Singapore.
- Build command:
npm ci --include=dev.tsxandprismaare devDependencies. - Start command:
npm run worker:prod. - Instance size: 0.5 CPU / 512 MB is enough. A learner's whole plan is ready in about 10–15 minutes:
- what that covers: the AI schedule, all 133 questions, vocabulary, audio and pictures;
- why a larger instance would not help: the worker mostly waits on the AI and voice APIs.
- Alternative: a cron job can
POST /api/internal/worker/tickwithAuthorization: Bearer $WORKER_TICK_SECRETto process one job per call.
- Live deployment.
- The web app runs at https://www.lafaektoefl.tech (Vercel), and the worker runs on Render in Singapore.
- The database is PostgreSQL on Render, and media is in AWS S3.
- S3.
- Use a private bucket with Block Public Access and server-side encryption.
- Give the IAM user least privilege on that one bucket (
s3:PutObject,s3:GetObject,s3:DeleteObject,s3:ListBucket).
- Admin.
- Set
role = 'admin'on a user in the database. GET /api/admin/jobslists failed or blocked jobs, andPOST /api/admin/jobs/:id/retryretries one.
- Set
#Data retention
| Data | Kept | Deletion |
|---|---|---|
| Email codes | HMAC only, 10-minute validity | Superseded codes are invalidated; rows go when the account is deleted |
| Sessions | 30 days (SESSION_TTL_DAYS), at most 3 per account |
Revoked on logout, from Settings, or when a 4th device signs in; all deleted with the account |
| Device sign-in codes | HMAC only, 5 minutes (at least 3 more once a device enters the code) | Used once; pruned by the worker a day after they expire |
| Practice recordings | Only with opt-in consent | Learner can delete each one; deleted with the account |
| Mock test recordings | Until the AI rating finishes (about a minute) | Deleted by the mock_scoring job; the result keeps bands and short comments |
| Certificates | While the account exists | Deleted with the account; a revoked one shows "Revoked" on the check page |
| Practice answers, plans, generated items, usage | While the account exists | DELETE /api/account deletes all rows and queues S3 clean-up |
| Guest demo accounts | 48 hours | Deleted by the worker with their sessions, answers and progress; signed out as soon as they leave the VR area |
| Rate-limit counters | 2 days | Pruned by the worker |
#Scores and costs
- Score scale. The TOEFL iBT 2026 scale is used throughout: bands from 1 to 6 in 0.5 steps, with CEFR levels (6 C2, 5–5.5 C1, 4–4.5 B2, 3–3.5 B1, 2–2.5 A2, 1–1.5 A1). See
lib/config/toefl-scale.ts. - Scores are practice estimates. All scores and feedback are practice estimates, never official ETS/TOEFL scores. Speaking is judged from transcripts, so pronunciation itself is not scored.
- Costs.
- Meta calls return token usage, which is stored per call in
usage_events. - ElevenLabs returns no usage data, so characters are stored as estimates.
GENERATION_DAILY_USER_LIMITcaps generation per learner per day.
- Meta calls return token usage, which is stored per call in
#Project structure
app/(public)/ landing, login, signup, verify-email, forgot-password, certificate check, /link (sign in with a code)
app/vr/ the /vr landing page for the VR Study Room
app/(app)/ signed-in pages (server components fetch data via lib/server)
app/api/ route handlers (Zod-validated, request IDs, sanitized errors)
app/docs/ the /docs site
components/ UI, layout, practice engine, study-plan calendar, mock test, docs, motion, charts
docs/ user guide (with screenshots) and architecture diagrams
hystory/ the story behind the project
public/vr/room/ the built VR Study Room (committed; served at /vr/room)
vr/ VR Study Room source (IWSDK + Vite)
lib/config/ practice types, navigation, assets, pricing, docs list
lib/client/ browser helpers: API client, WAV encoder, GSAP motion setup
lib/practice/ client-safe DTOs (never contain answer keys)
lib/server/ server-only: env, db, auth, providers, storage, content, generation, docs
prisma/ schema, migrations, starter content
scripts/ worker, seed, provider checks, upgrades, secret scan
tests/ unit, integration (isolated schema), e2e (HTTP)#Known limitations
- Indian, African and Australian voices come from the ElevenLabs Voice Library, so a self-hosted copy must add them to its own ElevenLabs account first (see Voices). Audio made before 2 November 2026 used the learner's other chosen accents in place of these three.
- Starter-set items have no generated audio yet and use the browser's voice. They also predate some 2026 formats.
- Practice AI scores and speaking transcription run in Vercel route handlers (usually 10–15 s, within the 60 s limit). If they ever time out, they can move to the worker queue, as the mock test rating already does.
- There is no self-service password reset, and Google sign-in is not implemented.
- AI bands for Writing and Speaking are model estimates. Results and certificates say so.
- Write an Email and Write for an Academic Discussion are typing tasks, so they stay on the website and are not in the VR room.
#License
MIT, see LICENSE. TOEFL is a registered trademark of ETS; this project is not affiliated with ETS.