🦉 LingoBright Docs

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"]
        
PersonaTracksCore Needs
Kid / BeginnerA0–A1, JLPT N5, PhonicsPicture match, audio tiles, gentle retry, stickers, 15s guest start
IELTS / TOEIC CandidateIELTS 4.5–9.0, TOEIC 300–990Split reading drag-drop, error surgery, multi-accent listening (US/UK/AU), Band estimator
JLPT / Asian Lang ClimberJLPT N5 → N1, HSK, TOPIKFurigana/Pinyin toggle, Kanji radical cards, Keigo register sorting, ★ clause builder
TESOL Trainee / TeacherTESOL Mastery, Pack StudioIPA 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

VersionDateSummary of Changes
v1.2.02026-11-22Updated 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.02026-11-15Synchronized FSM drag threshold (6px), elementsFromPoint hit-testing, Breezy mascot name, and PBKDF2 auth scheme with built modules.
v1.0.02026-11-15Initial HLD visual portal.