Skip to content

Update all documentation to reflect 960-day N5/N4/N3 curriculum #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alanfwilliams merged 2 commits into from
Feb 19, 2026
Merged

Update all documentation to reflect 960-day N5/N4/N3 curriculum #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8b6a00d
Update all documentation to reflect 960-day N5/N4/N3 curriculum
claude Feb 19, 2026
667280f
Rename N3-REQUIREMENTS.md to N3-N2-N1-REQUIREMENTS.md
claude Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 35 additions & 29 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,19 @@

## Project overview

A free, self-contained, zero-dependency interactive Japanese course from zero to JLPT N5 in 365 days.
A free, self-contained, zero-dependency interactive Japanese course from zero to JLPT N3 in 960 days (N5 + N4 + N3 complete; N2/N1 planned).
Everything runs in the browser with no build step and no installation required.

## Repository structure

```
jlpt-n5/
├── index.html # Application shell — React components + localStorage logic
├── curriculum.js # 365-day lesson data array + phase colour/name constants
├── curriculum.js # 960-day lesson data array + phase colour/name constants
├── lib.js # Pure utility functions: SM-2, card helpers, exercises
├── tests.html # QUnit browser test suite (open directly, no server)
├── README.md # User-facing documentation
├── N3-N2-N1-REQUIREMENTS.md # Implementation plan for N2/N1 (N3 complete)
└── .nojekyll # Disables Jekyll processing for GitHub Pages
```

Expand Down Expand Up @@ -56,7 +57,7 @@ the test suite reports failures.

### Running tests

**In the browser (full suite, 92 tests):**
**In the browser (full suite):**
```
open tests.html # macOS
xdg-open tests.html # Linux
Expand All @@ -67,7 +68,7 @@ xdg-open tests.html # Linux
node .claude/hooks/run-tests.js
```

### Test coverage — 12 modules
### Test coverage — 14 modules

| Module | What is tested |
|---|---|
Expand All @@ -82,37 +83,42 @@ node .claude/hooks/run-tests.js
| `srsReview` | Quality→grade mapping, EF clamp, no mutation, new object |
| `srsAddCards` | Embedded card data, no-overwrite, bool return value |
| `srsDueCards` | Returns objects not IDs, due/not-due filtering |
| **Curriculum integrity** | 365 sequential days, required fields, type validity, vocab/chars structure, phase/week ranges |

### Known failing tests (data bugs to fix)

The test suite currently flags 5 real data bugs in `curriculum.js`. These tests
will fail until the underlying data is corrected:

| Days | Bug |
|---|---|
| 85 | `type` field is an array instead of a string |
| 86–97 | `vocab` entries are 2-element `[jp, en]` instead of `[jp, reading, en]` |
| 253–308 | `vocab[1][2]` (meaning) is an empty string on kanji days |
| 173 | `chars[4]` is a 3-element array instead of the expected 2-element |
| 365 | `week = 53` (calendar weeks only go to 52) |
| **Curriculum integrity** | 960 sequential days, required fields, type validity, vocab/chars structure, phase/week ranges, N5/N4/N3 boundary checks |
| **Phase constants** | PHASE_COLORS, PHASE_BG, PHASE_NAMES defined and correct for all 20 active phases |
| **React render** | index.html inline script executes, App/DayView/Overview/ReviewMode render without error |

## Curriculum structure

| Days | Phase |
|-----------|----------------------------------------------------|
| 1–14 | Hiragana (46 characters) |
| 15–28 | Katakana (46 characters) |
| 29–84 | Foundations (numbers, particles, basic sentences) |
| 85–140 | Core N5 Vocabulary (~200 words) |
| 141–182 | Essential Verbs (て-form, ます-form, conjugation) |
| 183–252 | Grammar Patterns (particles, conditionals, keigo) |
| 253–308 | Kanji (~100 N5 kanji) |
| 309–365 | Review & JLPT Test Prep |
| Days | Phase | Name |
|-----------|-------|----------------------------------------------------|
| 1–14 | 1 | Hiragana (46 characters) |
| 15–28 | 2 | Katakana (46 characters) |
| 29–84 | 3 | Foundations (numbers, particles, basic sentences) |
| 85–140 | 4 | Vocabulary (~200 N5 words) |
| 141–182 | 5 | Verbs (て-form, ます-form, conjugation) |
| 183–252 | 6 | Grammar Patterns (particles, conditionals, keigo) |
| 253–308 | 7 | Kanji (~100 N5 kanji) |
| 309–365 | 8 | Test Prep (N5 review & JLPT prep) |
| 366–395 | 9 | N5 Review (bridge to N4) |
| 396–455 | 10 | N4 Vocabulary (~300 words) |
| 456–500 | 11 | N4 Verbs |
| 501–555 | 12 | N4 Grammar Patterns |
| 556–620 | 13 | N4 Kanji (~175 kanji) |
| 621–660 | 14 | N4 Test Prep |
| 661–690 | 15 | N4 Review (bridge to N3) |
| 691–770 | 16 | N3 Vocabulary (~1,500 words) |
| 771–820 | 17 | N3 Verbs & Adjectives |
| 821–895 | 18 | N3 Grammar Patterns (~120 patterns) |
| 896–930 | 19 | N3 Kanji (~170 kanji) |
| 931–960 | 20 | N3 Test Prep |

