01 · High-Level Design (HLD)
Playful kid-style drag-and-drop gameplay powering Basic (A0/N5) to Super-Advanced (C2/N1) & IELTS, TOEIC, TESOL, JLPT tracks.
System Context & Personas
Open overview.md
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 -->|"Seed Local"| DB[("SQLite DB")]
Packs -->|"Remote D1 Migration"| D1[("Cloudflare D1 lingobright-db")]
WebApp -->|"language.outxet.dev"| Worker["Cloudflare Worker + Hono + Assets"]
WebApp -->|"Local 127.0.0.1:8000"| API["FastAPI Backend"]
API --> DB
Worker --> D1
WebApp -->|"BCP-47 Fallback"| TTS["Browser Web Speech API"]
| Persona | Tracks | Core Needs |
|---|---|---|
| Kid / Beginner | A0–A1, JLPT N5, Phonics | Picture match, audio tiles, gentle retry, stickers, 15s guest start |
| IELTS / TOEIC Candidate | IELTS 4.5–9.0, TOEIC 300–990 | Split reading drag-drop, error surgery, multi-accent listening (US/UK/AU), Band estimator |
| JLPT / Asian Lang Climber | JLPT N5 → N1, HSK, TOPIK | Furigana/Pinyin toggle, Kanji radical cards, Keigo register sorting, ★ clause builder |
| TESOL Trainee / Teacher | TESOL Mastery, Pack Studio | IPA explorer, PPP/ESA lesson sequencer, CCQ sorting, YAML/JSON import/export |
Component Architecture (Overview → Details)
Open architecture.md
flowchart LR
Browser["Browser Client - Shared ES6+ + DragDropBoard"] -->|"https://language.outxet.dev"| Worker["Cloudflare Worker + Hono + Assets"]
Browser -->|"Local Dev"| API["FastAPI API and Jinja2"]
Worker --> D1[("Cloudflare D1 lingobright-db")]
API --> DB[("SQLite + YAML + Audio")]
Detail A · Browser Modules
flowchart TD
Shell["Bright UI Shell + Mode Switcher"] --> Renderers["11 Exercise Renderers"]
Renderers --> DND["Pointer-Event DragDropBoard"]
Renderers --> AudioUI["Multi-Accent Speech + SFX"]
Renderers --> Drawer["Band / Nx Breakdown Drawer"]
Detail B · Backend Engines
flowchart LR
API["FastAPI Routers"] --> Auth["Auth and Guest"]
API --> Curr["Course Filter"]
API --> Place["Placement"]
API --> Grader["11-Type Grader"]
API --> PackSvc["Pack Service"]
Grader --> SRS["SM-2 SRS"]
Grader --> Est["Band/Nx Estimator"]
Learner Journey, Drag-Drop FSM & Grading Sequence
Open flows.md
flowchart LR
Start["Guest Start - 15s"] --> Choice{"Experience?"}
Choice -->|"New / Guided"| Map["Tiered Island Map - A0 / N5"]
Choice -->|"Skip Ahead"| Place["2-Min Placement Sprint"]
Choice -->|"Free Browse"| Open["Open Mastery Access - N1 / Band 9 / TESOL"]
Place --> Map
Open --> Map
Map --> Mode{"Gameplay Mode"}
Mode -->|"Playful"| Play["Untimed + Hints + Mascot"]
Mode -->|"Exam Focus"| Exam["Pacing Timer + Strict Script"]
Play --> Drill["11-Type Drag-Drop Session"]
Exam --> Drill
Drill --> Breakdown["Linguistic / Band Breakdown Drawer"]
Breakdown --> Rewards["XP + Stars + SRS + Exam Estimator"]
stateDiagram-v2
[*] --> IDLE
IDLE --> POINTER_DOWN : pointerdown / touch / mouse
IDLE --> TAP_SELECTED : quick tap - accessibility
POINTER_DOWN --> DRAGGING : distance >= 6px - create floating ghost
DRAGGING --> HOVER_TARGET : elementsFromPoint hits DropZone
HOVER_TARGET --> DRAGGING : leaves DropZone
HOVER_TARGET --> SNAPPED_SLOT : pointerup inside DropZone
DRAGGING --> RETURN_SPRING : pointerup outside DropZone
TAP_SELECTED --> SNAPPED_SLOT : tap destination DropZone
SNAPPED_SLOT --> IDLE : snap SFX + update readiness
RETURN_SPRING --> IDLE : cleanup ghost and restore tray
Changelog
| Version | Date | Summary of Changes |
|---|---|---|
| v1.2.0 | 2026-11-22 | Updated HLD Context & Architecture diagrams to show live Dual-Runtime topology: Cloudflare Worker + D1 (https://language.outxet.dev) and local FastAPI + SQLite sharing one pack & frontend source. |
| v1.1.0 | 2026-11-15 | Synchronized FSM drag threshold (6px), elementsFromPoint hit-testing, Breezy mascot name, and PBKDF2 auth scheme with built modules. |
| v1.0.0 | 2026-11-15 | Initial HLD visual portal. |