System Requirements Document for nihongo-path

1. Introduction

Nihongo Path is a production-quality mobile application that takes a self-study learner from JLPT N5 to JLPT N2. It is built as a single React Native + Expo + TypeScript codebase for Android and iOS, with an offline-first SQLite store for all lessons, progress, and spaced-repetition data. The interface and support languages are English and Urdu, with full right-to-left support for Urdu text blocks.

The product intent is a patient, wellbeing-paced daily study ritual rather than a gamified arcade: a learner opens the app, sees one clear "Today" arc, works through review, new words, kanji, grammar, writing, listening, speaking, and a short quiz, and watches a long-horizon streak and level progression build up over months. The audience is English- and Urdu-speaking adults studying Japanese from beginner to upper-intermediate level, often on a mid-range Android phone, frequently at night.

The app is content-driven: every word, kanji, and sentence is presented in a four-line stack (Japanese with furigana, Romaji, English, Urdu RTL), and each level uses only the kanji and grammar of that level or lower. Content is stored as JSON by level and unit and imported into SQLite. Open datasets (JMdict, KANJIDIC2, KanjiVG, Tatoeba) and community level lists supply the linguistic data, with licenses respected and attribution surfaced in Settings. An optional, online-only AI tutor calls Claude through the user's own small backend proxy; no API key is ever placed inside the app, and the model name is a configuration value.

2. System Overview

Nihongo Path is delivered as a mobile application (Android and iOS) with an optional companion backend proxy owned by the user for the AI tutor. All core learning work — lessons, kana, kanji, writing, listening, speaking, spaced repetition, quizzes, mock tests, progress, and settings — runs offline against a local SQLite database. Only the AI tutor requires network connectivity, and it is explicitly optional.

The current delivery covers the full N5→N2 learning journey as specified: onboarding and placement, kana, the daily lesson arc, kanji study with stroke order and stroke checking, writing practice, listening with TTS dialogues, speaking roleplay with speech recognition and a typed fallback, SM-2 spaced repetition with a review-queue badge, weekly review tests and level mock tests with an 80% pass mark to unlock the next level, progress tracking with streak/XP/accuracy/weak points/weekly charts, the optional online AI tutor, and settings including display toggles, voice speed, theme, font size, reminder time, and progress backup export/import.

Actors are: the Japanese Learner (N5–N2), the AI Tutor Chat User (online), and the Content Maintainer / Importer. The AI tutor's Claude provider is an external service reached only through the user's own backend proxy. The app owns learner identity so that durable learning state, progress, and review queues remain bound to the correct learner across sessions and devices.

Narrow exclusions: the AI tutor is optional and online-only; no API key is stored in the app; N3 and N2 content is import-ready with the same schema but real authored content is created for N5 first, then N4 as a second pass; audio and speech features are only claimed to work when tested on a real device.

2a. Product Interpretation and Delivery Boundary

Nihongo Path is a first-party mobile application. The learner's durable state — lessons completed, SM-2 scheduling, streak, XP, accuracy, weak points, settings, and backup — is owned by the app and stored locally in SQLite, so the app must establish and verify learner identity before that protected state is created or resumed. The anonymous entry surface (Landing) explains the product and its N5–N2 journey; Sign Up establishes a new learner identity; Login verifies a returning learner, an online tutor user, or an authorized content maintainer. Content Maintainer / Importer access to Content Import is provisioned or authorized separately and is not self-service.

The AI tutor is a distinct, optional, online-only workflow. It is owned by the app's AI Tutor surface but depends on the user's own backend proxy, which holds the Claude API key server-side; the app never contains the key, and the model name is a configuration value. When there is no network or the proxy is unreachable, the AI tutor is unavailable and the rest of the app continues to work offline.

Microphone permission and an installed Japanese TTS voice are prerequisites for the speaking and audio workflows respectively; the app must handle their absence with clear recovery guidance (including how to install the Japanese voice) rather than failing silently. SQLite initialization and content import must complete before durable lessons and review queues can be used.

Future horizon: N3 and N2 are import-ready with the same schema but are not authored as real content in the current delivery; real content is created for all of N5 first, then N4 as a second pass. Play Store / App Store build steps with EAS are part of the final phase.

2b. Source Content Inventory

The following open datasets and community sources are authoritative content sources for Nihongo Path. Each must be used under its own license, and each must be listed on the Attribution screen in Settings.

• JMdict — open dataset for vocabulary. Used as the authoritative source for word entries (readings and meanings). License respected; attributed in Settings.
• KANJIDIC2 — open dataset for kanji data. Used as the authoritative source for kanji meaning, on'yomi, kun'yomi, and stroke count. License respected; attributed in Settings.
• KanjiVG — open dataset for stroke-order data. Used as the authoritative source for animated stroke order and stroke checking. License respected; attributed in Settings.
• Tatoeba — open dataset for example sentences. Used as the authoritative source for example sentences. License respected; attributed in Settings.
• Community level lists — community JLPT level lists used alongside the open datasets to assign items to N5/N4/N3/N2. Each list's license respected; attributed in Settings.

Content is stored as JSON files by level and unit with fields: id, level, jp, furigana, romaji, en, ur, audioText, tags. Any uncertain reading or meaning is marked needs review rather than guessed. Level targets: N5 ~100 kanji / 800 words; N4 ~300 kanji / 1,500 words; N3 ~650 kanji / 3,700 words; N2 ~1,000 kanji / 6,000 words.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression explaining Nihongo Path, its learner audience, and its N5–N2 learning journey; the four-line word-stack concept; the offline-first promise; the optional online AI tutor.
• Primary action: Begin — proceed to Sign Up (new learner) or Login (returning learner).
• Supporting actions: Switch interface language (English / Urdu / both); open Login directly.
• Domain entities: Product description, level range (N5–N2), language options.
• Component responsibilities: Hero greeting in Fraunces; a single hero card (28px radius) presenting the four-line word stack as the product's fundamental component; one terracotta primary CTA; language toggle.
• States: Loading (fonts/assets), empty (n/a), success (rendered), error (asset/font load failure with retry), recovery (retry).

Sign Up

• Information/state: Self-service enrollment for a learner starting independently; note that maintainer access requires separate authorization.
• Primary action: Create learner account.
• Supporting actions: Return to Landing; go to Login.
• Domain entities: Learner identity (credentials), consent to local-first storage.
• Component responsibilities: Input fields (14px radius), validation messaging, single primary CTA.
• States: Loading (submitting), empty (blank form), success (identity created → Onboarding), error (invalid/duplicate credentials, network-independent local validation), recovery (correct and resubmit).

Login

• Information/state: Shared returning-verification surface for learners, online tutor users, and authorized content maintainers.
• Primary action: Verify identity and resume protected state.
• Supporting actions: Go to Sign Up; return to Landing.
• Domain entities: Learner identity, maintainer identity.
• Component responsibilities: Credential inputs, error messaging, single primary CTA.
• States: Loading (verifying), empty (blank form), success (routed to Home for learners, Content Import for authorized maintainers), error (invalid credentials), recovery (retry, or go to Sign Up).