Phase constants for N2 (phases 21–26) and N1 (phases 27–32) are defined in
`curriculum.js` but lesson data for those levels has not yet been added.
See `N3-N2-N1-REQUIREMENTS.md` for the full N2/N1 implementation plan.

## Key implementation notes

- All 365 day definitions live in `curriculum.js` as a `curriculum` array
- All 960 day definitions live in `curriculum.js` — the first 365 as a JSON array literal, days 366–960 appended via `curriculum.push()` calls
- Two SM-2 implementations exist side-by-side: `sm2Update` (older, used by `ReviewView`) and `srsReview` (newer, used by `ReviewMode` + `App`). Both use `ease`/`ef` for the same concept.
- Quiz state, SRS card data, and completed-day flags are stored in `localStorage`
- The lesson view, overview calendar, and review flashcard deck are separate React components in `index.html`
Expand Down
57 changes: 31 additions & 26 deletions N3-REQUIREMENTS.md → N3-N2-N1-REQUIREMENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,21 @@
# JLPT N3 / N2 / N1 — Implementation Requirements

This document describes what needs to be built to extend the course from N4 (day 660) through JLPT N3, N2, and N1 readiness.
> **Status:** N3 is fully implemented (days 661–960, phases 15–20, all tests passing).
> This document now serves as the implementation plan for **N2 and N1** only.
> N3 sections are retained for reference.

This document describes what was built to extend the course through N3, and what remains to be built for N2 and N1 readiness.

---

## 1. Scope overview

| Level | New Vocabulary | New Kanji | New Grammar | New Days | Day Range |
|-------|---------------|-----------|-------------|----------|-----------|
| N3 | ~1,500 words | ~170 kanji | ~120 patterns | 300 | 661–960 |
| N2 | ~3,000 words | ~200 kanji | ~180 patterns | 360 | 961–1320 |
| N1 | ~4,000 words | ~300 kanji | ~220 patterns | 400 | 1321–1720 |
| **Total** | **~8,500 words** | **~670 kanji** | **~520 patterns** | **1,060** | **661–1720** |
| Level | New Vocabulary | New Kanji | New Grammar | New Days | Day Range | Status |
|-------|---------------|-----------|-------------|----------|-----------|--------|
| N3 | ~1,500 words | ~170 kanji | ~120 patterns | 300 | 661–960 | ✅ Complete |
| N2 | ~3,000 words | ~200 kanji | ~180 patterns | 360 | 961–1320 | Planned |
| N1 | ~4,000 words | ~300 kanji | ~220 patterns | 400 | 1321–1720 | Planned |
| **Total** | **~8,500 words** | **~670 kanji** | **~520 patterns** | **1,060** | **661–1720** | |

**Cumulative totals at each level (including N5+N4 base):**

Expand Down Expand Up @@ -786,30 +790,31 @@ To maintain consistency across all 1720 days:

## 25. File changes summary

| File | Changes |
|------|---------|
| `curriculum.js` | Add 1,060 new day objects (days 661–1720), add phases 15–32 to `PHASE_COLORS`, `PHASE_BG`, `PHASE_NAMES` |
| `lib.js` | Add 11 new exercise types to `buildExercises()`, increase exercise caps, add furigana helper |
| `index.html` | Passage rendering, furigana toggle, level selector/filter, reading exercise UI, per-level progress |
| `tests.html` | Update day count to 1720, add phase 15–32 range checks, new exercise type tests, passage validation |
| `CLAUDE.md` | Update curriculum structure table, test coverage table, phase listing, day count |
| File | Changes | Status |
|------|---------|--------|
| `curriculum.js` | N3 days 661–960, phases 15–20 ✅; still needs N2/N1 days 961–1720, phases 21–32 | N3 done |
| `lib.js` | Add 11 new exercise types to `buildExercises()`, increase exercise caps, add furigana helper | Planned |
| `index.html` | Passage rendering, furigana toggle, level selector/filter, reading exercise UI, per-level progress | Planned |
| `tests.html` | Update day count checks as levels are added, add phase range checks, new exercise type tests | Ongoing |
| `CLAUDE.md` | Updated with 960-day curriculum structure and current test coverage | ✅ Done |
| `README.md` | Updated with N5/N4/N3 curriculum overview | ✅ Done |

---

## 26. Implementation order

### Phase A — N3 (days 661–960)

