Lingo AI (MVP)
Spanish conversation practice for Hebrew speakers, with two virtual teachers (Lucía and Vale) and real-time voice.
Invite-only beta, 18+.
Stack: Next.js 16 on Vercel, Supabase (Auth + Postgres), OpenAI Realtime API over WebRTC.
How a conversation is secured
- The browser asks
/api/realtime/session to start a call (Supabase session cookie).
- The server checks the daily quota and the monthly budget in one Postgres transaction (
start_session), and reserves the worst-case cost.
- The server asks OpenAI for a client secret that lives 60 seconds, with the persona prompt and voice locked in. The browser gets only that secret, never the API key.
- The browser connects to OpenAI directly over WebRTC.
- On hang-up,
/api/realtime/end bills the real time (capped by the server clock), books the cost, and stores the transcript encrypted with AES-256-GCM.
Limits
| Limit | Default | Where |
|---|
| Talk time per user per day (Israel time) | 15 min | DAILY_LIMIT_MINUTES |
| Longest single call | 10 min | MAX_SESSION_MINUTES |
| Monthly API budget | $50 | MONTHLY_BUDGET_USD |
| New calls blocked at | 90% of budget ($45) | BUDGET_BLOCK_RATIO |
| Cost booked per minute (at least) | $0.10 | RESERVE_USD_PER_MINUTE |
| Transcript retention | 30 days | pg_cron job in the migration |
The booked cost per call is the larger of the client-reported token cost and the per-minute estimate, so the cap holds even if a client lies. As a second safety net, set a budget limit on the OpenAI project that owns the key.
Setup
- Supabase: create a project, then run the migration in
supabase/migrations (SQL editor, or npx supabase db push).
- Authentication > Sign In / Providers > Email: turn off "Allow new users to sign up". Accounts are created only through invites.
- Authentication > URL Configuration: Site URL = your app URL; add
<APP_URL>/** to Redirect URLs.
- Email templates can stay as they are:
/auth/callback handles Supabase's default links.
- OpenAI: create a dedicated project, set its monthly budget, and create a key there.
- Env vars: copy
.env.example to .env.local and fill it in. On Vercel, add the same variables and mark secrets as Sensitive.
- Invite someone:
node --env-file=.env.local scripts/create-invite.mjs [email protected] "beta wave 1".
- Persona tests (optional): set
PERSONA_TEST_KEY (24+ random characters, Sensitive, Preview only), then open <PREVIEW_URL>/api/admin/persona-test?key=.... A second model plays a learner through each scenario in src/lib/persona-test.ts and the endpoint returns the transcripts. Add &persona=vale or &scenario=injection to run one.
Scripts
npm run dev # local dev server
npm test # unit tests (crypto, cost)
npm run lint
npm run typecheck
npm run build