Onboarding

• Information/state: First-use setup: language choice (English / Urdu / both), daily goal (10 / 20 / 30 min), reminder time (default 9:00 PM, user can change).
• Primary action: Save setup and continue to Placement.
• Supporting actions: Change any individual choice before saving.
• Domain entities: Learner preferences (language, daily goal, reminder time).
• Component responsibilities: Segmented choices, time picker, single primary CTA.
• States: Loading (saving), empty (defaults shown), success (preferences persisted → Placement), error (save failure), recovery (retry).

Placement

• Information/state: Placement quiz that determines the learner's starting level.
• Primary action: Complete the placement quiz and receive a starting-level result.
• Supporting actions: Review answers before submitting; retake if desired.
• Domain entities: Placement questions, placement result (starting level).
• Component responsibilities: Question presentation using the four-line word stack where applicable; progress indicator; result summary.
• States: Loading (question set), empty (n/a), success (starting level assigned → Home), error (incomplete submission), recovery (resume or retake).

Home

• Information/state: Large greeting headline (time-aware), current date, level badge (N5 sage → N2 terracotta), the single "Today" card containing the whole lesson arc as a vertical checklist, the four-line word of the day, the daily review-queue badge (terracotta), streak number with breathing terracotta dot.
• Primary action: Start or continue today's lesson (single terracotta CTA pinned to the bottom of the Today card).
• Supporting actions: Open the review queue (Practice); open Learn; open Progress; open Settings.
• Domain entities: Daily lesson arc, review queue count, streak, XP, level badge, word of the day.
• Component responsibilities: Greeting headline (Fraunces); Today card (28px radius, 1px oat border); four-line word stack; vertical checklist with discrete level-coloured progress segments; review-queue badge; bottom tab bar (solid slate-green slab, 3px terracotta top rule on active tab).
• States: Loading (SQLite init / content import in progress), empty (no lesson scheduled yet → prompt to complete Onboarding/Placement), success (Today card populated), error (SQLite init or import failure with retry), recovery (retry; offline-safe).

Learn

• Information/state: Structured language study entry: kana, kanji, writing, listening, speaking, grammar, and level/unit browsing.
• Primary action: Choose a study area to enter.
• Supporting actions: Filter by level; resume last position.
• Domain entities: Levels (N5–N2), units, study areas.
• Component responsibilities: Full-width stacked rows (not grids of cards); level badge; progress fill per area.
• States: Loading (content index), empty (no content imported → prompt to import), success (areas listed), error (content read failure), recovery (retry).

Daily Lesson

• Information/state: The ordered 30–40 minute arc: review 10 old items, 5 new words, 3 kanji, 1 grammar point, then writing, listening, speaking, and a 10-question quiz.
• Primary action: Advance through each step in order.
• Supporting actions: Replay audio; reveal/hide text where applicable; pause and resume.
• Domain entities: Lesson steps, items, quiz questions, completion state.
• Component responsibilities: Step checklist with discrete level-coloured progress segments; four-line word stack; step-specific controls; single primary CTA per step.
• States: Loading (step content), empty (no lesson available), success (step completed → next step), error (step failure), recovery (retry step; resume from last completed step).

Kana

• Information/state: Hiragana and katakana charts; tap-to-hear; writing practice; kana quizzes.
• Primary action: Tap a kana to hear it; enter writing practice; start a kana quiz.
• Supporting actions: Switch between hiragana and katakana; replay audio.
• Domain entities: Kana characters, audio, stroke practice, quiz items.
• Component responsibilities: Chart layout; tap targets ≥48×48; audio playback via expo-speech (ja-JP); writing canvas; quiz runner.
• States: Loading (chart/audio), empty (n/a), success (audio plays / practice recorded / quiz scored), error (TTS voice missing → show how to install the Japanese voice), recovery (retry after installing voice).

Kanji

• Information/state: Meaning, on'yomi, kun'yomi, stroke count, animated stroke order, example words, and a trace-then-write-from-memory canvas with stroke checking.
• Primary action: Study a kanji; play the stroke-order animation; trace then write from memory.
• Supporting actions: Replay stroke animation with scrubber; view example words; move to next kanji.
• Domain entities: Kanji entry, stroke-order data (KanjiVG), example words, stroke-check result.
• Component responsibilities: Stroke-order animation (6px rounded slate-green strokes, current stroke terracotta, 120ms crossfade, replay scrubber); react-native-skia canvas; stroke checking.
• States: Loading (kanji + stroke data), empty (n/a), success (stroke check passes / animation completes), error (stroke data missing or canvas failure), recovery (retry; skip to next kanji).

Writing

• Information/state: Kanji tracing, typing practice with a romaji-to-kana keyboard, and sentence building by tapping word tiles.
• Primary action: Complete the selected writing exercise.
• Supporting actions: Switch exercise type; clear canvas; undo tile placement.
• Domain entities: Tracing targets, romaji input, kana output, word tiles, sentences.
• Component responsibilities: Tracing canvas; romaji-to-kana keyboard; tile tray and sentence area.
• States: Loading (exercise), empty (n/a), success (exercise completed), error (canvas or input failure), recovery (retry; clear and redo).

Practice

• Information/state: Recurring spaced-repetition work: the daily review queue driven by SM-2, with wrong answers returning sooner.
• Primary action: Work through the review queue.
• Supporting actions: Reveal answer; grade recall; leave and resume.
• Domain entities: Review items, SM-2 scheduling state, queue count.
• Component responsibilities: Flashcard with real 3D Y-axis flip (320ms); grading controls; queue progress; four-line word stack.
• States: Loading (queue), empty (no items due → encouraging message), success (item graded → next item), error (SM-2 persistence failure), recovery (retry; queue preserved).

Listening

• Information/state: TTS dialogues at normal and slow speed, dictation, 3 comprehension questions, and a toggle to show or hide text.
• Primary action: Play the dialogue; complete dictation; answer the 3 comprehension questions.
• Supporting actions: Toggle normal/slow speed; toggle show/hide text; replay.
• Domain entities: Dialogue, audio, dictation input, comprehension questions.
• Component responsibilities: Playback controls; speed toggle; text visibility toggle; dictation field; question runner.
• States: Loading (dialogue/audio), empty (n/a), success (questions answered), error (TTS voice missing → show how to install the Japanese voice), recovery (retry after installing voice).

Speaking

• Information/state: Roleplay scenes (shop, station, restaurant, office, hospital); the app speaks one side; the user answers by voice; the app shows what it heard next to the target sentence with a match score and tips; a type-instead option if recognition fails.
• Primary action: Respond by voice to the app's turn.
• Supporting actions: Use type-instead fallback; replay the app's turn; review match score and tips.
• Domain entities: Roleplay scene, turns, target sentence, recognized transcript, match score, tips.
• Component responsibilities: Scene opener illustration (tea cup, train window, shop counter, notebook); recording waveform (pulses while listening); transcript vs. target comparison; match score; tips; typed fallback input.
• States: Loading (scene), empty (n/a), success (match score and tips shown), error (no microphone permission → guidance; recognition failure → typed fallback), recovery (grant permission or type instead).

