# HLD — Overview, Context & Personas

> [Docs Home](../README.md) | [HLD HTML View](./index.html) | Next: [Architecture →](./architecture.md)

## System Context Diagram

```mermaid
flowchart LR
    Kid["Kid / Starter Learner - A0-A2 / N5"] -->|"Tactile Drag-Drop and Audio"| WebApp["LingoBright Browser Client"]
    Exam["Exam Candidate - IELTS / TOEIC / JLPT N5-N1"] -->|"Timed Drills and Band Estimator"| WebApp
    Educator["TESOL Trainee / Teacher / Parent"] -->|"Pedagogy Labs and Custom Packs"| WebApp
    CLI["Curriculum Author"] -->|"validate_packs + export_d1_sql + sync_worker_assets"| Packs["content/packs/lang/*.yaml"]
    Packs -->|"Local Seed"| SQLiteDB[("Local SQLite data/lingobright.db")]
    Packs -->|"Remote D1 Migration"| D1DB[("Cloudflare D1 lingobright-db")]
    WebApp -->|"Edge HTTPS language.outxet.dev"| Worker["Cloudflare Worker + Hono + Assets"]
    WebApp -->|"Local Dev 127.0.0.1:8000"| API["FastAPI + Jinja2 Backend"]
    API --> SQLiteDB
    Worker --> D1DB
    WebApp -->|"BCP-47 Fallback"| TTS["Browser Web Speech API"]
```

## Core Design Pillars

| Pillar | Strategy | Target Impact |
| :--- | :--- | :--- |
| **Kid-Style Tactile UI** | Pointer-Events drag-and-drop, 3D squishy tiles, **Breezy** owl mascot (`owl/fox/cat/panda`), Web Audio SFX | High engagement across ages & exam tiers |
| **Basic → Super Advanced** | Unified `CEFR A0–C2` + exam ladders (`IELTS`, `TOEIC`, `TESOL`, `JLPT N5–N1`) | Zero ceiling; grows with the learner |
| **All-Language Engine** | Universal `L1 -> L2` pairs, `<bdi>` RTL isolation, Furigana/Pinyin/IPA toggles, Unicode `NFC` | Works for Latin, CJK, Hangul, RTL, Abugida |
| **Dual Gameplay Modes** | `Playful Mode` (untimed, hints, Breezy mascot) ↔ `Exam Focus Mode` (timer, hidden crutches) | Same exercises serve kids & test-takers |
| **Dual-Runtime Single Source** | Local Python FastAPI (`run.py`) & 24/7 Edge Cloudflare Worker + D1 (`https://language.outxet.dev`) | Same YAML packs & ES6 UI on both local & cloud edge |

## User Personas Matrix

| Persona | Tracks Used | Key Features Needed |
| :--- | :--- | :--- |
| **Kid / Beginner** | `A0–A1`, `JLPT N5`, `Polish A1`, Phonics | Picture match, audio tiles, gentle retry, sticker album, guest start |
| **IELTS / TOEIC Candidate** | `IELTS 4.5–9.0`, `TOEIC 300–990` | Split-pane reading drag-drop, error surgery, multi-accent listening (`US/UK/AU`), Band estimator |
| **JLPT / Asian Lang Climber** | `JLPT N5 -> N1`, `HSK 1–9`, `TOPIK 1–6` | Furigana/Romaji toggle, Kanji radical cards, Keigo register sorting, `★` sentence ordering |
| **TESOL Trainee / Teacher** | `TESOL Mastery`, Studio | IPA explorer, PPP/ESA lesson sequencer, CCQ sorting, YAML/JSON pack studio |

## Changelog

| Version | Date | Summary of Changes |
| :--- | :--- | :--- |
| **v1.2.0** | 2026-11-22 | Updated System Context Diagram and pillars for Dual-Runtime deployment (`FastAPI + SQLite` local & `Cloudflare Worker + Hono + D1` at `https://language.outxet.dev`) + Polish (`pl`) track. |
| **v1.1.0** | 2026-11-15 | Renamed mascot in UI docs to **Breezy** (`owl`/`fox`/`cat`/`panda` avatars); aligned quick launch note to `run.py`. |
| **v1.0.0** | 2026-11-15 | Initial HLD overview, system context diagram, and learner persona matrix. |

