رَفِيق — Rafiq
Learn to read, understand and speak Modern Standard Arabic in short daily lessons, fully vowelled, with instant feedback on what you write and say. Live at rafiq-arabic.com.
Static site (GitHub Pages) + Supabase for accounts and progress + one Cloudflare Worker for answer checking. No build step.
How it's organised
Home is a single path with one Continue button. Units open in order — a unit unlocks when the one before it is done (or skipped by placement), and steps inside a unit open in order; anything finished can be revisited. The Practise area is never locked. Each unit is a run of 5–10 minute steps:
meet 10 words → hear the conversation → how it works → meet the next 10 → practise → … → have the conversation → say it yourself
A reading starter (unit 0: the 28 letters in shape families, then the vowel marks) comes first; readers skip it with one tap. Sign-up asks three questions — can you read Arabic, how much do you know, minutes a day — and learners who know some Arabic take a 6-sentence placement check that sets their starting unit.
Practise is for going beyond the lessons (it no longer repeats them): real-life scenes (six conversations — airport, doctor, masjid, restaurant, taxi, visiting a family — in scenes-data.js, played with the conversation partner; Complete), a weak-spots review (session.html?focus=weak: exercises tagged with the learner's repeat mistake types in item-tags.js, generated by tools/typesafe-exp/tag_items.py, plus items they recently missed; Complete), Verbs, Joining words, Your words (flashcards and a test on the words met in lessons only, plus the full list) and Redo a unit (session.html?unit=NN&redo=1, finished units only). Review of what's been learned lives on Home.
Progress (progress.html) shows words learned, sentences practised, units done and streaks; today / 7 days / 30 days; new words per day for the last two weeks against your usual day (the median of the last four weeks); and 12 weeks of practice days. A day with more new words than usual, or a best day, is highlighted after the lesson, on Home and on Progress.
| File | |
|---|
index.html | Landing page, pricing |
onboarding.html | Three questions + placement check |
dashboard.html | Home: today's step, streak, daily goal, your week, mistake focus, the path |
learn.html | Runs one lesson step, one card at a time |
practise.html | Extra practice menu |
progress.html | Progress tracking |
session.html | Review session; ?unit=NN is a lesson's Practise step |
vocab.html, drills.html, verbs.html, connectors.html | The practice areas |
path.js / path-data.js | The path: steps, progress, streak. path-data.js is generated by tools/build-path.js |
alphabet-data.js | The reading starter |
vocab-data.js, drills-data.js, toolkit-data.js | Words, units, verbs and joining words |
salah-data.js | "Your salah" data (generated by tools/salah/build.py; awaiting teacher review, not shown in the app yet; review sheet: tools/salah/REVIEW.md) |
essentials-data.js, essentials.js | Practise → Everyday essentials: numbers, days, Islamic and Western months, colours, telling the time (table + drill) |
judge.js | Talks to the checking Worker; falls back to plain matching |
mistakes.js | The mistake profile shown on Home |
plan.js | Essentials vs Complete, and the beta switch |
nav.js | The four tabs (Home, Practise, Progress, Settings) on every page |
pwa.js, sw.js, manifest.json | Installing to the home screen: the install card (Home, Settings), iPhone splash screens (icons/splash/), offline pages and audio, and reminder notifications |
Progress
One store (progress.js) in Supabase, with an offline mirror. Ids are namespaced: v: words, d: sentence drills, p:<unit>|<step> lesson steps (and p:<unit>|placed for units skipped by placement), s:<date> days with activity (streak and daily goal), w:<date> new words met in lessons that day, e:<date> sentence exercises done that day. Words met in a lesson enter spaced repetition due the next day; sessions only use units the learner has reached.
Answer checking
Two layers: an exact match in the browser (vowel marks ignored; "a/an/the" ignored for English), then, if that fails, a judgment on meaning from TypeSafe through the Worker. The Worker only asks fixed questions — its kinds are vocab, produce, build, rewrite, prompt and reply — so the key can't be used for anything else, and only answers requests from rafiq-arabic.com. If the Worker is unreachable or slow (3 s), pages fall back to exact matching. Dictation and verb forms stay exact-match on purpose.
Each check was measured on hand-labelled answers before it shipped (tools/typesafe-exp/):
| Check | Cases | Judge | Before |
|---|
| Vocab: typed English | 43 | 95% | 53% (exact match) |
| Produce: typed Arabic | 37 | 92–95% | 49–76% (word matching) |
| Build-it reorders | 15 | 15/15 | only one order accepted |
| Transform / Fix-it | 33 | 31/33 | reveal only |
| Free speaking: task done / grammar | 17 | 17/17 / 17/17 | — |
| Conversation: does the reply fit? | 40 | 40/40 | — |
The case counts are small — a sanity check, not a guarantee. When the judge is unsure the learner gets "Nearly — compare with the model answer" rather than a verdict.
TypeSafe is also used offline, never at run time, to pick a picture for 114 concrete words from a fixed emoji list (pick_pictures.py) and to check the grammar of new dialogue lines (qa_dialogues.py). It chooses; it never writes Arabic.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