Tests

• Information/state: Weekly review test and a full JLPT-style mock test at the end of each level (vocabulary and kanji, grammar, reading, listening); pass mark 80% to unlock the next level.
• Primary action: Take the weekly review test or the level mock test.
• Supporting actions: Review results; retake; continue to the next level when unlocked.
• Domain entities: Test sections, questions, score, pass/fail, level-unlock state.
• Component responsibilities: Section runner; score summary; unlock messaging.
• States: Loading (test), empty (no test available), success (score ≥80% → next level unlocked), error (incomplete submission), recovery (retake).

Progress

• Information/state: Streak, words and kanji learned, accuracy by skill, weak-points list, and weekly charts.
• Primary action: Review progress and identify weak points.
• Supporting actions: Open a weak point to practice it; change week view.
• Domain entities: Streak, XP, words learned, kanji learned, accuracy by skill, weak points, weekly chart data.
• Component responsibilities: One big number; one weekly bar chart; weak-points list; level badge; friendly encouragement in English and Urdu.
• States: Loading (metrics), empty (no activity yet → encouraging message), success (metrics shown), error (metrics read failure), recovery (retry).

AI Tutor

• Information/state: Optional online chat practice that corrects sentences, explains mistakes in English and Urdu, and role-plays conversations. Requires network connectivity and the configured user-owned backend proxy; the provider API key remains server-side; the model name is a configuration value.
• Primary action: Send a message and receive corrections, explanations, or roleplay responses.
• Supporting actions: Start a roleplay; switch explanation language (English/Urdu); clear conversation.
• Domain entities: Chat messages, corrections, explanations, roleplay scenes.
• Component responsibilities: Chat transcript; input field; language toggle for explanations; offline/unavailable state.
• States: Loading (awaiting proxy response), empty (no messages yet), success (response shown), error (no internet or proxy unreachable → clear message; AI tutor unavailable while offline), recovery (retry when online).

Settings

• Information/state: Show or hide furigana, romaji, English, Urdu; voice speed; dark mode; font size; reminder time; export and import progress backup; link to Attribution.
• Primary action: Change a setting.
• Supporting actions: Export progress backup; import progress backup; open Attribution.
• Domain entities: Display preferences, voice speed, theme, font size, reminder time, backup file.
• Component responsibilities: Toggle rows; sliders; time picker; export/import controls; Attribution link.
• States: Loading (settings), empty (defaults), success (setting saved), error (backup export/import failure), recovery (retry).

Attribution

• Information/state: Open-dataset licenses and attribution for JMdict, KANJIDIC2, KanjiVG, Tatoeba, and community level lists.
• Primary action: Read attribution and license information.
• Supporting actions: Return to Settings.
• Domain entities: Dataset names, licenses, attribution text.
• Component responsibilities: Readable list of datasets with license text.
• States: Loading (attribution content), empty (n/a), success (shown), error (content read failure), recovery (retry).

Content Import

• Information/state: Authorized schema validation and import of N5–N2 level/unit content. Access is provisioned or authorized; not self-service.
• Primary action: Validate and import level/unit JSON content into SQLite.
• Supporting actions: Select level/unit; review validation report; mark uncertain items needs review.
• Domain entities: JSON content files, schema, validation report, import status.
• Component responsibilities: File selection; schema validation; import progress; validation report.
• States: Loading (validating/importing), empty (no files selected), success (content imported), error (schema validation failure or import failure), recovery (fix and re-import).

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance. Provenance is explicit (source-stated), basic_default (accepted default), or required_inference (indispensable inferred mechanics).

FR-1 — Learner self-service enrollment (required_inference) As a Japanese Learner (N5–N2), I should be able to create my own learner identity from Sign Up so that my durable learning state is bound to me.

• Trigger/input: Learner opens Sign Up from Landing and submits credentials.
• Observable result: A learner identity is created and the learner is routed to Onboarding.
• Access state: Anonymous entry; protected state is not yet created.
• Failure/recovery: Invalid or duplicate credentials show an error and allow correction and resubmission.
• Continuation: Onboarding.

FR-2 — Returning verification (required_inference) As a Japanese Learner (N5–N2), an AI Tutor Chat User (online), or a Content Maintainer / Importer, I should be able to verify my identity from Login so that I can resume my protected state.

• Trigger/input: User opens Login and submits credentials.
• Observable result: Identity is verified; learners route to Home, authorized maintainers route to Content Import.
• Access state: Anonymous entry; protected destinations remain unavailable until verification succeeds.
• Failure/recovery: Invalid credentials show an error and allow retry or navigation to Sign Up.
• Continuation: Home (learner) or Content Import (authorized maintainer).

FR-3 — Onboarding setup (explicit) As a Japanese Learner (N5–N2), I should be able to choose my interface language (English / Urdu / both), my daily goal (10 / 20 / 30 min), and my reminder time (default 9:00 PM, changeable) during Onboarding.

• Trigger/input: First use after Sign Up.
• Observable result: Preferences are persisted and the learner proceeds to Placement.
• Access state: Protected (learner identity established).
• Failure/recovery: Save failure shows an error and allows retry.
• Continuation: Placement.

FR-4 — Placement quiz (explicit) As a Japanese Learner (N5–N2), I should be able to take a placement quiz during Onboarding so that my starting level is determined.

• Trigger/input: Completion of Onboarding setup.
• Observable result: A starting level is assigned and the learner proceeds to Home.
• Access state: Protected.
• Failure/recovery: Incomplete submission allows resume or retake.
• Continuation: Home.

FR-5 — Kana charts and audio (explicit) As a Japanese Learner (N5–N2), I should be able to view hiragana and katakana charts and tap a kana to hear it on Kana.

• Trigger/input: Tap a kana character.
• Observable result: The kana is pronounced via expo-speech (ja-JP).
• Access state: Protected.
• Failure/recovery: If the Japanese TTS voice is missing, show how to install it.
• Continuation: Continue chart study or enter writing practice or a kana quiz.

FR-6 — Kana writing practice and quizzes (explicit) As a Japanese Learner (N5–N2), I should be able to do kana writing practice and take kana quizzes on Kana.

• Trigger/input: Enter writing practice or start a kana quiz.
• Observable result: Practice is recorded; quiz is scored.
• Access state: Protected.
• Failure/recovery: Canvas or quiz failure allows retry.
• Continuation: Return to Kana or proceed to the next study area.

FR-7 — Daily lesson arc (explicit) As a Japanese Learner (N5–N2), I should be able to complete a 30–40 minute Daily Lesson that reviews 10 old items, introduces 5 new words, 3 kanji, and 1 grammar point, then covers writing, listening, speaking, and a 10-question quiz.

• Trigger/input: Start or continue today's lesson from Home.
• Observable result: Each step is completed in order and the lesson completion state is recorded.
• Access state: Protected.
• Failure/recovery: A failed step can be retried; the lesson resumes from the last completed step.
• Continuation: Next step, then Home.

