# silent9669/jlpt_n5 architecture

> Architecture diagram of the GitHub repository silent9669/jlpt_n5, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/silent9669/jlpt_n5
- Repository: https://github.com/silent9669/jlpt_n5

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development Tools
    subgraph "Development (Dev-time)" 
        direction TB
        PythonServer["Python HTTP Server"]:::tool
        NpmScripts["npm scripts"]:::tool
        ChartsScript["Data Preprocessing Scripts"]:::tool
    end

    %% CI/CD
    subgraph "Deployment & CI/CD"
        direction TB
        GitRepo["Git Repository"]:::tool
        GitHubPages["GitHub Pages"]:::tool
    end

    %% Runtime Environment
    subgraph "Runtime (Run-time)"
        direction TB
        Browser["Browser (Client)"]:::client
        subgraph "Frontend Assets"
            direction TB
            HTML["index.html"]:::client
            CSS["styles.css"]:::client
            JS["app.js"]:::client
            subgraph "SPA Modules"
                direction TB
                Dashboard["Dashboard Module"]:::client
                DailyStudy["Daily Study Module"]:::client
                VocabBrowser["Vocabulary Browser Module"]:::client
                KanjiLearn["Kanji Learning Module"]:::client
                GrammarDB["Grammar Database Module"]:::client
                QuizEngine["Interactive Quiz Engine"]:::client
                PracticeTests["Practice Tests Module"]:::client
            end
        end
        subgraph "Static Data API"
            direction TB
            JSONStore["JSON Data Store"]:::data
        end
        Hosting["Static Hosting"]:::host
    end

    %% Relationships
    PythonServer -->|serves assets locally| HTML
    NpmScripts -->|build/preprocess| HTML
    NpmScripts -->|build/preprocess| CSS
    NpmScripts -->|build/preprocess| JS
    ChartsScript -->|generate charts/data| JS

    GitRepo -->|push via CI/CD| GitHubPages
    GitHubPages -->|serves HTML, CSS, JS| Browser

    Browser -->|loads index.html| HTML
    Browser -->|loads styles.css| CSS
    Browser -->|loads app.js| JS
    JS -->|initializes modules| Dashboard
    JS -->|initializes modules| DailyStudy
    JS -->|initializes modules| VocabBrowser
    JS -->|initializes modules| KanjiLearn
    JS -->|initializes modules| GrammarDB
    JS -->|initializes modules| QuizEngine
    JS -->|initializes modules| PracticeTests

    Browser -->|HTTP GET JSON| JSONStore
    Dashboard -->|HTTP GET JSON| JSONStore
    DailyStudy -->|HTTP GET JSON| JSONStore
    VocabBrowser -->|HTTP GET JSON| JSONStore
    KanjiLearn -->|HTTP GET JSON| JSONStore
    GrammarDB -->|HTTP GET JSON| JSONStore
    QuizEngine -->|HTTP GET JSON| JSONStore
    PracticeTests -->|HTTP GET JSON| JSONStore

    %% Click Events
    click HTML "https://github.com/silent9669/jlpt_n5/blob/main/index.html"
    click CSS "https://github.com/silent9669/jlpt_n5/blob/main/styles.css"
    click JS "https://github.com/silent9669/jlpt_n5/blob/main/app.js"
    click ChartsScript "https://github.com/silent9669/jlpt_n5/blob/main/scripts/chart_script.py"
    click NpmScripts "https://github.com/silent9669/jlpt_n5/blob/main/package.json"
    click JSONStore "https://github.com/silent9669/jlpt_n5/tree/main/data/"
    click DailyStudy "https://github.com/silent9669/jlpt_n5/tree/main/data/daily/"
    click VocabBrowser "https://github.com/silent9669/jlpt_n5/tree/main/data/vocabulary/"
    click GrammarDB "https://github.com/silent9669/jlpt_n5/tree/main/data/grammar/"
    click QuizEngine "https://github.com/silent9669/jlpt_n5/tree/main/data/tests/"

    %% Styles
    classDef client fill:#CFE2F3,stroke:#6FA8DC,color:#0B5394;
    classDef data fill:#D9EAD3,stroke:#93C47D,color:#38761D;
    classDef tool fill:#E7E6E6,stroke:#A6A6A6,color:#666666;
    classDef host fill:#FCE5CD,stroke:#F9CB9C,color:#B45F06
```
