JLPTSuccess

A multi-level JLPT (Japanese-Language Proficiency Test) study app covering N5 → N1.

No login · No tracking · Works offline · Open source · 100% on-device · Free, no ads, no paywall.

Live site: gauravaccentureproducts.github.io/JLPTSuccess/

Architecture

Each level lives as a self-contained sub-app under its own subdirectory and URL path:

Level	Path	Status
N5 (Beginner)	/N5/	Live — actively maintained (current version in N5/CHANGELOG.md)
N4 (Elementary)	/N4/	Paused (migrated state preserved; legacy URL still serves; no further development)
N3 (Intermediate)	/N3/	Coming soon
N2 (Upper-intermediate)	/N2/	Coming soon
N1 (Advanced)	/N1/	Coming soon

The top-level page (this repo's index.html) is the level picker. Each level's app shell, data, audio, SVGs, build pipeline, and tests live under that level's subdirectory.

N5 surface highlights

• Content: a full N5 corpus — grammar patterns, vocab, kanji, reading passages, listening drills — plus a mock-test question bank and full-mock papers (85 Q × 105 min) matching real JLPT N5 shape. (Corpus sizes are derived facts that drift as content grows; see N5/data/version.json counts for the live figures rather than a hardcoded snapshot.)
• Hindi (niche-N1): 100 % meaning_hi / gloss_hi / meanings_hi / summary_hi / explanation_hi / l1_notes.hi across all surfaces, native_reviewed at LLM-persona Q33 quality bar.
• Audio: multi-voice VOICEVOX-rendered listening (4 distinct speakers, JLPT-N5-paced); gtts-synthesized grammar/reading examples; per-example audio player with speed controls + transcript-aligned timestamped lines.
• PWA: installable, offline-first, FSRS-4.5 SRS unified across grammar + vocab + kanji.
• Privacy: no login, no tracking, no third-party scripts, all state in localStorage namespaced jlpt-n5-tutor:*. CSP same-origin. Verified by the CI content-integrity invariant suite + 8 design-system rules.

Running locally

The whole site is static HTML / CSS / JS - no JS bundler, no runtime build, no framework. Content is pre-generated by Python scripts under each level's tools/ directory at authoring time; the rendered JSON, audio MP3s, and SVGs are committed to the repo and served as-is by GitHub Pages.

python -m http.server 8000
# Visit http://localhost:8000/JLPTSuccess/  (or  http://localhost:8000/  if served from inside the repo)

To work on a specific level:

cd N5    # or N4, etc.
python -m http.server 8000
# Visit http://localhost:8000/

Each level's tests + builders are local to that level:

cd N5
python tools/check_content_integrity.py
npx playwright test

Per-level isolation

• localStorage namespacing: N5 uses keys prefixed jlpt-n5-tutor:, N4 uses jlpt-n4-tutor: (verifiable in N5/js/storage.js). Per-level progress doesn't bleed across.
• Service worker scope: each level's SW is scoped to its own subdirectory, so cache and offline behavior are independent.
• Build pipelines: each level has its own tools/ and KnowledgeBank/. There is no shared build infrastructure - clones the N5 → N4 patterns at scaffolding time, then evolves independently.

Migration history

This monorepo was created on 2026-05-04, consolidating the previously separate repos:

• gauravaccentureproducts/jlpt-n5-tutor (kept as pre-migration backup, tag pre-migration-2026-05-04)
• gauravaccentureproducts/jlpt-n4-tutor (kept as pre-migration backup, tag v0.2.1-pre-migration)

The old deploys at …github.io/jlpt-n5-tutor/ and …github.io/jlpt-n4-tutor/ remain alive for the time being but will not receive further updates.

Adding a new level (N3 → N1)

When content is ready for an additional level:

1. Create the level subdirectory by cloning the N4 scaffold:

   cp -r N4 N3

2. Token-substitute n4 → n3, JLPT N4 → JLPT N3, jlpt-n4-tutor → jlpt-n3-tutor (or update to JLPTSuccess refs).
3. Wipe content (data/*.json, KnowledgeBank/*.md) to skeleton state.
4. Author the level-specific kanji + vocab + grammar inventories.
5. Run the build pipeline: python tools/build_n3_kanji.py, etc.
6. Update the top-level index.html to flip the N3 card from is-disabled to is-available with href="N3/".

License

Source code: MIT (see LICENSE once added). Content: see each level's CONTENT-LICENSE.md for level-specific notes; KanjiVG attribution in each level's NOTICES.md.