Features
Profiles & Navigation
The application revolves around four main views accessible through a fixed sidebar: Profile Selection, Articles, Flashcards, and Progress. User profiles act as the authentication layer — without a selected profile, access to the core functionality is blocked, and the login state is persisted across sessions.
Article Reader
Reading is centered on Chinese stories organized by HSK level and category, such as daily life, family, shopping, and food. The article reader segments Chinese text using Jieba and displays it with interactive, clickable words. Tapping a word fetches its translation via Google Translate and shows pinyin, part-of-speech, and multiple translation options. Users can save words to their vocabulary with context, translate whole paragraphs, and toggle pinyin visibility per paragraph. Text-to-speech playback is available through Google TTS for both individual words and full paragraphs. The reader remembers scroll position so users can resume exactly where they left off.
Flashcards & Spaced Repetition
Saved words feed into a flashcard system powered by the SM-2 spaced repetition algorithm. Reviews can be filtered to only due words or include all vocabulary, and three review modes are supported: recognition (seeing the character and recalling the meaning), production (seeing the translation and recalling the character), and audio (hearing the word and recalling meaning or character). Flashcards track ease factor, interval, repetition count, and next review date to schedule reviews according to the algorithm.
Progress & Skill Progression
Progress is tracked through vocabulary size, well-known words, articles read, average reviews per word, and streaks. A skill progression system defines five levels from Beginner to Advanced, with eligibility based on vocabulary count, well-known words, articles read, review quality, and streak length. When users meet the criteria for the next level, a level-up modal celebrates their progress.
Achievements & Localization
Achievements such as first 10 words, vocabulary builder, quick learner, and week warrior provide additional motivation. The interface is localized and supports multiple languages for the UI, with translation targets configurable per profile. The app checks internet connectivity and shows a warning when offline, since translation and TTS depend on network access.
Technical Stack
Application Architecture
The application is an Electron app with a clear split between main process and renderer. The main process runs Node.js and handles file system access, IPC, and CPU-heavy or native operations. The renderer is a single-page React application bundled with Webpack, using Babel for JSX transpilation and PostCSS with Tailwind CSS for styling.
Frontend
React 19 is used for the UI layer, with Lucide React for icons. State is managed through React Context for app-wide data such as saved words, profiles, and language settings. Custom hooks like useStorage and useLevelUpManager encapsulate persistence and level-up logic.
Main Process Services
The main process uses several services: ChineseProcessor relies on @node-rs/jieba for Chinese text segmentation and the pinyin package for romanization. TranslationService calls the public Google Translate API over HTTP with Axios, with a cache layer to reduce repeated requests. StoryService serves HSK-level Chinese stories from a bundled JSON collection. DataService writes and reads JSON files in the Electron user data directory for profiles, saved words, and app state. CacheService provides configurable in-memory caches with TTLs for translation, articles, and RSS data. StatsService and SkillProgressionService compute vocabulary metrics, streaks, achievements, and level-up eligibility from saved words and read articles.
IPC & Security
Communication between renderer and main process uses IPC via a preload script that exposes a contextBridge API. The preload script defines explicit method signatures, and the main process registers corresponding handlers for data, stories, translation, Chinese processing, stats, and skill progression. Context isolation and disabled nodeIntegration ensure that the renderer cannot directly access Node.js or the main process.