# sureshnepal/dzo_learn architecture

> Architecture diagram of the GitHub repository sureshnepal/dzo_learn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sureshnepal/dzo_learn
- Repository: https://github.com/sureshnepal/dzo_learn

## Overview

#### Purpose and Runtime
Dzongkha Learn is a static, browser-only prototype for Level 1 Dzongkha alphabet practice. It runs directly from `index.html`, with Vue 3 and Tailwind CSS loaded from CDNs; there is no build pipeline, server application, authentication, or backend.

#### Entry and UI Composition
`index.html` is the browser entry point and hosts the Vue template, CDN dependencies, and script/style inclusion. The application UI and screen-level behavior are owned by `js/app.js`; supplemental visual behavior and animations reside in `styles/custom.css`.

#### Application Orchestrator
`js/app.js` creates the Vue application, coordinates onboarding/profile display, game-mode selection, question presentation, answer feedback, completion screens, and live XP rendering. It is the boundary between reactive UI state and the domain-oriented game/progress modules.

#### Game Session Engine
`js/gameLogic.js` defines the mechanics for the two modes: alphabet recognition and sound matching. It generates five-question sessions from alphabet data, produces four answer options, evaluates selections, tracks session state/score, and applies the configured XP-per-correct-answer rule. This module should remain independent of DOM/Vue rendering where possible.

#### Learning Content and Configuration
`data/alphabets.json` is the primary content catalog: character glyphs, transliterations, descriptions, difficulty, and referenced pronunciation audio paths. `data/lessons.json` supplies level/game metadata such as game IDs, question counts, and XP configuration. The runtime loads these static JSON resources, making content expansion primarily data-driven.

#### Progress Persistence Boundary
`js/userProgress.js` encapsulates profile and aggregate progress persistence through the browser Local Storage API. It stores the username, total XP, current level, completed sessions, games played, and last-played time under `dzongkha_learn_user_data`. This is the sole persistence mechanism and is local to a browser/device; clearing storage resets user state.

#### Primary Flow and External Dependencies
At startup, the browser loads `index.html`, external Vue/Tailwind CDN resources, local scripts, and JSON content. The user establishes or restores a local profile, selects a game mode, and starts a generated session. Each answer flows from Vue UI (`js/app.js`) to session evaluation (`js/gameLogic.js`); correct results increase XP and update persistent progress (`js/userProgress.js`), then UI state refreshes. Audio playback uses each alphabet’s `audioFile` reference from `data/alphabets.json`; referenced `assets/` files are not present in this repository tree, so audio is an optional/missing static-resource boundary.

