Kanji Chain

Desktop app for discovering and studying kanji through chains of connected Japanese words.

Kanji Chain builds study sessions by selecting Japanese words that connect one kanji to another, creating a continuous path for vocabulary and kanji exploration.

Features

• Generates chains of connected kanji.
• Selects Japanese words containing the current kanji.
• Displays meanings, readings, furigana and kanji information.
• Supports daily, extra and review study sessions.
• Records study history, ratings and cooldown periods.
• Stores all user data locally in SQLite.
• Downloads dictionary data during the initial setup.
• Refreshes dictionary data automatically every 30 days.
• Preserves study history when dictionary entries are updated or removed.

How study selection works

Kanji Chain uses a heuristic scoring system to decide which kanji and words should receive more attention.

A lower numeric score means higher study priority.

Base word score

Each word receives a base score derived from JMdict metadata. The app gives lower priority to entries that are less useful for general study, such as:

• kana-only entries;
• uncommon writings or readings;
• writings containing numbers or Latin characters;
• obsolete, archaic, rare, dated or highly specialized senses;
• entries carrying tags that indicate irregular or unusual usage.

Common and broadly useful entries therefore tend to receive lower scores and appear earlier.

User history and cooldown

The base score is combined with the user's study history.

The current selection score includes:

• the number of times each kanji has been studied;
• the number of times each word has been studied;
• temporary cooldown penalties;
• the frequency ranking of the kanji;
• the combined score of the kanji contained in each word.

Ratings change the stored study count:

• terrible: decreases the count by 1, never below zero;
• bad: leaves the count unchanged;
• good: increases the count by 1;
• excellent: increases the count by 2.

Because lower scores have higher priority, a successful review increases the numeric score and makes that item less likely to be selected again immediately. A difficult item remains comparatively more likely to return.

Cooldowns add a much larger temporary penalty. Better-known items therefore leave the active study pool for longer periods, while difficult items return sooner.

Chain and variety rules

The score is not the only selection rule. Kanji Chain also:

• avoids selecting multiple variations from the same JMdict entry in one chain;
• temporarily penalizes repeated parts of speech to encourage vocabulary variety;
• prefers words that introduce a kanji not yet present in the current chain;
• favors common readings and writings when two candidates have the same score;
• uses shorter and simpler forms as additional tie-breakers.

The scoring system is a practical study heuristic rather than a formal spaced-repetition algorithm. Its purpose is to balance useful vocabulary, user difficulty, variety and chain continuity.

Technology

• Electron
• Node.js
• Express
• SQLite
• better-sqlite3
• Vanilla HTML, CSS and JavaScript

Running locally

Requirements:

• Node.js 22
• npm

Install the dependencies:

npm ci

Rebuild the native SQLite module for Electron:

npx electron-rebuild -f -w better-sqlite3

Start the application:

npm run electron

On the first launch, Kanji Chain downloads and imports its dictionary data. This process may take several minutes.

Dictionary updates

Kanji Chain stores the imported dictionary data in a local SQLite database.

Every 30 days, the application:

1. Creates a temporary copy of the current database.
2. Downloads the latest available dictionary files.
3. Updates kanji, words and furigana data.
4. Validates the updated database.
5. Replaces the original database only if the update succeeds.

Existing study sessions, ratings and user statistics are preserved.

Data sources

Kanji Chain uses data from:

• JMdict
• KANJIDIC2
• JmdictFurigana

See CREDITS.md for attribution and licence information.

Project status

Kanji Chain is a personal and academic project developed as part of a software development portfolio and undergraduate final project.

License

The Kanji Chain source code is licensed under the MIT License.

Dictionary data and third-party resources remain under their respective licences. See CREDITS.md.