FR-8 — Kanji study (explicit) As a Japanese Learner (N5–N2), I should be able to study a kanji's meaning, on'yomi, kun'yomi, stroke count, animated stroke order, and example words on Kanji.

• Trigger/input: Select a kanji.
• Observable result: Kanji details and stroke-order animation are shown.
• Access state: Protected.
• Failure/recovery: Missing stroke data or canvas failure allows retry or skip to the next kanji.
• Continuation: Next kanji or return to Learn.

FR-9 — Trace-then-write-from-memory with stroke checking (explicit) As a Japanese Learner (N5–N2), I should be able to trace a kanji and then write it from memory on a canvas with stroke checking on Kanji.

• Trigger/input: Enter the trace-then-write exercise.
• Observable result: Stroke checking reports pass/fail.
• Access state: Protected.
• Failure/recovery: Failed stroke check allows retry; canvas failure allows retry.
• Continuation: Next kanji or return to Learn.

FR-10 — Writing practice (explicit) As a Japanese Learner (N5–N2), I should be able to do kanji tracing, typing practice with a romaji-to-kana keyboard, and sentence building by tapping word tiles on Writing.

• Trigger/input: Select an exercise type.
• Observable result: The exercise is completed and recorded.
• Access state: Protected.
• Failure/recovery: Canvas or input failure allows retry; clear and redo.
• Continuation: Next exercise or return to Learn.

FR-11 — Listening practice (explicit) As a Japanese Learner (N5–N2), I should be able to listen to TTS dialogues at normal and slow speed, complete dictation, answer 3 comprehension questions, and toggle show/hide text on Listening.

• Trigger/input: Play the dialogue; complete dictation; answer questions.
• Observable result: Dictation and comprehension answers are recorded.
• Access state: Protected.
• Failure/recovery: If the Japanese TTS voice is missing, show how to install it.
• Continuation: Next dialogue or return to Learn.

FR-12 — Speaking roleplay (explicit) As a Japanese Learner (N5–N2), I should be able to practice roleplay scenes (shop, station, restaurant, office, hospital) on Speaking, where the app speaks one side, I answer by voice, and the app shows what it heard next to the target sentence with a match score and tips.

• Trigger/input: Select a scene; respond by voice.
• Observable result: Recognized transcript, target sentence, match score, and tips are shown.
• Access state: Protected.
• Failure/recovery: If recognition fails, allow a type-instead option; if microphone permission is missing, show guidance.
• Continuation: Next turn or return to Learn.

FR-13 — Spaced repetition with SM-2 (explicit) As a Japanese Learner (N5–N2), I should be able to work through a daily review queue on Practice that uses the SM-2 algorithm, where wrong answers return sooner.

• Trigger/input: Open Practice; grade recall on each item.
• Observable result: SM-2 scheduling state is updated; the queue advances.
• Access state: Protected.
• Failure/recovery: SM-2 persistence failure allows retry; the queue is preserved.
• Continuation: Next item or return to Home.

FR-14 — Daily review queue badge on Home (explicit) As a Japanese Learner (N5–N2), I should see a daily review queue badge on Home so that I know how many items are due.

• Trigger/input: Open Home.
• Observable result: The badge shows the current due count.
• Access state: Protected.
• Failure/recovery: If the count cannot be read, show a neutral state and allow retry.
• Continuation: Open Practice.

FR-15 — Weekly review test (explicit) As a Japanese Learner (N5–N2), I should be able to take a weekly review test on Tests.

• Trigger/input: Start the weekly review test.
• Observable result: The test is scored and results are shown.
• Access state: Protected.
• Failure/recovery: Incomplete submission allows retake.
• Continuation: Review results or return to Home.

FR-16 — Level mock test and unlock (explicit) As a Japanese Learner (N5–N2), I should be able to take a full JLPT-style mock test at the end of each level (vocabulary and kanji, grammar, reading, listening) on Tests, with a pass mark of 80% to unlock the next level.

• Trigger/input: Start the level mock test.
• Observable result: The test is scored; at ≥80% the next level is unlocked.
• Access state: Protected.
• Failure/recovery: Below 80% allows retake; incomplete submission allows retake.
• Continuation: Next level or retake.

FR-17 — Progress tracking (explicit) As a Japanese Learner (N5–N2), I should be able to see my streak, words and kanji learned, accuracy by skill, weak-points list, and weekly charts on Progress.

• Trigger/input: Open Progress.
• Observable result: Metrics and charts are shown.
• Access state: Protected.
• Failure/recovery: Metrics read failure allows retry.
• Continuation: Open a weak point to practice it.

FR-18 — AI tutor chat (explicit) As an AI Tutor Chat User (online), I should be able to chat with the AI tutor on AI Tutor so that my sentences are corrected, mistakes are explained in English and Urdu, and conversations can be role-played.

• Trigger/input: Send a message; the app calls Claude through the user's own backend proxy.
• Observable result: Corrections, explanations, or roleplay responses are shown.
• Access state: Protected; requires network connectivity and the configured user-owned backend proxy; the provider API key remains server-side; the model name is a configuration value.
• Failure/recovery: If there is no internet or the proxy is unreachable, show a clear message that the AI tutor is unavailable while offline and allow retry when online.
• Continuation: Continue the conversation or return to Home.

FR-19 — Settings controls (explicit) As a Japanese Learner (N5–N2), I should be able to control show/hide furigana, romaji, English, Urdu; voice speed; dark mode; font size; reminder time; and export/import progress backup on Settings.

• Trigger/input: Change a setting; export or import a backup.
• Observable result: The setting is saved; the backup is exported or imported.
• Access state: Protected.
• Failure/recovery: Backup export/import failure shows an error and allows retry.
• Continuation: Continue using the app with the new setting.

FR-20 — Attribution (explicit) As a Japanese Learner (N5–N2) or Content Maintainer / Importer, I should be able to read open-dataset licenses and attribution on Attribution, reached from Settings.

• Trigger/input: Open Attribution from Settings.
• Observable result: Dataset names, licenses, and attribution text are shown.
• Access state: Protected.
• Failure/recovery: Content read failure allows retry.
• Continuation: Return to Settings.

FR-21 — Content import (required_inference) As a Content Maintainer / Importer, I should be able to validate and import N5–N2 level/unit JSON content into SQLite on Content Import, with access provisioned or authorized.

• Trigger/input: Select level/unit JSON files and start validation/import.
• Observable result: Valid content is imported; a validation report is shown; uncertain items are marked needs review.
• Access state: Protected; access is provisioned or authorized, not self-service.
• Failure/recovery: Schema validation failure or import failure shows a report and allows fix and re-import.
• Continuation: Import another level/unit or return to Home.

FR-22 — Four-line word stack (explicit) As a Japanese Learner (N5–N2), I should see every word, kanji, and sentence in four lines: Japanese with furigana, Romaji, English, and Urdu (RTL, natural everyday Urdu).

• Trigger/input: Any content presentation.
• Observable result: The four-line stack is rendered with a thin terracotta rule on the left edge marking it as one unit.
• Access state: Protected.
• Failure/recovery: Missing line data shows a neutral placeholder rather than inventing content.
• Continuation: Continue the current activity.

