# HLD — Runtime Flows & State Machines

> [← Architecture](./architecture.md) | [HLD HTML View](./index.html) | Next: [FRS →](../02-frs/tracks-and-modes.md)

## 1. End-to-End Learning Flow

```mermaid
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"]
```

## 2. Drag-and-Drop Pointer Engine State Machine (`drag_engine.js`)

```mermaid
stateDiagram-v2
    [*] --> IDLE
    IDLE --> POINTER_DOWN : pointerdown / touch / mouse
    IDLE --> TAP_SELECTED : quick tap or Enter/Space (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 : play snap SFX + update readiness
    RETURN_SPRING --> IDLE : cleanup ghost + restore opacity
```

## 3. Exercise Submission & Exam Grading Sequence

```mermaid
sequenceDiagram
    actor Learner
    participant UI as Renderer + DragDropBoard
    participant Audio as Audio & SFX Engine
    participant API as FastAPI /api/v1
    participant Grader as 11-Type Grader
    participant Est as SRS + Band/Nx Estimator

    Learner->>UI: Picks up & drops tile into target slot
    UI->>Audio: Play tactile snap SFX + speak tile
    Learner->>UI: Submits answer
    UI->>API: POST /api/v1/exercises/{id}/attempt
    API->>Grader: Normalize Unicode NFC + evaluate payload
    Grader->>Est: Update WordMasterySRS + SkillEstimate + XP
    Est-->>API: {is_correct, score_ratio, feedback_type, item_feedback, evidence_quotes, explanation}
    API-->>UI: AttemptResultResponse JSON
    alt Correct
        UI->>Audio: Play chime + celebratory confetti on 3+ combo
        UI->>Learner: Breezy mascot cheers + ExplanationDrawer
    else Retry (Playful Mode)
        UI->>Audio: Play soft try-again SFX
        UI->>Learner: Gentle wobble + progressive hint
    end
```

## Changelog

| Version | Date | Summary of Changes |
| :--- | :--- | :--- |
| **v1.2.0** | 2026-11-22 | Confirmed runtime parity between Cloudflare Edge Worker/Hono API (`https://language.outxet.dev/api/v1`) and local FastAPI (`/api/v1`) for onboarding, `DragDropBoard` state transitions, and grading responses. |
| **v1.1.0** | 2026-11-15 | Aligned FSM (`>= 6px` drag threshold, `elementsFromPoint` hit-test, Enter/Space keyboard parity) and sequence response keys (`evidence_quotes`, `explanation`, `score_ratio`, `feedback_type`) with implemented `drag_engine.js` & `grader.py`. |
| **v1.0.0** | 2026-11-15 | Initial learner journey, drag-drop FSM, and grading sequence diagrams. |