Main entry points: [`js/app.js`](https://github.com/sureshnepal/dzo_learn/blob/master/js/app.js) (Vue app orchestrator), [`index.html`](https://github.com/sureshnepal/dzo_learn/blob/master/index.html) (index.html), [`js/gameLogic.js`](https://github.com/sureshnepal/dzo_learn/blob/master/js/gameLogic.js) (Game session engine), [`data/alphabets.json`](https://github.com/sureshnepal/dzo_learn/blob/master/data/alphabets.json) (Alphabet catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser Runtime"]
  node_index["index.html<br/>browser entry<br/>[index.html]"]
  node_vue["Vue 3 CDN<br/>external UI runtime"]
  node_tailwind["Tailwind CDN<br/>external CSS runtime"]
  node_localstorage[("Local Storage<br/>browser persistence")]
  node_user(("Learner<br/>browser user"))
end

subgraph group_app["Application"]
  node_appjs["Vue app orchestrator<br/>UI controller<br/>[app.js]"]
  node_game["Game session engine<br/>domain logic<br/>[gameLogic.js]"]
  node_progress["User progress store<br/>persistence adapter<br/>[userProgress.js]"]
  node_customcss["Custom styles<br/>stylesheet<br/>[custom.css]"]
end

subgraph group_content["Learning Content"]
  node_alphabets["Alphabet catalog<br/>static content<br/>[alphabets.json]"]
  node_lessons["Lesson configuration<br/>static content<br/>[lessons.json]"]
  node_audio["Pronunciation audio<br/>optional static resource"]
end

node_user -->|"opens"| node_index
node_index -->|"loads"| node_vue
node_index -->|"loads"| node_tailwind
node_index -->|"loads"| node_appjs
node_index -->|"loads"| node_customcss
node_appjs -->|"starts and evaluates sessions"| node_game
node_appjs -->|"restores and updates progress"| node_progress
node_progress -->|"reads and writes"| node_localstorage
node_game -->|"uses question content"| node_alphabets
node_game -->|"uses mode and XP rules"| node_lessons
node_appjs -->|"loads content"| node_alphabets
node_appjs -->|"loads configuration"| node_lessons
node_alphabets -.->|"references audioFile paths"| node_audio
node_appjs -->|"renders screens and feedback"| node_user

click node_index "https://github.com/sureshnepal/dzo_learn/blob/master/index.html"
click node_appjs "https://github.com/sureshnepal/dzo_learn/blob/master/js/app.js"
click node_game "https://github.com/sureshnepal/dzo_learn/blob/master/js/gameLogic.js"
click node_progress "https://github.com/sureshnepal/dzo_learn/blob/master/js/userProgress.js"
click node_customcss "https://github.com/sureshnepal/dzo_learn/blob/master/styles/custom.css"
click node_alphabets "https://github.com/sureshnepal/dzo_learn/blob/master/data/alphabets.json"
click node_lessons "https://github.com/sureshnepal/dzo_learn/blob/master/data/lessons.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_vue,node_tailwind,node_localstorage,node_user toneBlue
class node_appjs,node_game,node_progress,node_customcss toneAmber
class node_alphabets,node_lessons,node_audio toneMint
```

## Components

### Browser Runtime

- [index.html](https://github.com/sureshnepal/dzo_learn/blob/master/index.html): browser entry · Hosts the Vue template and local resource inclusion. · `index.html`
- **Vue 3 CDN**: external UI runtime
- **Tailwind CDN**: external CSS runtime
- **Local Storage**: browser persistence · Stores dzongkha_learn_user_data per browser/device.
- **Learner**: browser user

### Application

- [Vue app orchestrator](https://github.com/sureshnepal/dzo_learn/blob/master/js/app.js): UI controller · Coordinates screens, reactive state, and live XP. · `js/app.js`
- [Game session engine](https://github.com/sureshnepal/dzo_learn/blob/master/js/gameLogic.js): domain logic · Generates and evaluates five-question game sessions. · `js/gameLogic.js`
- [User progress store](https://github.com/sureshnepal/dzo_learn/blob/master/js/userProgress.js): persistence adapter · Encapsulates local profile and aggregate progress. · `js/userProgress.js`
- [Custom styles](https://github.com/sureshnepal/dzo_learn/blob/master/styles/custom.css): stylesheet · Provides supplemental visual behavior and animations. · `styles/custom.css`

### Learning Content

- [Alphabet catalog](https://github.com/sureshnepal/dzo_learn/blob/master/data/alphabets.json): static content · Characters, transliterations, difficulty, and audio references. · `data/alphabets.json`
- [Lesson configuration](https://github.com/sureshnepal/dzo_learn/blob/master/data/lessons.json): static content · Defines game metadata, question counts, and XP rules. · `data/lessons.json`
- **Pronunciation audio**: optional static resource · Referenced assets are absent from the repository.

## Connections

- Learner → index.html: opens
- index.html → Vue 3 CDN: loads
- index.html → Tailwind CDN: loads
- index.html → Vue app orchestrator: loads
- index.html → Custom styles: loads
- Vue app orchestrator → Game session engine: starts and evaluates sessions
- Vue app orchestrator → User progress store: restores and updates progress
- User progress store → Local Storage: reads and writes
- Game session engine → Alphabet catalog: uses question content
- Game session engine → Lesson configuration: uses mode and XP rules
- Vue app orchestrator → Alphabet catalog: loads content
- Vue app orchestrator → Lesson configuration: loads configuration
- Alphabet catalog → Pronunciation audio: references audioFile paths
- Vue app orchestrator → Learner: renders screens and feedback