FR-23 — Level-appropriate content (explicit) As a Japanese Learner (N5–N2), I should only encounter kanji and grammar of my current level or lower.

• Trigger/input: Any content presentation.
• Observable result: Content respects the level constraint (N5 ~100 kanji / 800 words; N4 ~300 kanji / 1,500 words; N3 ~650 kanji / 3,700 words; N2 ~1,000 kanji / 6,000 words).
• Access state: Protected.
• Failure/recovery: Content that violates the constraint is flagged for review rather than shown.
• Continuation: Continue the current activity.

FR-24 — No invented readings or meanings (explicit) As a Content Maintainer / Importer, I should mark any uncertain reading or meaning as needs review instead of guessing.

• Trigger/input: Content validation.
• Observable result: Uncertain items are marked needs review.
• Access state: Protected.
• Failure/recovery: Unmarked uncertain items are flagged during validation.
• Continuation: Fix and re-import.

FR-25 — Error handling for offline, microphone, and TTS (explicit) As a Japanese Learner (N5–N2), I should see clear handling for no internet, no microphone permission, and a missing TTS voice (including how to install the Japanese voice).

• Trigger/input: The corresponding condition occurs.
• Observable result: A clear message and recovery guidance are shown.
• Access state: Protected.
• Failure/recovery: Recovery guidance is provided; retry is allowed.
• Continuation: Continue the current activity or the affected workflow.

FR-26 — Accessibility (explicit) As a Japanese Learner (N5–N2), I should have screen-reader labels and scalable text throughout the app.

• Trigger/input: Use of assistive technology or text scaling.
• Observable result: Labels are announced; text scales.
• Access state: Protected.
• Failure/recovery: n/a.
• Continuation: Continue the current activity.

FR-27 — Friendly progress feedback (explicit) As a Japanese Learner (N5–N2), I should receive friendly progress feedback with XP, streaks, level badges, and short encouragement in English and Urdu.

• Trigger/input: Completing learning activity.
• Observable result: XP, streak, level badge, and encouragement are shown.
• Access state: Protected.
• Failure/recovery: n/a.
• Continuation: Continue the current activity.

4. User Personas

Japanese Learner (N5–N2)

• Product context: A self-study adult learning Japanese from beginner to upper-intermediate level, using English and/or Urdu as the interface language, often on a mid-range Android phone, frequently at night. The learner works through a long-horizon journey from JLPT N5 to N2.
• Primary goal: Progress from JLPT N5 to N2 and unlock the next level by passing the 80% mock test.
• Distinct accepted responsibilities: Chooses interface language (English / Urdu / both), takes the placement quiz, sets a daily goal (10 / 20 / 30 min) and reminder time (default 9:00 PM, changeable); works through daily lessons, kana, kanji, writing, listening, and speaking practice; completes spaced-repetition reviews; takes weekly review tests and level mock tests; tracks streak, XP, accuracy, and weak points; configures display, voice speed, theme, font size, reminder time, and backup.
• Relevant inputs or decisions: Language choice, daily goal, reminder time, placement answers, review grading, exercise completion, test answers, settings changes.
• Interactions with other accepted participants: Interacts with the app's content and feedback; the AI tutor is a separate optional workflow used by the AI Tutor Chat User; the Content Maintainer / Importer supplies the content the learner studies.
• Observable success: A growing streak, words and kanji learned, accuracy by skill, a shrinking weak-points list, and a level badge that advances from N5 (sage) toward N2 (terracotta) after passing the 80% mock test.

AI Tutor Chat User (online)

• Product context: A learner using the optional online AI tutor chat to have sentences corrected, mistakes explained in English and Urdu, and to role-play conversations. This is a distinct workflow with its own online-only access condition and backend-proxy dependency, separate from offline lesson practice.
• Primary goal: Receive corrections, explanations in English and Urdu, and roleplay practice for Japanese sentences.
• Distinct accepted responsibilities: Sends messages, receives corrections and explanations, starts roleplays, switches explanation language, clears conversations.
• Relevant inputs or decisions: Message text, roleplay scene choice, explanation language choice.
• Interactions with other accepted participants: Depends on the user's own backend proxy, which holds the Claude API key server-side; the model name is a configuration value. The learner's offline study continues independently.
• Observable success: Corrections and explanations appear in the chosen language; roleplay responses continue the conversation; when offline or the proxy is unreachable, a clear unavailability message is shown and retry works when online.

Content Maintainer / Importer

• Product context: The person who imports level/unit JSON content (N5 first, then N4, with N3/N2 import-ready), respects dataset licenses, and marks uncertain readings or meanings as needs review rather than guessing. Access to Content Import is provisioned or authorized, not self-service.
• Primary goal: Load valid, schema-conformant content into SQLite with attribution intact.
• Distinct accepted responsibilities: Selects level/unit JSON files, validates against the schema, imports into SQLite, reviews the validation report, marks uncertain items needs review, and ensures attribution for JMdict, KANJIDIC2, KanjiVG, Tatoeba, and community level lists.
• Relevant inputs or decisions: JSON content files, schema, validation report, license information.
• Interactions with other accepted participants: Supplies the content the Japanese Learner studies; reads Attribution from Settings.
• Observable success: Valid content is imported; the validation report is clean or clearly flags issues; attribution is intact.

5. Core User Flows

Flow 1 — New learner enrollment and first setup (Japanese Learner)

1. The learner opens the app and lands on Landing, which explains Nihongo Path, its N5–N2 journey, and the four-line word-stack concept.
2. The learner taps the single terracotta primary CTA to begin.
3. On Sign Up, the learner creates a learner identity. On success, the learner is routed to Onboarding.
4. On Onboarding, the learner chooses interface language (English / Urdu / both), daily goal (10 / 20 / 30 min), and reminder time (default 9:00 PM, changeable), then saves.
5. On Placement, the learner completes the placement quiz and receives a starting-level result.
6. The learner is routed to Home, where the greeting headline, level badge, Today card, and review-queue badge are shown.
7. Failure/recovery: Invalid or duplicate credentials on Sign Up show an error and allow correction; a save failure on Onboarding allows retry; an incomplete placement submission allows resume or retake.
8. Continuation: The learner starts today's lesson from the Today card.

Flow 2 — Returning learner verification and resume (Japanese Learner)

1. The learner opens the app and lands on Landing.
2. The learner navigates to Login and submits credentials.
3. On success, the learner is routed to Home, where the durable state (streak, XP, review queue, lesson progress) is resumed.
4. Failure/recovery: Invalid credentials show an error and allow retry or navigation to Sign Up.
5. Continuation: The learner continues today's lesson or opens Practice.

Flow 3 — Daily lesson arc (Japanese Learner)

