03 · Tech Stack, Repository Tree & Code Files
Python 3.9+ FastAPI + SQLAlchemy 2.0 + Pydantic v2 + Zero-Build ES6+ Modules (no Node.js required locally).
Stack Data-Flow & Decisions
Open tech-stack.md
flowchart LR
Browser["Browser: Shared ES6+ + DragDropBoard"] -->|"https://language.outxet.dev"| Worker["Cloudflare Worker + Hono + Assets"]
Browser -->|"Local Dev 127.0.0.1:8000"| FastAPI["FastAPI + Jinja2 + Pydantic v2"]
Worker --> D1[("Cloudflare D1 lingobright-db")]
FastAPI --> DB[("Local SQLite data/lingobright.db")]
PackCLI["Python CLI: export_d1_sql + sync_worker_assets"] --> Worker
PackCLI -->|"Load / Validate"| YAML["content/packs/lang/*.yaml"]
| Layer | Stack Choice | Role |
|---|---|---|
| Local Backend | Python 3.9.6+ · FastAPI + Uvicorn | Async REST /api/v1, Jinja2 templates, local SQLite |
| Edge Backend | Cloudflare Workers · TypeScript + Hono | Serverless 24/7 host bound to https://language.outxet.dev |
| Databases | SQLAlchemy 2.0 + Cloudflare D1 | 16 tables synced identically via scripts/export_d1_sql.py |
| Validation | Pydantic v2 + PyYAML / js-yaml | 11-type polymorphic exercise contracts & YAML pack checks |
| Frontend | CSS3 + Vanilla ES6+ Modules | Zero bundler overhead; shared via Cloudflare Edge Assets |
| Audio / SFX | Web Speech + Web Audio + MP3 Cache | Multi-accent (en-US/GB/AU, ja-JP, pl-PL) + zero-asset SFX |
Python, Worker & Frontend File Inventory
Open python-and-frontend.md| Folder / Script | Files | Key Responsibility |
|---|---|---|
app/core/ & models/ | 16 SQLAlchemy tables + settings/security | Local SQLite ORM, JWT cookies & pbkdf2_sha256 hashing |
app/exercises/ & services/ | text_normalizer, grader, placement, score_estimator, pack_service | Unicode NFC, 11 graders, SM-2 SRS & Band/TOEIC/JLPT estimators |
worker/src/ | index.ts, views/html.ts, lib/*.ts | TypeScript Hono Worker + D1 + Web Crypto parity deployed on language.outxet.dev |
app/static/js/ | app.js, api_client.js, drag_engine.js, renderers/_board_helpers.js + 11 renderers | Zero-build ES6+ modules synced to worker/public/static/ |
scripts/ | init_db, validate_packs, export_d1_sql, sync_worker_assets | Local seed, strict YAML lint, D1 SQL generator & Cloudflare Asset sync |
content/packs/ | en/, ja/ (N5–N1), zh/, ko/, fr/, es/, de/, ar/, vi/, pl/ | 17 validated YAML packs across 10 languages (Basic → Super-Advanced) |
Changelog
| Version | Date | Summary of Changes |
|---|---|---|
| v1.2.0 | 2026-11-22 | Added Cloudflare Workers + Hono + D1 stack (worker/src/, export_d1_sql.py, sync_worker_assets.py) and Polish pack (17 YAML packs across 10 languages). |
| v1.1.0 | 2026-11-15 | Corrected ORM count (15 → 16 tables), added app/static/js/ row including _board_helpers.js & renderers/index.js, and verified 16 YAML packs. |
| v1.0.0 | 2026-11-15 | Initial Tech Stack & File Inventory HTML view. |