# LingoBright — Architecture & Specification Hub

> **Visual HTML Portal:** [docs/index.html](./index.html) (or live at `https://language.outxet.dev/docs-portal/index.html`)  
> **Live Deployment:** `https://language.outxet.dev` (**Cloudflare Worker + Hono + D1** `lingobright-db`)  
> **Status:** `v1.2.0` — Dual-Runtime (`Local FastAPI` + `Cloudflare Edge Worker/D1`), `17` packs / `10` languages (incl. Polish `pl`)

```mermaid
flowchart LR
    Home["docs/README.md & index.html"] --> HLD["01-hld/ - Context, Dual-Runtime, Flows"]
    Home --> FRS["02-frs/ - 10 Languages, 11 Exercises, Estimator"]
    Home --> Tech["03-tech/ - FastAPI + Worker/D1 Stack & Tree"]
    Home --> Data["04-data/ - ERD, D1 Migrations, Functions/API"]
```

## Documentation Map (Markdown + HTML)

| Folder | Visual HTML Portal | Markdown Sub-Documents | Focus |
| :--- | :--- | :--- | :--- |
| **`01-hld/`** | [01-hld/index.html](./01-hld/index.html) | [overview.md](./01-hld/overview.md) · [architecture.md](./01-hld/architecture.md) · [flows.md](./01-hld/flows.md) | Context, personas, component diagram, drag-drop FSM, sequence flow |
| **`02-frs/`** | [02-frs/index.html](./02-frs/index.html) | [tracks-and-modes.md](./02-frs/tracks-and-modes.md) · [exercises-matrix.md](./02-frs/exercises-matrix.md) · [gamification-studio-nfr.md](./02-frs/gamification-studio-nfr.md) | `A0→C2`, IELTS/TOEIC/TESOL/JLPT `N5–N1`, all 11 exercise types, NFRs |
| **`03-tech/`** | [03-tech/index.html](./03-tech/index.html) | [tech-stack.md](./03-tech/tech-stack.md) · [repo-tree.md](./03-tech/repo-tree.md) · [python-and-frontend.md](./03-tech/python-and-frontend.md) | Python 3.9+ / FastAPI / ES6+ stack, repo tree, Python scripts & renderers |
| **`04-data/`** | [04-data/index.html](./04-data/index.html) | [erd-and-tables.md](./04-data/erd-and-tables.md) · [exercise-schemas.md](./04-data/exercise-schemas.md) · [functions-and-api.md](./04-data/functions-and-api.md) | ERD, 16 tables, 11 polymorphic schemas, Python functions & `/api/v1` |

## 4-Phase Implementation Record

| Phase | Status | Delivered Scope |
| :--- | :--- | :--- |
| **Phase 1** | ✅ Complete | `app/core/*`, `app/models/*` (16 tables), `app/schemas/*`, `app/exercises/*` (11 graders, normalizer, placement, score estimator), CLI `scripts/` |
| **Phase 2** | ✅ Complete | `app/services/*`, `app/api/v1/*`, all 17 multi-tier YAML packs (`en`, `ja N5–N1`, `zh-Hans`, `ko`, `fr`, `es`, `de`, `ar`, `vi`, `pl`) + `stickers.yaml` |
| **Phase 3** | ✅ Complete | 8 Jinja2/Edge HTML views, CSS3 tokens, `drag_engine.js`, `sfx_synth.js`, `audio_engine.js`, all 11 `renderers/*.js` + `_board_helpers.js`, `/studio`, `/parent` |
| **Phase 4** | ✅ Complete | `export_d1_sql.py`, `sync_worker_assets.py`, Cloudflare Worker (`worker/src/*`) + D1 (`lingobright-db`) live at `https://language.outxet.dev`, `pytest`, `vitest`, `ruff`, Chrome verified |

## Changelog

| Version | Date | Summary of Changes |
| :--- | :--- | :--- |
| **v1.2.0** | 2026-11-22 | Deployed dual-runtime **Cloudflare Worker + Hono + D1** (`worker/`) to `https://language.outxet.dev`, added **Polish (`pl`)** pack (17 packs / 10 languages), added D1 export/sync CLI scripts, and published docs at `/docs-portal/`. |
| **v1.1.0** | 2026-11-15 | Marked all 4 implementation phases complete after building full backend/frontend/packs and passing `pytest` + headless Chrome checks; synchronized docs index with implemented state. |
| **v1.0.0** | 2026-11-15 | Initial split Markdown + visual HTML documentation hub and 4-phase roadmap. |