1. On Home, the learner sees the Today card containing the whole lesson arc as a vertical checklist and taps the single terracotta CTA.
2. On Daily Lesson, the learner works through the ordered arc: review 10 old items, 5 new words, 3 kanji, 1 grammar point, then writing, listening, speaking, and a 10-question quiz.
3. Each step shows the four-line word stack where applicable; the learner advances step by step.
4. Observable result: Each step's completion is recorded; the checklist's discrete level-coloured progress segments advance.
5. Failure/recovery: A failed step can be retried; the lesson resumes from the last completed step.
6. Continuation: After the 10-question quiz, the learner returns to Home with XP, streak, and encouragement shown.

Flow 4 — Kana study (Japanese Learner)

1. From Learn, the learner opens Kana.
2. The learner views the hiragana and katakana charts and taps a kana to hear it via expo-speech (ja-JP).
3. The learner enters writing practice and/or starts a kana quiz.
4. Observable result: Audio plays; practice is recorded; the quiz is scored.
5. Failure/recovery: If the Japanese TTS voice is missing, the app shows how to install it; canvas or quiz failure allows retry.
6. Continuation: The learner returns to Kana or proceeds to the next study area.

Flow 5 — Kanji study and stroke checking (Japanese Learner)

1. From Learn, the learner opens Kanji and selects a kanji.
2. The learner studies meaning, on'yomi, kun'yomi, stroke count, animated stroke order, and example words.
3. The learner plays the stroke-order animation (6px rounded slate-green strokes, current stroke terracotta, 120ms crossfade, replay scrubber).
4. The learner enters the trace-then-write-from-memory canvas and completes the exercise with stroke checking.
5. Observable result: Stroke checking reports pass/fail.
6. Failure/recovery: Missing stroke data or canvas failure allows retry or skip to the next kanji; a failed stroke check allows retry.
7. Continuation: The learner moves to the next kanji or returns to Learn.

Flow 6 — Writing practice (Japanese Learner)

1. From Learn, the learner opens Writing.
2. The learner selects kanji tracing, typing practice with a romaji-to-kana keyboard, or sentence building by tapping word tiles.
3. The learner completes the exercise.
4. Observable result: The exercise is completed and recorded.
5. Failure/recovery: Canvas or input failure allows retry; clear and redo.
6. Continuation: The learner moves to the next exercise or returns to Learn.

Flow 7 — Listening practice (Japanese Learner)

1. From Learn, the learner opens Listening.
2. The learner plays a TTS dialogue at normal or slow speed.
3. The learner completes dictation and answers 3 comprehension questions, using the toggle to show or hide text as needed.
4. Observable result: Dictation and comprehension answers are recorded.
5. Failure/recovery: If the Japanese TTS voice is missing, the app shows how to install it.
6. Continuation: The learner moves to the next dialogue or returns to Learn.

Flow 8 — Speaking roleplay (Japanese Learner)

1. From Learn, the learner opens Speaking and selects a roleplay scene (shop, station, restaurant, office, hospital).
2. The app speaks one side; the learner answers by voice.
3. The app shows what it heard next to the target sentence with a match score and tips.
4. Observable result: Recognized transcript, target sentence, match score, and tips are shown.
5. Failure/recovery: If recognition fails, the learner uses the type-instead option; if microphone permission is missing, the app shows guidance.
6. Continuation: The learner continues to the next turn or returns to Learn.

Flow 9 — Spaced-repetition review (Japanese Learner)

1. On Home, the learner sees the daily review-queue badge and opens Practice.
2. The learner works through the review queue; each item uses the SM-2 algorithm, and wrong answers return sooner.
3. Observable result: SM-2 scheduling state is updated; the queue advances.
4. Failure/recovery: SM-2 persistence failure allows retry; the queue is preserved.
5. Continuation: The learner finishes the queue or returns to Home.

Flow 10 — Weekly review test (Japanese Learner)

1. From Learn or Home, the learner opens Tests.
2. The learner starts the weekly review test.
3. Observable result: The test is scored and results are shown.
4. Failure/recovery: Incomplete submission allows retake.
5. Continuation: The learner reviews results or returns to Home.

Flow 11 — Level mock test and unlock (Japanese Learner)

1. On Tests, the learner starts the full JLPT-style mock test at the end of the level (vocabulary and kanji, grammar, reading, listening).
2. The learner completes all sections.
3. Observable result: The test is scored; at ≥80% the next level is unlocked.
4. Failure/recovery: Below 80% allows retake; incomplete submission allows retake.
5. Continuation: The learner proceeds to the next level or retakes the test.

Flow 12 — Progress review (Japanese Learner)

1. The learner opens Progress.
2. The learner sees streak, words and kanji learned, accuracy by skill, weak-points list, and weekly charts.
3. Observable result: Metrics and charts are shown with friendly encouragement in English and Urdu.
4. Failure/recovery: Metrics read failure allows retry.
5. Continuation: The learner opens a weak point to practice it.

Flow 13 — AI tutor chat (AI Tutor Chat User, online)

1. The learner opens AI Tutor (optional, online only).
2. The learner sends a message; the app calls Claude through the user's own backend proxy (the provider API key remains server-side; the model name is a configuration value).
3. Observable result: Corrections, explanations in English and Urdu, or roleplay responses are shown.
4. Failure/recovery: If there is no internet or the proxy is unreachable, the app shows a clear message that the AI tutor is unavailable while offline and allows retry when online.
5. Continuation: The learner continues the conversation or returns to Home; offline study continues independently.

Flow 14 — Settings and backup (Japanese Learner)

1. The learner opens Settings.
2. The learner changes show/hide furigana, romaji, English, Urdu; voice speed; dark mode; font size; reminder time; or exports/imports a progress backup.
3. Observable result: The setting is saved; the backup is exported or imported.
4. Failure/recovery: Backup export/import failure shows an error and allows retry.
5. Continuation: The learner continues using the app with the new setting, or opens Attribution to read dataset licenses.

Flow 15 — Content import (Content Maintainer / Importer)

1. The maintainer verifies identity on Login; authorized maintainers are routed to Content Import.
2. The maintainer selects level/unit JSON files and starts validation/import.
3. Observable result: Valid content is imported into SQLite; a validation report is shown; uncertain items are marked needs review.
4. Failure/recovery: Schema validation failure or import failure shows a report and allows fix and re-import.
5. Continuation: The maintainer imports another level/unit or returns to Home.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. The muse is Yves Béhar; the headline is "Humane technology for a language learner." The direction is a patient, encouraging, quietly intellectual study ritual — a well-made everyday object, not a hype product.

Color tokens

Light mode

• Background: #F7F4EE (warm oat-paper ground)
• Surface: #FFFDF9 (slightly brighter card surface — never pure white)
• Text: #23211D
• Primary: #2F3B3A (deep slate-green — structure, tab bar, primary actions)
• Accent: #C25E3A (terracotta — reserved for exactly three things: the daily streak number, the review-queue badge, and the one primary CTA per screen)
• Muted: #8A8578 (muted clay — romaji, furigana, secondary labels, hairline rules)
• Supporting tints: Sage #7C8F7A and Oat #E8E1D4 (level badges N5 sage → N2 terracotta; progress fills)
• Hairline border: #E4DCCE
• Shadow: 0 1px 2px rgba(35,33,29,0.05) (very soft, never a glow)

