---

📊 Project Fingerprint

---

✨ Features

🎙️ Dual-Model ASR with Dynamic Swap

• /api/score → Wav2Vec2 (character-level phonetic accuracy, ~1.2 GB RAM)
• /api/live → Whisper tiny int8 (streaming, ~150 MB RAM)
• Engine auto-swaps between them — never both in RAM simultaneously → stays under 2 GB ceiling

📊 5-Layer Adaptive Scorer (A1–C1)

• Layer 1: Global Levenshtein ratio (A1+)
• Layer 2: Word tracking — missing/extra/substituted words (A1+)
• Layer 3: German suffix quality — dropped endings (-en, -er, -e) (A2+)
• Layer 4: Umlaut accuracy — ä/ö/ü vs a/o/u confusion (B1+)
• Layer 5: Phonetic features — final devoicing, vowel length (C1 only)

🧠 Spaced Repetition (SM-2)

• Same algorithm as Anki
• Words you keep mispronouncing are surfaced for targeted re-practice
• Ease factor + interval + reps tracking per word

💾 SQLite Persistence

• Every session logged (target text, transcript, score, layers, feedback)
• WAL mode for concurrent read/write
• Weekly trend, top 10 error words, level-up readiness indicator

🎛️ Controller Architecture

• Always-on controller (port 8766, ~80 MB) serves the frontend + orchestrates the backend
• Backend on demand (port 8765, ~1.5 GB) — only runs when you're practicing
• Start/Stop from the webUI System page
• Live backend logs streamed via SSE
• Analytics page with CPU/RAM charts

🛡️ Auto-Recovery & Freeze Detection

• Idle auto-stop: backend stops after 15 min of no API activity → frees ~1.5 GB RAM
• CPU freeze: kills backend if CPU >95% for 30 consecutive seconds
• RAM circuit breaker: kills backend if RAM >2.5 GB
• Health endpoint unresponsive: kills backend if /api/status doesn't respond for 30s

🌐 Web UI (SvelteKit + Tailwind)

• 9 routes: Dashboard, Practice, Shadowing, Live, Progress, SRS Trainer, Analytics, Settings, System
• Live RAM/health indicator (green/yellow/red) in nav bar
• Color-coded feedback (green = perfect, yellow = suffix issues, red = missing words)
• Dark mode + mobile responsive

📦 Smart Setup

• Idempotent: re-running never re-downloads what's already there
• 7 modes: full / --quick / --offline / --models-only / --dev-deps / --check / --force
• aria2c for parallel downloads on slow connections
• HuggingFace models cached in ~/.cache/huggingface (survives venv rebuild)

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│ Browser → http://127.0.0.1:8766                                    │
│  ┌──────────────────────────────────────────────────────────┐     │
│  │ Controller (port 8766, ALWAYS ON, ~80 MB)                │     │
│  │  - Serves SvelteKit static frontend                     │     │
│  │  - /api/controller/status, start, stop, logs, analytics  │     │
│  │  - Proxies /api/* → backend (port 8765)                  │     │
│  │  - Monitors backend CPU/RAM, kills on freeze            │     │
│  │  - Auto-stops backend after 15 min idle                  │     │
│  └──────────────────────────────────────────────────────────┘     │
│                          │ spawns/kills subprocess                 │
│  ┌──────────────────────────────────────────────────────────┐     │
│  │ Backend (port 8765, ON DEMAND)                           │     │
│  │  - /api/score → Wav2Vec2 (~1.2 GB, character-level)      │     │
│  │  - /api/live  → Whisper tiny int8 (~150 MB, streaming)  │     │
│  │  - 5-layer adaptive scorer (A1-C1)                       │     │
│  │  - SQLite + SM-2 SRS                                     │     │
│  └──────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────┘

---

🚀 Quick Start (Arch Linux)

Prerequisites

• Arch Linux (kernel 6.x)
• Python 3.12, 3.13, or 3.14
• Node.js 20+
• ~2 GB free disk for model weights

Setup + Run

git clone https://github.com/bif26/Local_DE_Coach.git
cd Local_DE_Coach
./setup.sh          # one-time setup (idempotent)
./start.sh          # starts controller on http://127.0.0.1:8766

Then open http://127.0.0.1:8766 in your browser, go to the System page, click Start backend.

Update from upstream

git pull origin main
./setup.sh          # only downloads what changed
./start.sh

Stop

./stop.sh           # stops controller + backend

---

📂 Project Structure

Local_DE_Coach/
├── backend/
│   ├── server.py              # FastAPI backend (port 8765)
│   ├── controller.py          # Always-on orchestrator (port 8766)
│   ├── config.py              # Settings (ports, RAM, model IDs)
│   ├── db.py                  # SQLite access layer
│   ├── launcher.py            # Optional pystray system-tray
│   ├── api/
│   │   ├── routes_score.py    # POST /api/score
│   │   ├── routes_live.py     # POST /api/live (SSE)
│   │   ├── routes_progress.py # GET /api/progress, /api/srs/*
│   │   └── routes_system.py   # GET /api/status, POST /api/warmup
│   ├── core/
│   │   ├── engine.py          # Wav2Vec2 + Whisper dynamic swap
│   │   ├── preprocessor.py    # 16kHz + VAD + normalize
│   │   ├── scorer.py          # 5-layer scorer, takes level param
│   │   ├── phonetics.py       # German suffix/umlaut rules
│   │   └── srs.py             # SM-2 scheduler
│   ├── data/
│   │   ├── schema.sql         # users, sessions, word_errors, srs_queue
│   │   └── exam_corpus/       # Goethe + ÖSD reference texts
│   └── tests/
│       └── test_scorer.py
├── frontend/                  # SvelteKit + Tailwind
│   └── src/
│       ├── lib/               # api.ts, controller-api.ts, components/
│       └── routes/            # 9 routes
├── docs/                      # Documentation (Markdown + PDF + Web UI)
│   ├── markdown/              # ← Source of truth (19 chapters)
│   ├── index.html             # Web UI (renders Markdown at runtime)
│   ├── architecture.pdf       # 33-page PDF spec
│   └── assets/                # CSS, JS, images, logo
├── systemd/                   # Controller + backend services
├── setup.sh                   # Idempotent setup (7 modes)
├── start.sh                   # Start controller (+ optional --dev)
├── stop.sh                    # Stop everything
└── README.md

---

📊 RAM Budget

---

🎯 Scoring Layers (CEFR-adaptive)

---

📖 Documentation

---

🔧 Setup Modes

./setup.sh                # full (default) — installs only what's missing
./setup.sh --quick        # skip pacman + skip model pre-download
./setup.sh --offline      # skip ALL downloads; use only cached deps
./setup.sh --models-only  # only download ASR models
./setup.sh --dev-deps     # only install pytest + httpx
./setup.sh --check        # check what's missing; don't install anything
./setup.sh --force        # re-download and rebuild everything

---

📋 API Reference

Controller endpoints (port 8766, always on)

Backend endpoints (port 8765, proxied through 8766)

Interactive docs at http://127.0.0.1:8766/docs (Swagger UI).

---

📦 Releases

---

📄 License

MIT — see LICENSE.

🙏 Acknowledgements

• Wav2Vec2 — German ASR by Facebook AI
• faster-whisper — int8 Whisper via CTranslate2
• FastAPI — Python API framework
• SvelteKit — Frontend framework
• Tailwind CSS — Utility-first CSS