1. Phase constants 15–20 in `curriculum.js`
2. N4 Review days (661–690)
3. N3 Vocabulary days (691–770)
4. N3 Verbs & Adjectives days (771–820)
5. N3 Grammar days (821–895)
6. N3 Kanji days (896–930)
7. Reading comprehension feature (`passage` field, `DayView`, `buildExercises`)
8. New exercise types: `reading`, `conjugation`, `pair_match`, `fill_blank`
9. N3 Test Prep days (931–960)
10. Tests for N3 content and features
### Phase A — N3 (days 661–960) ✅ Complete

1. ✅ Phase constants 15–20 in `curriculum.js`
2. ✅ N4 Review days (661–690)
3. ✅ N3 Vocabulary days (691–770)
4. ✅ N3 Verbs & Adjectives days (771–820)
5. ✅ N3 Grammar days (821–895)
6. ✅ N3 Kanji days (896–930)
7. N3 reading comprehension feature (`passage` field, `DayView`, `buildExercises`) — planned
8. New exercise types: `reading`, `conjugation`, `pair_match`, `fill_blank` — planned
9. ✅ N3 Test Prep days (931–960)
10. ✅ Tests for N3 curriculum data integrity

### Phase B — N2 (days 961–1320)

Expand Down
38 changes: 27 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 日本語 N5/N4 Course
# 日本語 N5–N3 Course

A free, self-contained interactive Japanese course from zero to JLPT N4 level.
A free, self-contained interactive Japanese course from zero to JLPT N3 level.
**No install. No account. Just open `index.html` in any browser.**

🔗 **Live:** [alanfwilliams.github.io/jlpt-n5](https://alanfwilliams.github.io/jlpt-n5)
Expand All @@ -11,7 +11,7 @@ A free, self-contained interactive Japanese course from zero to JLPT N4 level.

| Feature | Details |
|---|---|
| **N5 + N4 curriculum** | Complete N5 (365 days) + N4 content (30+ days and growing) |
| **N5 + N4 + N3 curriculum** | Complete N5 (365 days) + N4 (295 days) + N3 (300 days) — 960 days total |
| **Spaced repetition (SRS)** | SM-2 algorithm, same as Anki — cards scheduled automatically |
| **Text-to-speech** | Native browser Japanese voice on every vocab word |
| **Listening exercises** | Hear a word, pick the meaning |
Expand All @@ -33,7 +33,7 @@ A free, self-contained interactive Japanese course from zero to JLPT N4 level.
```bash
git init
git add index.html README.md
git commit -m "Initial commit: N5 365-day course"
git commit -m "Initial commit: N5/N4/N3 960-day course"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/jlpt-n5.git
git push -u origin main
Expand All @@ -45,20 +45,36 @@ Your site will be live at `https://YOUR_USERNAME.github.io/jlpt-n5` within a min

## Curriculum overview

### N5 Course (Days 1-365)
### N5 Course (Days 1–365)
- **Days 1–14** — Hiragana (all 46 characters)
- **Days 15–28** — Katakana (all 46 characters)
- **Days 29–84** — Foundations (numbers, particles, basic sentences)
- **Days 85–140** — Core N5 Vocabulary (~200 words)
- **Days 141–182** — Essential Verbs (て-form, ます-form, conjugation)
- **Days 183–252** — Grammar Patterns (particles, conditionals, keigo)
- **Days 253–308** — Kanji (all ~100 N5 kanji)
- **Days 309–365** — Review & JLPT Test Prep

### N4 Course (Days 366+, expanding)
- **Days 366–395** — N5 Review & Bridge Grammar (30 days)
- **Future content** — N4 Vocabulary, Verbs, Grammar, Kanji, Test Prep (~500+ more days)
- 🚧 **N4 curriculum is currently being developed** — contributions welcome!
- **Days 309–365** — Review & JLPT N5 Test Prep

### N4 Course (Days 366–660)
- **Days 366–395** — N5 Review & Bridge Grammar (30 days)
- **Days 396–455** — N4 Vocabulary (~300 words)
- **Days 456–500** — N4 Verbs (て-form extensions, potential, passive, causative)
- **Days 501–555** — N4 Grammar Patterns
- **Days 556–620** — N4 Kanji (~175 kanji)
- **Days 621–660** — Review & JLPT N4 Test Prep

### N3 Course (Days 661–960)
- **Days 661–690** — N4 Review & Bridge to N3 (30 days)
- **Days 691–770** — N3 Vocabulary (~1,500 words)
- **Days 771–820** — N3 Verbs & Adjectives (transitive/intransitive, compound verbs, conjugation forms)
- **Days 821–895** — N3 Grammar Patterns (~120 patterns)
- **Days 896–930** — N3 Kanji (~170 kanji)
- **Days 931–960** — Review & JLPT N3 Test Prep

### Future content (Days 961+)
- **N2** — ~360 days (vocabulary, verbs, grammar, kanji, test prep)
- **N1** — ~400 days (vocabulary, verbs, grammar, kanji, test prep)
- See [N3-N2-N1-REQUIREMENTS.md](N3-N2-N1-REQUIREMENTS.md) for the full implementation plan

## Browser compatibility

Expand Down