Dark mode

• Background: #1C1B18 (warm charcoal ground)
• Surface: #26241F
• Text: #F1ECE2
• Accent: #E07A52 (lifted terracotta for contrast)
• Contrast ratios for body text stay above 7:1 in both modes.

Typography

• Headings: Fraunces at 600–700 weight, optical size large, soft terminals and slight ink-trap warmth — used for app titles, level names, encouragement lines, and the streak number. Headlines run at 1.05 line-height and -0.01em tracking; set large and calm, never shouty.
• Japanese display: Noto Sans JP 700 for kanji and 500 for kana.
• Urdu: Noto Nastaliq Urdu at 1.9–2.1 line-height with at least 8px of vertical padding above and below every Urdu line so descenders and the nastaliq slope never clip.
• Body: Karla.
• Scale: 1.25 modular on a 4/8pt grid.
  • Mobile: 40 / 32 / 24 / 18 / 16 / 14 (display / H1 / H2 / body-lg / body / label)
  • Tablet 768px: 56 / 40 / 30 / 18 / 17 / 14
  • Desktop/web preview 1280px: 72 / 48 / 34 / 19 / 17 / 15
  • Japanese and Urdu lines take one step up: JP body 19px mobile; Urdu body 18px mobile with 1.9 line-height.
• Every size uses clamp() so nothing overflows at 375px.

Shape language

