How silent9669/jlpt_n5 works
Project Type & Purpose
• This is a pure client-side, static web application (“JLPT N5 Study App”) whose goal is to help users prepare for the JLPT N5 exam via a 36-day study plan, vocabulary/kanji/grammar databases, interactive quizzes, and practice tests.
• There is no true “backend service”; all data lives in JSON files under the data/ directory, and the app is hosted on a static file server (GitHub Pages or a simple Python HTTP server).
Key Architectural Components
A. Frontend Client (Single-Page Application)
• index.html: shell of the application
• styles.css: presentation layer
• app.js: application logic, routing between features, DOM manipulation, data fetching & state management
• JSON Data Fetcher: modules within app.js that load JSON via fetch() calls
• Sub-modules inside app.js for:
• Dashboard (animated counters)
• Daily Study (36 days of lessons)
• Vocabulary Browser (search, filter, infinite scroll)
• Kanji Learning (stroke order, examples)
• Grammar Database (filter by level/category, search)
• Interactive Quiz Engine (question generation, timer, review)
• Practice Tests (full-length test runner + results view)
B. Data Layer (Static JSON Files)
• data/daily/*.json: 36 day-by-day lesson definitions
• data/vocabulary/*.json: N5/N4 vocabulary, kanji databases
• data/grammar/*.json: grammar points database
• data/tests/*.json: 10 full practice test definitions
C. Development & Deployment Tools
• Python HTTP server (for local dev) or npm start (if customized in package.json)
• GitHub Pages (static hosting)
• scripts/*.py: offline utility scripts (e.g., chart_script.py) to preprocess data or generate charts
D. Hosting/Infrastructure
• Static file host (GitHub Pages CDN or any S3/Netlify)
• Browser as the runtime environment
• Optional: CI step (push to main → GitHub Pages deploy)
Relationships & Data Flow
• Browser loads index.html → CSS/JS assets downloaded
• app.js initializes UI router → fetches JSON files on demand
• JSON data → in-memory model → rendered into DOM components
• User interactions (click, search, quiz answers) → controller logic in app.js → update view + track progress
• Data never mutates on disk; all “state” is ephemeral in browser/sessionStorage if implemented
Architectural Patterns & Principles
• Single-Page Application (SPA) with modular JS controllers
• Model-View-Controller (MVC) or Model-View-ViewModel (MVVM) style separation within app.js
• Data-as-Static-Resources: JSON files treated as read-only “API” endpoints
• Progressive enhancement & responsive design (mobile-friendly)
• Offline capability: all assets and data live client-side once loaded