🦉 LingoBright Docs

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"]
        
LayerStack ChoiceRole
Local BackendPython 3.9.6+ · FastAPI + UvicornAsync REST /api/v1, Jinja2 templates, local SQLite
Edge BackendCloudflare Workers · TypeScript + HonoServerless 24/7 host bound to https://language.outxet.dev
DatabasesSQLAlchemy 2.0 + Cloudflare D116 tables synced identically via scripts/export_d1_sql.py
ValidationPydantic v2 + PyYAML / js-yaml11-type polymorphic exercise contracts & YAML pack checks
FrontendCSS3 + Vanilla ES6+ ModulesZero bundler overhead; shared via Cloudflare Edge Assets
Audio / SFXWeb Speech + Web Audio + MP3 CacheMulti-accent (en-US/GB/AU, ja-JP, pl-PL) + zero-asset SFX

Python, Worker & Frontend File Inventory

Open python-and-frontend.md
Folder / ScriptFilesKey Responsibility
app/core/ & models/16 SQLAlchemy tables + settings/securityLocal SQLite ORM, JWT cookies & pbkdf2_sha256 hashing
app/exercises/ & services/text_normalizer, grader, placement, score_estimator, pack_serviceUnicode NFC, 11 graders, SM-2 SRS & Band/TOEIC/JLPT estimators
worker/src/index.ts, views/html.ts, lib/*.tsTypeScript 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 renderersZero-build ES6+ modules synced to worker/public/static/
scripts/init_db, validate_packs, export_d1_sql, sync_worker_assetsLocal 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

VersionDateSummary of Changes
v1.2.02026-11-22Added 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.02026-11-15Corrected ORM count (15 → 16 tables), added app/static/js/ row including _board_helpers.js & renderers/index.js, and verified 16 YAML packs.
v1.0.02026-11-15Initial Tech Stack & File Inventory HTML view.