Hablaba
Spanish practice for parents raising a bilingual baby. Built for someone with
one hand on a pram: mobile-first, installable as a PWA, usable in five minutes
or fifteen.
Deployed on Vercel at spanishroutine.com.
What's in it
| Surface | What it does |
|---|
Phrases (/app/speak) | Ready-to-say phrases grouped by daily routine, with audio |
Practice (/app/practice, /app/chat) | Text conversation with an AI tutor that corrects as you go |
Charlar (/app/charla) | Hands-free spoken conversation, screen-off — transcribed, reviewed afterwards |
Palabras (/app/palabras) | Vocabulary: a tappable body diagram, sets for animals and food, your own words translated on the spot, and a spaced-repetition review that rests a word once you know it and brings it back weeks later |
Exercises (/app/exercises) | Grammar quizzes generated from teacher handouts |
Grow (/grow) | Bounded bilingual-parenting module: daily Rioplatense phrase packs, gap capture, sparring, journal, voice |
The loop that matters: speak → get your patterns back → practise the exact
gap → speak again. A spoken session is analysed into tagged observations, a
weekly report ("Tu semana") groups them into patterns, and each pattern links
straight to the quiz for that rule.
Running it
npm install
npm run dev # localhost:3000
npm run build # production build
npm run lint # ESLint
npx tsc --noEmit # typecheck (the build ignores TS errors — see below)
There is no test framework. Verification is typecheck + build + manual testing
on a phone.
npm run validate:content checks the Exercises content packs against their
schema.
Environment
Only OPENAI_API_KEY is required — every AI feature runs through it (chat,
packs, TTS, transcription, the Realtime voice engine, and the transcript
analysis). Everything else is optional; see CLAUDE.md for the full list.
Voice mode additionally needs Realtime API access on the OpenAI account,
which is gated separately from the chat models.
Testing voice mode
getUserMedia requires a secure origin, so voice mode does not work over plain
http://<lan-ip>:3000. Either use an HTTPS tunnel to your dev server, or test
against the deployed site. Primary target is Chrome on Android installed as a
PWA, where a session survives the screen going off; iOS Safari suspends the
mic instead and gets an explicit paused state.
Architecture notes
- Next.js 16 App Router, React 19, TypeScript, Tailwind 4, shadcn/ui.
- No server database. All state is per-device, table-shaped localStorage
designed to map 1:1 to future SQL. API routes are stateless LLM proxies; the
client owns persistence.
next.config.mjs sets ignoreBuildErrors: true for TypeScript and
ESLint, so the build passes with type errors. Run npx tsc --noEmit
yourself — expect two known pre-existing errors in app/manifest.ts (Next's
type is narrower than the web manifest spec allows for purpose).- Grow is a deliberately bounded module with rules about what may cross its
edge in either direction. Read
lib/criar/README.md before importing across
it.
- Vocabulary is a separate table from phrases (
lib/vocab/), because a word
carries an article and a gender and a phrase doesn't. Read
lib/vocab/README.md before merging the two.
- The voice engine is shared (
lib/voice/), and
lib/voice/openai-realtime.ts is the only file that knows about WebRTC or
OpenAI event names — so the provider stays swappable.
CLAUDE.md is the working reference for anyone (human or agent) picking this
up; PRODUCT.md and DESIGN.md carry the product and visual-design intent.
