A web app that teaches English chunks — the ready-made phrases native speakers use, like “that makes sense” or “get used to” — to learners from A1 to C2, with one daily session: hear it, say it twice, write it, read it aloud, and get pronunciation scores and friendly tips from open-source AI running on infrastructure we control.
Most apps teach single words, but fluent speakers think in chunks: “by the way”, “make a decision”, “I tend to…”. Learners need to say those chunks out loud and know exactly which sounds to fix — and pronunciation feedback usually means sending your voice to a closed cloud API.
This project does the speech scoring with self-hosted open models (Silero VAD, NVIDIA Parakeet, wav2vec2 phonemes) and writes tips with an open-weight LLM (Gemma 4). Learner recordings are scored in memory and deleted immediately — they never touch a disk or a third party. Pronunciation hints come from a fixed, curated table of ~40 English sounds; the AI only adds warmth around them, so the teaching is always correct and consistent.
A session is Learn → Speak (try 1, try 2) → Write → Read aloud → Daily score, with streaks, points, a level-band ranking, a searchable chunk library, learner chunk suggestions with admin review, and an admin console.
Diagrams of the physical deployment, logical components and user workflow are in docs/architecture.md.
Installation
Prerequisites
Tool
Version
Node.js
≥ 22
pnpm
10
Python
3.12 (installed by uv)
uv
≥ 0.12
espeak-ng
≥ 1.51
Docker
any recent (local Postgres)
git clone https://github.com/gusanchefullstack/englishchunks.guru.git
cd englishchunks.guru
pnpm install
# Local Postgres (localhost URLs use the standard `pg` driver)
docker run -d --name ec-pg-dev -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=englishchunks \
-p 54329:5432 postgres:17-alpine
cp web/.env.example web/.env.local # fill in values (never commit them)
export DATABASE_URL=postgres://postgres:dev@localhost:54329/englishchunks
pnpm --filter web db:migrate
pnpm --filter web db:seed # voices, sound hints, 30 starter chunks
# Scoring service + models (~950 MB of ONNX int8 models)
cd scoring
cp .env.example .env
uv sync
uv run python -m scoring.models.download # Silero VAD + Parakeet
uv run --extra export python -m scoring.models.download --wav2vec2 # export + quantize wav2vec2
Quick Start
# Terminal 1 — scoring service on :8001 (models preload in the background)
cd scoring && uv run uvicorn scoring.app:app --port 8001
curl localhost:8001/healthz # {"status":"ok","models":{"vad":true,"asr":true,"phonemes":true}}
# Terminal 2 — web app on :3001
pnpm --filter web dev
Open http://localhost:3001, create an account (confirm you're 16+), click the link in the verification email, choose your level, and start today's chunk.
DigitalOcean Spaces (TTS cache, avatars). Also needed at build time for the CSP
Yes
—
RESEND_API_KEY / EMAIL_FROM
Transactional email
Yes
—
SCORING_URL / SCORING_SHARED_SECRET
Scoring service URL and HMAC secret (≥ 32 chars)
Yes
—
CRON_SECRET
Bearer secret for /api/cron/*
Yes
—
UNSUBSCRIBE_SECRET
Signs one-click unsubscribe links
Yes
—
STRIPE_SECRET_KEY
Stripe restricted key (rk_…)
When billing is on
—
scoring/.env: SCORING_SHARED_SECRET (same as the web app), MODELS_DIR (default ./models), MAX_AUDIO_SECONDS (15), MAX_AUDIO_BYTES (1 MiB), SOUND_HINTS_PATH (set in Docker).
{
"kind": "scored",
"score": 82,
"components": { "sounds": 83, "words": 100, "flow": 95 },
"weakestSounds": [{ "ipa": "ð", "hint": "Put your tongue tip lightly between your teeth, then use your voice. Not \"d\" or \"z\".", "exampleWords": ["that", "the", "other"] }],
"tip": "Lovely rhythm! Let your tongue touch your teeth on “that”.",
"improvement": 12
}
422 {"kind":"unusable","reason":"no_speech"} asks the learner to try again (not counted).
Other routes: GET /api/tts?ref=chunk:<id>|example:<id>|sentence:<id> (302 to audio), POST /api/profile/avatar, POST /api/billing/checkout, POST /api/billing/portal, POST /api/webhooks/stripe, POST /api/cron/hourly, GET|POST /api/cron/daily, POST /api/unsubscribe (RFC 8058).
Web unit + integration (real SQL in PGlite, external services mocked with MSW — unmocked network fails the test)
Vitest
pnpm test
End-to-end (fake mic, real app + Postgres, deterministic AI fakes, axe WCAG 2.2 AA scans, keyboard-only run)
Playwright
pnpm --filter web test:e2e
Scoring unit + OpenAPI contract + "no audio persisted"
pytest
cd scoring && uv run pytest
Scoring calibration on speechocean762 (SC-005, ≥ 85 %)
pytest
uv run pytest -m calibration
Scoring latency (SC-003, p95 ≤ 5 s)
—
uv run python -m scoring.bench
Lint · types · secrets
ESLint · tsc · ruff · mypy · gitleaks
pnpm lint && pnpm typecheck && pnpm secret-scan
Current results: 197 web tests, 21 e2e tests, 30 scoring tests; calibration 89.1 % over 66,189 pairs; scoring server p95 1.68 s on the production Droplet (see scoring/BENCHMARKS.md).
Deployment
Every change goes through a pull request to main; CI (lint, types, unit/integration, Playwright e2e with axe, scoring tests, secret scan) must pass, and merging deploys production automatically. The scoring service is updated separately per its runbook.
Web → Vercel (Hobby while testing; Pro before charging money). Set every variable above in the project, including Spaces ones (used by the CSP at build). vercel.json schedules the daily cron.
Scoring → DigitalOcean Droplet (start 4 GB / 2 vCPU): docker build -f scoring/deploy/Dockerfile -t ec-scoring ., mount models read-only, run with scoring/deploy/scoring.service (read-only root, tmpfs /tmp with exec for espeak), Caddy for TLS, and cron-hourly.timer to call /api/cron/hourly (reminders, invite expiry). See scoring/deploy/RUNBOOK.md.
Billing stays off until an admin types ACTIVATE in Admin → Settings, after the go-live checklist (Stripe test-mode demo, Vercel Pro, restricted live keys, Stripe Tax decision).
What I learned
Spec-driven development with Spec Kit: constitution → spec → clarify → plan → tasks → analyze → implement kept a 150-task build coherent, and /speckit-analyze caught real gaps (Google account-linking takeover, overdue-payment limits) before any code existed.
Next.js 16 Cache Components: request data (cookies(), headers(), searchParams, DB reads) must live inside <Suspense>; read headers before touching anything that needs env during prerender; await connection() marks DB reads as request-time; a streamed page can't change its status code later, so real 404s for the admin area come from proxy.ts.
Pronunciation scoring from first principles: CTC forced alignment and goodness-of-pronunciation (GOP) per phone. Averaging GOP in log space let one leaked boundary frame wreck a clean sound — averaging probabilities fixed it. Word accuracy as in-order recall (LCS) stops “that makes… that makes sense” from being marked wrong. (GOP paper)
Privacy by construction: Starlette spools multipart uploads > 1 MB to disk, so the service rejects oversized bodies before parsing; Docker's --tmpfs is noexec by default, which breaks phonemizer's espeak-ng copy.
Better Auth: email sign-up hides creation failures behind a synthetic success (anti-enumeration), so the account-cap gate must run in a request before hook; implicit Google account linking had to be disabled.
Testing seams that unit tests miss: MSW 3 renamed onUnhandledRequest to onUnhandledFrame (the old option silently let tests hit the real network); a real Chrome MediaRecorder recording and the Docker image each exposed bugs that every fake had hidden.
Accessibility: disabling a button while it's busy drops keyboard focus to <body> — use aria-disabled/aria-busy instead; brand colors needed an AA-safe palette and validated chart colors.
Stripe Billing: one Product per plan, hosted Checkout + Customer Portal, signature-verified idempotent webhooks resolved by Customer ID, and since the 2025 “basil” API the billing period lives on subscription items.
Roadmap
Daily session with self-hosted pronunciation scoring and open-weight LLM feedback
Write tests first; keep pnpm lint && pnpm typecheck && pnpm test, the e2e suite and uv run pytest green.
Use Conventional Commits (feat:, fix:, docs:…) and open a PR describing the user-visible change.
License
Distributed under the MIT License. See LICENSE for details. The AI models keep their own licenses: Silero VAD (MIT), Parakeet TDT 0.6B v2 (CC-BY-4.0), wav2vec2-lv-60-espeak-cv-ft (Apache-2.0), speechocean762 (CC-BY-4.0, calibration only).
Landing video (Spaces CDN) + WebVTT captions and poster (served from web/public/video)
No
walkthrough fallback
Structured output across providers: through the AI Gateway, Gemma runs on a provider without JSON-schema response formats, so the SDK silently dropped the schema and the model invented its own keys. Stating the schema in the system prompt fixed it — and mocked tests could never have caught it.
Perceived latency vs. compute: running ASR and the phoneme model in parallel only saved ~10 % on 2 vCPUs, but streaming the score before the LLM tip (NDJSON from a route handler) removed the 2–3 s the learner actually felt — with zero extra infrastructure cost.
Tailwind v4 defaults: buttons no longer get cursor: pointer, so a single global hover layer (pointer, deeper primary, muted fill) beat editing 30+ class strings.
