# Tech Stack & Layer Architecture

> [Docs Home](../README.md) | [Tech & Files HTML View](./index.html) | Next: [Repository Tree →](./repo-tree.md)

## Layer Flow Diagram

```mermaid
flowchart LR
    Browser["Browser: ES6+ Modules + Pointer Events + Web Audio"] -->|"https://language.outxet.dev"| Worker["Cloudflare Worker + Hono + Assets"]
    Browser -->|"Local Dev JSON / HTML"| FastAPI["FastAPI + Jinja2 + Pydantic v2"]
    Worker --> D1[("Cloudflare D1 lingobright-db")]
    FastAPI --> ORM["SQLAlchemy 2.0 ORM"] --> DB[("Local SQLite data/lingobright.db")]
    PackCLI["Python CLI: export_d1_sql + sync_worker_assets"] -->|"0001_schema & 0002_seed SQL"| Worker
    PackCLI -->|"Load / Validate"| YAML["content/packs/lang/*.yaml"]
```

## Verified Tech Stack Matrix

| Layer | Technology | Target Version | Status & Rationale |
| :--- | :--- | :--- | :--- |
| **Local Runtime** | Python + FastAPI + Uvicorn | `Python 3.9.6+` | Async REST `/api/v1`, Jinja2 templates, auto `/docs` OpenAPI |
| **Edge Runtime** | Cloudflare Workers + TypeScript + Hono | `wrangler 4.x`, `hono 4.x` | 24/7 global edge serving `https://language.outxet.dev` (`language.outxet.dev`) |
| **Validation** | Pydantic v2 (`app/`) & TypeScript + `js-yaml` (`worker/`) | `>=2.6` / `^4.1` | Discriminated unions for 11 exercise schemas & YAML pack checks |
| **Database** | SQLAlchemy 2.0 SQLite + Cloudflare D1 (`lingobright-db`) | `SQLite 3 / D1 APAC` | Single DDL/seed generated via `export_d1_sql.py` (16 tables) |
| **Templates / HTML** | Jinja2 (`app/`) & SSR Edge HTML (`worker/src/views/`) | Native Browser | Identical DOM IDs, `<bdi dir="rtl\|ltr">`, `<ruby>` Furigana |
| **Frontend UI** | Modern CSS3 + Vanilla ES6+ Modules | Shared `app/static/` | Synced into Cloudflare Edge `ASSETS` via `sync_worker_assets.py` |
| **Audio / SFX** | Web Speech API + Web Audio API | Native + Optional CLI | Multi-accent (`en-GB/US/AU`, `ja-JP`, `pl-PL`) + Web Audio SFX |
| **Auth** | Passlib (`pbkdf2_sha256`) + PyJWT / Web Crypto `HS256` | Standard | `HttpOnly` signed cookies + `100k` PBKDF2-SHA256 hashes (Workers-safe) |
| **QA / Test** | `pytest` + `httpx` + `ruff` + `vitest` + `tsc` | `pytest 8`, `vitest 3` | Automated verification across Python API, Worker logic & 17 YAML packs |

## Changelog

| Version | Date | Summary of Changes |
| :--- | :--- | :--- |
| **v1.2.0** | 2026-11-22 | Documented Cloudflare Edge stack (**TypeScript + Hono Worker + Cloudflare D1 + Edge Assets + Web Crypto `100k` PBKDF2 / `HS256` + Vitest**) alongside local Python stack. |
| **v1.1.0** | 2026-11-15 | Replaced planned `Alembic` mention with implemented `Base.metadata.create_all` bootstrap and specified `pbkdf2_sha256` Passlib hashing scheme. |
| **v1.0.0** | 2026-11-15 | Initial verified tech stack & layer architecture document. |

