Vocab
Vocabulary practice focused on real usage.
Overview
Vocab is an app for learning vocabulary by practicing how words are used, not just recognizing them. Each word is practiced by writing your own sentence that an AI evaluates —linguistic analysis + verdict—, inside a spaced-repetition system. I started it in February 2026 to prepare for the DELE Spanish exam, and I use it daily. I then turned it from a personal tool into a full multi-user product.
The problem
I was preparing for the DELE and had built up a huge list of words. But flashcards aren't the best way to move vocabulary into active use: you can see a word, understand its definition, and still not know how to use it. On top of that, maintaining lists by hand costs time and attention — exactly what pulls you away from practicing.
I wanted two things: to remove the friction of adding words, and to practice real usage instead of passive recognition.
The solution
From an underlined word to active practice: the workflow is the heart of the project.
- I underline a word on my phone and run an iOS Shortcut. I type nothing and don't specify the language: the server detects the language, validates that the word is real, and discards duplicates and variants (conjugations, plurals) via a similarity funnel + LLM judge.
- The app shows me the word and I write a sentence. An AI judges whether I used it correctly and analyzes grammar and register, with suggestions. The goal isn't to recognize the word — it's to produce it in a real situation.
- Each word is rescheduled based on my performance with SM-2. A calendar shows what's due and when. Practice modes: spaced, situation (active recall), free, and image (describe a photo with vision analysis).
- To turn it into a product: custom auth at the edge (email/PBKDF2 + Google OAuth without a library, JWKS RS256 verification with Web Crypto), a multi-tenant database on Cloudflare D1, and BYOK — each user brings their own AI key, zero server cost.
Architecture
📱 iPhone (underlined word) 🌐 Single-page app (Safari)
│ Shortcut → POST /add │ Google / email login → JWT
│ (+ personal token) │
▼ ▼
⚙️ Cloudflare Worker (edge)
JWT auth · BYOK · /add route
│
┌───────────────┼────────────────────┐
▼ ▼ ▼
🤖 OpenAI 🤖 OpenAI / Gemini 🗄️ Cloudflare D1
language detect sentence evaluation (edge SQLite)
+ duplicates (user's own key, data by user_id:
(gpt-4.1-mini) BYOK) words · progress · etc.
>> Underline a word and tap a Shortcut: that's all the "work."
Practice trains USAGE, not recognition. The only manual step is running the Shortcut. Everything else is automated.
Tech stack
| Layer | Technology |
|---|---|
| Frontend | Vanilla JavaScript, a single index.html, HTML/CSS, mobile-first (Safari/PWA) |
| Frontend hosting | GitHub Pages (deployed via GitHub Actions) |
| Backend / proxy | Cloudflare Worker (edge) |
| Database | Cloudflare D1 (edge SQLite), multi-tenant by user_id |
| Authentication | Email + PBKDF2 (Web Crypto) · Google OAuth (ID token, JWKS RS256) · JWT sessions (HS256) |
| AI (practice) | BYOK — OpenAI (GPT) and Google (Gemma/Gemini), streaming, multi-provider abstraction |
| AI (capture) | gpt-4.1-mini server-side: language detection, validity, similarity |
| Mobile capture | iOS Shortcuts → POST /add with a personal token |
Technical challenges solved
Auth from scratch at the edge
PBKDF2 password hashing and Google ID-token verification via JWKS (RS256) inside the Worker with Web Crypto, no libraries. Account linking by email: same email = one account whether you sign in with Google or password.
Sheets → D1 migration without losing the single-page frontend
Normalized data into relational tables keyed by user_id and rewrote ~25 data-access calls, keeping the app as one file.
BYOK with cross-device sync
The key travels in a header on each AI request and is never stored server-side by default. An opt-in syncs it (encrypted at rest) across the user's devices via D1.
Frictionless capture with server-side intelligence
The /add route reproduces a validation funnel — language + sense + similarity (normalized scoring + LLM judge) — reading existing vocabulary from D1, and answers in the exact format the iOS Shortcut already understands.
AI sentence evaluation
Structured verdict + linguistic analysis, streamed, handling reasoning-model token budgets and anti-hallucination rules in the prompts.
Spaced repetition (SM-2)
Per-word rescheduling, a daily new-word cap, and day boundaries based on the user's local time.
Results
- Daily use since February 2026 to prepare for the DELE; a personal library of 8,000+ words.
- Practicing usage, not recognition: I write real sentences and get immediate correction.
- Near-zero capture friction: underline + one Shortcut, no typing, no language tagging.
- Tool to product in a few days: auth (Google + email), per-user data, BYOK, and production deployment — with zero server-side AI cost.
What this project demonstrates
I built a complete end-to-end full-stack system alone — mobile capture, frontend, authentication, an edge database, and integration of several AI APIs — and, above all, turned a real personal need into a product others can use. It grew out of learning a language: technology serves the practice, automating the boring part to protect what matters — actually using the words.