• Soft continuous curves, never pill-obsessive: 20px radius on cards, 14px on inputs and secondary buttons, 28px on the single hero card, 999px only for the primary CTA and the level badge.
• Surfaces are matte — one hairline border (#E4DCCE) plus a very soft 0 1px 2px rgba(35,33,29,0.05) shadow, never a glow.
• Progress bars are rounded capsules with a 1px inset track.
• Section dividers are 1px oat rules, not boxes.
• Tap targets are minimum 48×48 with 12px of breathing room.
• The bottom tab bar is a solid slate-green slab with icon + label, never floating glass.

Layout

• Single-column, thumb-first, one decision per screen.
• Persistent 5-tab bottom bar (Home, Learn, Practice, Progress, Settings) in solid #2F3B3A with the active tab marked by a terracotta 3px top rule rather than a colour swap, so it reads in RTL too.
• Home opens with a large greeting headline, then a single "Today" card containing the whole lesson arc as a vertical checklist.
• The 4-line word stack is the fundamental component: JP (19px, 500) / furigana above the kanji in muted clay / romaji (14px, muted) / English (16px) / Urdu (18px, Nastaliq, RTL, right-aligned in its own block).
• Learn and Practice use full-width stacked rows, not grids of cards.
• Progress uses one big number, one weekly bar chart, and a weak-points list — never a dashboard of equal tiles.
• RTL is handled per text block via I18nManager and writingDirection, so the app chrome stays LTR while Urdu lines flip cleanly.

Imagery

• No stock photography and no 3D renders. The visual content is the scripts themselves plus a small set of hand-made flat illustrations in the palette: a tea cup, a train window, a shop counter, a notebook — drawn at 2px stroke in slate-green with one terracotta fill, used as scene openers for roleplay and as empty states.
• Kanji stroke-order strokes are the app's most important imagery and are treated as illustration: 6px rounded slate-green strokes drawn progressively, with the current stroke in terracotta.
• Texture is limited to a very faint paper grain (2% opacity) on the background to keep the warmth.

7. Signature Design Concept

The Home screen is not a marketing hero — it is a daily ritual card. The signature concept is "the day's page": a warm oat ground holding one composed card that contains the entire day's work, with the Japanese and Urdu scripts as the heroes.

• Top 40% of the viewport: a warm oat ground with a large Fraunces greeting ("おはよう, Ayesha" / "Good evening, Ayesha" depending on time) at 40px mobile / 56px tablet, left-aligned, with the current date and level badge (N5, sage) sitting beneath it as a small caps label.
• Below, dominating the screen: one 28px-radius card in #FFFDF9 with a 1px oat border. Inside it, the day's four-line Japanese word of the day at full width (kanji 44px, furigana above in clay, romaji, English, Urdu block right-aligned), then a vertical checklist of today's lesson steps with a single terracotta CTA pinned to the bottom of the card.
• A terracotta review-queue badge floats at the card's top-right corner.
• The bottom tab bar is a solid slate-green slab with a 3px terracotta top rule on the active tab.
• Nothing is centred, nothing is a gradient blob, and the only accent on the whole screen is the badge and the one button.

The concept recomposes only accepted content, states, and controls: the greeting, date, level badge, word of the day, lesson checklist, review-queue badge, and the single primary CTA. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject: The four-line word stack as a first-class component — kanji with furigana stacked above it, then romaji, English, and an Urdu block right-aligned in Nastaliq, with a thin terracotta rule running down the left edge of the stack to mark it as one unit.
• Input → transformation → outcome thesis: As the learner arrives, the word stack composes itself line by line (JP → furigana → romaji → English → Urdu) with a 12px rise plus fade, staggered 40ms, capped at 6 items so low-end phones stay smooth; the outcome is a calm, complete four-line unit that reads as one object.
• Motion vocabulary: 220–320ms ease-out on entrances, 160ms on state changes, no bounce, no spring overshoot; one purposeful loop per screen at most.
• Composed first frame: Warm oat ground, the word stack fully composed, the single terracotta CTA, and the level badge — nothing centred, no gradient blob.
• Reduced-motion state: Wrapped in a reduced-motion guard that swaps to instant opacity changes and disables the breathing loops.

Signature moves carried through the app

• The 4-line word stack as a first-class component with a thin terracotta rule on the left edge.
• Bottom tab bar as a solid slate-green slab with a 3px terracotta top rule on the active tab, so the active state reads identically in LTR and RTL and never depends on colour alone.
• Progress bars and the daily ring drawn as oat tracks with a sage-to-terracotta fill that advances in discrete level-coloured segments, one per lesson step completed, so the bar is a map of the day's work rather than a percentage.
• Kanji stroke order animated as illustration: 6px rounded strokes drawn one at a time in slate-green with the current stroke in terracotta and a soft 120ms crossfade between strokes, with a replay scrubber beneath the canvas.
• A single breathing terracotta dot next to the streak number that pulses at 4s — the app's only ambient motion, used as a "you are on a run" signal rather than decoration.
• Flashcard flip is a real 3D Y-axis rotation at 320ms.
• The recording waveform pulses while listening.

9. Non-Functional Requirements

• Offline-first (explicit): SQLite holds all lessons, progress, and spaced-repetition data. The app must function without network connectivity for all core learning work. Rationale: the learner studies daily, often at night, on a mid-range Android phone.
• AI tutor online-only (explicit): The AI tutor is optional and online only; it must call Claude through the user's own small backend proxy. Rationale: the user owns the proxy and controls cost and access.
• No API key in the app (explicit): Never put an API key inside the app; the model name must be a config value. Rationale: security and configurability.
• Level-appropriate content (explicit): Each level uses only the kanji and grammar of that level or lower. Rationale: pedagogical correctness.
• No invented readings or meanings (explicit): Mark any uncertain item needs review instead of guessing. Rationale: accuracy and trust.
• License respect and attribution (explicit): Respect each dataset license and provide an Attribution screen in Settings. Rationale: legal compliance and credit.
• Content authoring order (explicit): Create real content for all of N5 first, then N4 as a second pass; N3 and N2 must be import-ready with the same schema. Rationale: staged delivery.
• Pass mark 80% (explicit): Pass mark 80% to unlock the next level. Rationale: level gating.
• Reminder default (explicit): Daily reminder default 9:00 PM, user can change it. Rationale: user control.
• Honest audio/speech claims (explicit): Never claim an audio or speech feature works if it was not tested; state what needs a real device test. Rationale: trust and quality.
• Phase discipline (explicit): Finish and test each phase before starting the next. Rationale: staged delivery.

• One codebase (explicit): One codebase for Android and iOS (React Native with Expo and TypeScript). Rationale: maintainability.
• Performance (explicit): Smooth but light animations; works well on low-end phones and small screens. Rationale: target device profile.
• Accessibility (explicit): Screen-reader labels and scalable text. Rationale: inclusive access.
• Error handling (explicit): Handle no internet, no microphone permission, and missing TTS voice (show how to install the Japanese voice). Rationale: graceful degradation.
• Unit tests (explicit): Add unit tests for the SM-2 logic, quiz scoring, and level unlock rules. Rationale: correctness of core algorithms.
• Code quality (explicit): Clean, typed, commented code with a clear folder structure (app, components, data, db, hooks, services, i18n, theme). Rationale: maintainability.
• Contrast (direction): Contrast ratios for body text stay above 7:1 in both light and dark modes. Rationale: readability for long study sessions.
• Readable text and controls (direction): Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Rationale: legibility across devices.

10. Tech Stack

• Framework: React Native with Expo and TypeScript — one codebase for Android and iOS. (explicit)
• Navigation: Expo Router, bottom tabs: Home, Learn, Practice, Progress, Settings. (explicit)
• Storage: SQLite for all lessons, progress, and spaced-repetition data (offline-first). (explicit)
• Text-to-speech: expo-speech with the ja-JP voice. (explicit)
• Speech recognition: expo-speech-recognition (ja-JP) for speaking practice. (explicit)
• Handwriting: react-native-skia canvas with stroke-order data from KanjiVG. (explicit)
• Notifications: expo-notifications (daily reminder, default 9:00 PM, user can change). (explicit)
• Fonts: Noto Nastaliq Urdu for Urdu; Noto Sans JP for Japanese; Fraunces for headings; Karla for body. Enable I18nManager RTL for Urdu text blocks. (explicit + direction)
• AI tutor backend: The user's own small backend proxy that calls Claude; the API key stays server-side; the model name is a configuration value. (explicit)
• Content data: JSON files by level and unit with fields id, level, jp, furigana, romaji, en, ur, audioText, tags. (explicit)
• Open datasets: JMdict, KANJIDIC2, KanjiVG, Tatoeba, and community level lists. (explicit)
• Build and release: EAS for Play Store / App Store build steps (final phase). (explicit)
• Folder structure: app, components, data, db, hooks, services, i18n, theme. (explicit)

11. Assumptions and Constraints

• Assumption: The learner has a device capable of running Expo/React Native and can install the Japanese TTS voice if it is missing. (required_inference)
• Assumption: The user owns and operates the small backend proxy for the AI tutor and configures the model name there. (explicit)
• Assumption: Content Maintainer / Importer access is provisioned or authorized separately; it is not self-service. (required_inference)
• Constraint: Offline-first — SQLite holds all lessons, progress, and spaced-repetition data. (explicit)
• Constraint: The AI tutor is optional and online only; it must call Claude through the user's own small backend proxy. (explicit)
• Constraint: Never put an API key inside the app; the model name must be a config value. (explicit)
• Constraint: Each level uses only the kanji and grammar of that level or lower. (explicit)
• Constraint: Do not invent readings or meanings; mark any uncertain item needs review instead of guessing. (explicit)
• Constraint: Respect each dataset license and provide an Attribution screen in Settings. (explicit)
• Constraint: Create real content for all of N5 first, then N4 as a second pass; N3 and N2 must be import-ready with the same schema. (explicit)
• Constraint: Pass mark 80% to unlock the next level. (explicit)
• Constraint: Daily reminder default 9:00 PM, user can change it. (explicit)
• Constraint: Never claim an audio or speech feature works if it was not tested; state what needs a real device test. (explicit)
• Constraint: Finish and test each phase before starting the next. (explicit)

• Constraint: One codebase for Android and iOS (React Native with Expo and TypeScript). (explicit)
• Constraint: Microphone permission and an installed Japanese TTS voice are required for the corresponding speaking and audio workflows. (required_inference)
• Constraint: SQLite initialization and content import must complete before durable lessons and review queues can be used. (required_inference)
• Default — not specified by user: Exact SQLite schema column names and migration strategy beyond the required fields; exact proxy implementation language and hosting; exact EAS build profile names.

12. Glossary

• JLPT: Japanese-Language Proficiency Test; levels N5 (beginner) through N2 (upper-intermediate) are covered by this app.
• N5 / N4 / N3 / N2: JLPT levels, each with approximate kanji and word targets (N5 ~100 kanji / 800 words; N4 ~300 kanji / 1,500 words; N3 ~650 kanji / 3,700 words; N2 ~1,000 kanji / 6,000 words).
• Kana: Hiragana and katakana syllabaries.
• Kanji: Japanese characters of Chinese origin.
• Furigana: Reading aid written above kanji.
• Romaji: Latin-script transliteration of Japanese.
• On'yomi / Kun'yomi: Sino-Japanese and native Japanese readings of a kanji.
• SM-2: A spaced-repetition scheduling algorithm; wrong answers return sooner.
• SRS: Spaced-repetition system.
• TTS: Text-to-speech (expo-speech, ja-JP voice).
• RTL: Right-to-left text direction, used for Urdu.
• Nastaliq: The Urdu calligraphic script style (Noto Nastaliq Urdu).
• Four-line word stack: The app's fundamental content component — Japanese with furigana, Romaji, English, Urdu (RTL).
• Review queue: The set of items due for spaced-repetition review, surfaced as a badge on Home.
• Mock test: A full JLPT-style test at the end of each level (vocabulary and kanji, grammar, reading, listening) with an 80% pass mark to unlock the next level.
• AI tutor: The optional, online-only chat that corrects sentences, explains mistakes in English and Urdu, and role-plays conversations, via the user's own backend proxy.

• Backend proxy: The user's own small server that calls Claude; holds the API key server-side; the model name is a configuration value.
• needs review: The marker applied to any uncertain reading or meaning instead of guessing.
• Attribution screen: The Settings destination listing open-dataset licenses (JMdict, KANJIDIC2, KanjiVG, Tatoeba, community level lists).
• Content Maintainer / Importer: The authorized person who validates and imports level/unit JSON content into SQLite.