# HLD — System & Subsystem Architecture

> [← Overview](./overview.md) | [HLD HTML View](./index.html) | Next: [Flows →](./flows.md)

## 1. Dual-Runtime Architecture Overview (Local & Cloudflare Edge)

```mermaid
flowchart LR
    Browser["Browser Client - Shared ES6+ + DragDropBoard"] -->|"https://language.outxet.dev"| Worker["Cloudflare Worker + Hono + Edge Assets"]
    Browser -->|"http://127.0.0.1:8000"| API["Local FastAPI + Jinja2"]
    Worker --> D1[("Cloudflare D1 lingobright-db")]
    API --> SQLite[("Local SQLite + YAML Packs + Audio Cache")]
    Packs["content/packs/*.yaml + app/static/*"] -->|"export_d1_sql + sync_worker_assets"| Worker
    Packs --> API
```

---

## 2. Detail A — Browser Frontend Modules

```mermaid
flowchart TD
    Shell["Bright UI Shell + Playful/Exam Switcher"] --> Renderers["11 Exercise Renderers"]
    Renderers --> DND["Pointer-Event DragDropBoard"]
    Renderers --> AudioUI["Multi-Accent Speech + Web Audio SFX"]
    Renderers --> Drawer["Linguistic & Band/Nx Breakdown Drawer"]
```

---

## 3. Detail B — Python Backend Engines & Services

```mermaid
flowchart LR
    API["FastAPI Routers"] --> Auth["Auth & Guest Profile"]
    API --> Curr["Multi-Tier Course & Filter"]
    API --> Place["Placement Diagnostic"]
    API --> Grader["11-Type Grader + NFC Normalizer"]
    API --> PackSvc["YAML/JSON Pack Service"]
    Grader --> SRS["SM-2 Spaced Repetition"]
    Grader --> Est["Band / TOEIC / JLPT Estimator"]
    Grader --> Game["XP, Stars & Stickers"]
```

## Subsystem Responsibilities Matrix

| Subsystem | Core Responsibility | Key Design Rule |
| :--- | :--- | :--- |
| **Proficiency & Exam Matrix** | Maps `(target_lang, exam_framework, cefr_level, skill_focus)` | Orthogonal tags allow `JLPT N5->N1`, `IELTS 4.5->9.0`, `TOEIC`, `TESOL` in one schema |
| **Universal Script Engine** | Renders `LTR`, `RTL`, `CJK` (`<ruby>`), Hangul, IPA cleanly | `<bdi dir="rtl\|ltr">`, Unicode `NFC` normalization before every comparison |
| **3-Tier Audio Pipeline** | `Cached MP3` → `Browser Web Speech (BCP-47)` → `Web Audio SFX` | Supports `0.7x` Turtle, `1.0x` Normal, `1.15x` Exam + `en-US/GB/AU` accents |
| **Security & Kid Privacy** | Zero-PII guest start + optional account + 4-digit Parent/Studio PIN | `HttpOnly` signed cookies (`HS256` JWT via `PyJWT` / Web Crypto), `pbkdf2_sha256` (`100k` Web Crypto / Passlib) |
| **Deployment Scaling** | Local SQLite (`python run.py`) + Serverless Cloudflare Edge (`language.outxet.dev`) | Parity `/api/v1` + identical `app/static/` ES6 frontend served directly from Cloudflare Assets |

## Changelog

| Version | Date | Summary of Changes |
| :--- | :--- | :--- |
| **v1.2.0** | 2026-11-22 | Updated architecture overview & scaling matrix for Dual-Runtime deployment (**FastAPI + SQLite** locally and **Hono Worker + D1 + Assets** on `language.outxet.dev` using Web Crypto `HS256` + `pbkdf2_sha256`). |
| **v1.1.0** | 2026-11-15 | Documented exact password/PIN hashing scheme (`pbkdf2_sha256` via Passlib) and `run.py` entrypoint. |
| **v1.0.0** | 2026-11-15 | Initial split HLD overview + component diagrams. |
