Talk in Seoul

Hangul class companion for Pop In Seoul, a Korean market in Springfield, IL.

Students come to an in-person Hangul class at the store, then use this phone-friendly web app to practice at home between classes. It is a warm, simple companion — not a full learning-management system.

Talk in Seoul · Hangul Class @ Pop In Seoul

What’s in this version

• Home — this week’s focus, an access-code box, then links: Pronunciation, Trace, Quiz, This Week
• Pronunciation — 모음(vowels), 이중모음(compound vowels), 자음(consonants), and 쌍자음(double consonants) are free (Jung’s audio + Record / Play me). All 14 자음, all 5 쌍자음 (ㄲㄸㅃㅆㅉ), and all 11 이중모음 (ㅐㅔㅒㅖㅘㅙㅚㅝㅞㅟㅢ) have teacher clips. 음절(syllables) is the full 140 CV chart; Play / Record need a class access code. All 10 vowel rows (ㅏㅑㅓㅕㅗㅛㅜㅠㅡㅣ, 140/140) have teacher clips.
• Bottom Sounds (/batchim) — 20 easy 받침 words. Coral marks the syllable with a bottom letter. Open to every student. Drop batchim-*.mp3 into public/audio/.
• Numbers (/numbers) — native 1–10, Sino-Korean 1–10, and the tens pattern. Open to every student. Drop number-*.mp3 into public/audio/.
• Conversation (/conversation) — 10 everyday phrases. Open to every student. Drop phrase-*.mp3 into public/audio/.
• Sound Workout (/sound) — ㄹ (reu) / (ri-eul) tap ladder and a ㅂ (beu) / ㅍ (peu) / ㅃ (ppeu) listen-and-pick. Open with or without a class code. New clips are sound-*.mp3. Words that already have a recording reuse that file.
• Real Talk (/real-talk) — counter conversations for Weeks 3–7. Jung is the cashier. Weeks 3 and 4 are free. Weeks 5–7 need full course access.
• Record & Compare — on any Play row, Record keeps a clip on this phone only (nothing is uploaded). Compare plays Jung, then you.
• Trace — finger tracing for the 8-week course, one letter at a time. Pick a line: Consonants ㄱ–ㅎ, then 쌍자음, 모음, and one syllable line per vowel (ㅏ 가 ~ 하 through ㅣ 기 ~ 히). A taste-class code does not open Trace. Wobbly strokes are fine. Press Done after any ink and the letter turns green. The doorbell (public/audio/trace-success.mp3) and Jung’s clip start together; his voice plays once and is fetched when the letter appears, not after the chime. The next letter appears shortly after his clip ends. Arriving on a letter does not play it; Hear it does. Done on an empty canvas shows a red X and “Try again.” The finger stroke is half the gray letter’s stem width. Last position is remembered on this phone.
• Quiz — flashcards. 모음(vowels) and 자음(consonants) (14 basic + 5 쌍자음) stay free; Play uses Jung’s clips. Words (단어) · Easy 20 is also free (no access code). Words (단어) · Class unlock needs the same student access code as 음절(syllables). Word cards have no teacher MP3s yet, so they stay silent. Compound vowels and 음절(syllables) are not in the jamo decks.
• This Week — writing sheets for the 8-week course: 자음 (2 pages ㄱ–ㅎ), 모음, and 단어 (animals: 개 호랑이 토끼 다람쥐 새 개구리 나비 곰). A taste-class code does not open them, and the PDF addresses are not public.
• My Progress (/progress) — Beginner checklist in the hamburger menu. Each step shows what you learn. Class progress is a filled dot, “Covered in class,” for every step through the week Jung set. My review is the student’s own check. Any class code can open it, including a taste-class code.
• Notices (/notices) — reminders Jung posts (title, message, date, optional pin). Newest first, pinned on top. A notice can be for every student or for one course. Needs a class code.
• Homework (/homework) — files for the student’s course, grouped Week 1, Week 2, and so on. PDF or photo. Needs full course access. A taste-class code still unlocks pronunciation and notices.
• Admin (/admin) — hidden from the student hamburger. Jung unlocks with a password, then:
  • Codes — issue a code, set its expiry, start or stop it, change that date later with Save date, turn Full course access (Homework, This Week, Trace, Real Talk) on or off, and delete it after confirming
  • Courses — add a class (Beginner is already there, 8 weeks), change its name or week count, set Class is at (Taste Korean Day or Week 1–8), and choose which class a code is for
  • Notices — post, edit, or delete reminders
  • Homework — post, edit, or delete homework and add or remove files

Menu is a hamburger in the top-left. English is the primary UI language, with Korean labels where they feel natural. Students do not create an account. Without a code they can still use the free app.

Old /lesson and /practice URLs go to Pronunciation.

Run locally

npm install
cp .env.example .env.local
# set ADMIN_PASSWORD in .env.local
npm run dev

Then open the URL Vite prints (usually http://localhost:5173) on your computer or phone.

Local issued codes are saved to .data/access-codes.json (gitignored) so you can test without Vercel Blob.

Other commands

npm run build    # production build
npm run preview  # serve the production build
npm run lint     # oxlint
npm test         # access-code helpers

Student enrollment is remembered in this browser (localStorage). Issued codes are not stored only on the phone — they live in Vercel Blob in production, or .data/ locally. Student recordings stay in memory for this visit and are never uploaded.

Admin password (Jung)

The password is never shipped to the browser. The app checks it on the server.

Set it on Vercel

1. Open the Talk in Seoul project on Vercel.
2. Go to Settings → Environment Variables.
3. Add ADMIN_PASSWORD with a long password only you know.
4. Apply it to Production and Preview.
5. Redeploy so /api/admin/login picks it up: Vercel → Deployments → ⋯ on Production → Redeploy (or merge this repo’s next PR). Do not skip the redeploy; env vars are applied at function boot.

This is the beginning of the README. Read the rest at the original. Read the full README ↗