-003B57?style=flat-square&logo=sqlite&logoColor=white){kind=icon}
DeutschPath is a local-first German learning platform that runs entirely on your computer.
Upload real German books, annotate words and grammar, chat with an AI tutor,
practice writing, and have full voice conversations — no subscription, no data leaving your machine.
|
Upload any German PDF — text-based or scanned. Highlight a word to get instant analysis, or a phrase to identify the grammar rule. One click saves it to your study list. A persistent AI tutor chat lets you ask questions about anything on the current page.
|
Your saved words are reviewed using the SM-2 algorithm — the same method used by Anki. The app automatically schedules each word for the optimal review moment.
|
|
A structured A1 → C2 grammar roadmap with 15 pre-built rules. Each rule has its own AI tutor that gives exercises, corrects answers in real time, and advances you when you're ready.
|
Practice real German in 10 role-play scenarios — grocery store, restaurant, bank, doctor, job interview, and more. The AI agent stays in character and adapts to your CEFR level.
|
|
Select a topic by level and type (essay, email, story, exam prompt), write in German, and get detailed AI feedback with a scored diff view.
|
A complete German case reference covering all articles, adjective endings, and personal pronouns — with a fill-in-the-blank practice mode and live scoring.
|
AI explanations are delivered in your chosen language(s) — pick English only, a second language only, or both. Configurable in Settings:
| 🇮🇷 Persian | 🇸🇦 Arabic | 🇷🇺 Russian | 🇫🇷 French | 🇪🇸 Spanish | 🇹🇷 Turkish | 🇨🇳 Chinese | 🇯🇵 Japanese |
| 🇰🇷 Korean | 🇵🇹 Portuguese | 🇮🇹 Italian | 🇵🇱 Polish | 🇳🇱 Dutch | 🇸🇪 Swedish | 🇺🇦 Ukrainian | 🇬🇧 English |
No installation wizard. Just double-click.
|
🍎 macOS
|
🪟 Windows
|
The launcher:
- Installs all Python and Node.js dependencies on first run (~1–2 min)
- Starts the FastAPI backend (port 8000) and Next.js frontend (port 3000) silently in the background
- Opens a browser progress page, then redirects to the app when ready
- On every re-launch: detects the servers are already up and opens the browser in ~5 seconds without restarting anything
DeutschPath uses Google's Gemini API. The free tier covers regular personal use.
- Go to aistudio.google.com — sign in with any Google account
- Click Get API key → Create API key
- Copy the key (it starts with
AQ.in current AI Studio versions) - Open DeutschPath → Settings → paste and save
Free tier limits (as of June 2026): 10 requests/min · 250,000 tokens/min · 250 requests/day for Gemini 2.5 Flash text. The TTS model (
gemini-2.5-flash-preview-tts) has no free tier — voice features (auto-play in scenarios and the reader) are billed at paid rates. Keep auto-play off if you want to stay on the free tier.
When you have finished using the platform and want to exit, do NOT simply close the tab. First, shut down the platform by clicking the button in the top right corner, and only then close the tab.
| Category | Tool / Library | Version | Purpose |
|---|---|---|---|
| UI Framework | Next.js | 15 | App Router, server components, routing |
| UI Runtime | React | 19 | Component rendering |
| Language | TypeScript | 5 (strict) | Type safety across the frontend |
| Styling | Tailwind CSS | 3 | Utility-first CSS, dark mode |
| State | Zustand | — | Global UI state (user level, languages) |
| Icons | lucide-react | — | SVG icon set |
| API Framework | FastAPI | 0.111 | REST API, async request handling |
| Language | Python | 3.10+ | Backend runtime |
| ORM | SQLAlchemy | 2 | Database models and queries |
| Server | Uvicorn | — | ASGI server for FastAPI |
| Database | SQLite | — | Local file database, zero config |
| AI — text | Google Gemini 2.5 Flash | — | Analysis, chat, OCR, grammar, writing |
| AI — voice | Gemini 2.5 Flash TTS Preview | — | Neural TTS, PCM16 audio output |
| PDF — text | pdfplumber | — | Text extraction from native PDFs |
| PDF — scanned | Gemini Vision | — | OCR fallback for image-based PDFs |
| Speech input | Web Speech API | browser | Microphone input in scenarios |
| Spaced repetition | SM-2 algorithm | — | Vocabulary review scheduling |
| Image processing | Pillow | — | Launcher icon generation (.icns / .ico) |
| Launcher | Python http.server + subprocess | — | Cross-platform app launcher |
╔══════════════════════════════════════════════════════════════════╗
║ USER'S MACHINE ║
║ ║
║ ┌───────────────────────────────────────────────────────────┐ ║
║ │ Browser (localhost:3000) │ ║
║ │ Next.js 15 · React 19 · TypeScript │ ║
║ │ │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
║ │ │ Reader │ │ Vocab / │ │ Grammar │ │ Writing │ │ ║
║ │ │ + Chat │ │ Flashcd │ │ Roadmap │ │ Practice │ │ ║
║ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
║ │ │Scenarios │ │ Cases │ │Dashboard │ │ Settings │ │ ║
║ │ │+ Voice │ │ & Drills │ │& Progress│ │& API Key │ │ ║
║ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ ║
║ └────────────────────────┬──────────────────────────────────┘ ║
║ │ HTTP/JSON (fetch) ║
║ ┌────────────────────────▼──────────────────────────────────┐ ║
║ │ FastAPI (localhost:8000) │ ║
║ │ │ ║
║ │ Routers Services │ ║
║ │ ├─ /books (reader,OCR) ├─ ai_service.py │ ║
║ │ ├─ /words (vocab, SM-2) │ └─ all Gemini calls │ ║
║ │ ├─ /grammar (roadmap) ├─ pdf_service.py │ ║
║ │ ├─ /scenarios (chat) │ └─ pdfplumber + OCR │ ║
║ │ ├─ /writing (feedback) ├─ tts_service.py │ ║
║ │ ├─ /tts (audio out) └─ usage_tracker.py │ ║
║ │ ├─ /settings (key, stats) └─ usage.json │ ║
║ │ └─ /users (profile) │ ║
║ └──────────┬─────────────────────────┬──────────────────────┘ ║
║ │ │ ║
║ ┌──────────▼──────────┐ │ HTTPS ║
║ │ SQLite Database │ │ ║
║ │ deutschpath.db │ ╔─────────▼──────────────────╗ ║
║ │ │ ║ Google Gemini API ║ ║
║ │ Books · Words │ ║ ║ ║
║ │ Grammar · Sessions │ ║ gemini-2.5-flash ║ ║
║ │ Writing · Profile │ ║ (text · vision · chat) ║ ║
║ │ Annotations │ ║ ║ ║
║ └─────────────────────┘ ║ gemini-2.5-flash-tts ║ ║
║ ║ (neural voice output) ║ ║
║ ╚════════════════════════════╝ ║
╚══════════════════════════════════════════════════════════════════╝
- Single-user, local-first. No authentication, no cloud database. All user data (vocabulary, progress, grammar mastery, uploaded PDFs) stays in a single SQLite file on your machine.
- Lazy Gemini client.
_get_client()inai_service.pyinitialises the Gemini SDK on first use. If no API key is set it raises a friendly error shown in the Settings UI — the app starts cleanly without a key. - Auto-migration.
database.pyrunsCREATE TABLE IF NOT EXISTSplus a_migrate_sqlite()pass on every startup to add new columns to existing tables without wiping data. No Alembic, no migration files. - Separate TTS tracking. Text and TTS calls are recorded in distinct buckets in
usage.jsonbecause they have very different per-token prices ($0.30/$2.50 vs $0.50/$10.00 per 1M). The Settings page shows both breakdowns and links to AI Studio for accurate real-time figures. - Neural TTS only. All voice output uses
gemini-2.5-flash-preview-tts(PCM16 audio wrapped in a WAV header server-side). There is no browserspeechSynthesisfallback — consistent quality over silent degradation. - Bidirectional text. When the AI responds in a right-to-left language (Persian, Arabic) and includes German example sentences, the reader chat wraps each German segment in
dir="ltr" unicode-bidi: isolateso word order renders correctly in both directions simultaneously.
Backend
cd backend
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # add your GEMINI_API_KEY
uvicorn main:app --reload --port 8000Frontend
cd frontend
npm install
npm run devEnvironment variables
backend/.env
GEMINI_API_KEY=your_key_here
FRONTEND_URL=http://localhost:3000frontend/.env.local (copy from .env.local.example)
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_USER_ID=demo-user-001Project structure
DeutschPath/
├── backend/
│ ├── main.py # FastAPI app entry point — mounts all routers
│ ├── models.py # SQLAlchemy ORM models
│ ├── database.py # SQLite engine, init_db(), auto-migration, seeding
│ ├── seed_data.py # 15 grammar rules (A1→C2) + 10 scenarios
│ ├── requirements.txt
│ ├── routers/
│ │ ├── books.py # PDF upload, OCR, page text, reader chat, transcription
│ │ ├── words.py # Vocabulary CRUD, SM-2 review, batch analysis
│ │ ├── grammar.py # Grammar roadmap, exercises, mastery, AI practice chat
│ │ ├── scenarios.py # Scenario listing, conversation sessions
│ │ ├── writing.py # Writing topics, AI analysis, session history
│ │ ├── tts.py # Gemini TTS endpoint → WAV response
│ │ ├── settings.py # API key, usage stats, backup/restore
│ │ └── users.py # User profile, daily goal, stats
│ └── services/
│ ├── ai_service.py # All Gemini calls (analysis, chat, OCR, TTS, transcription)
│ ├── pdf_service.py # PDF text extraction (pdfplumber + Gemini OCR fallback)
│ ├── tts_service.py # gTTS stub (unused — kept for reference)
│ └── usage_tracker.py # Token/cost tracking per call type → usage.json
├── frontend/
│ └── src/
│ ├── app/ # Next.js pages: reader · vocabulary · grammar · writing
│ │ # scenarios · cases · dashboard · settings · contact
│ ├── components/
│ │ ├── layout/ # TabNav, ConfirmLeaveDialog, LevelBadge
│ │ ├── reader/ # PDFViewer, TextPanel, AnalysisTable,
│ │ │ # WordExplanationCard, GrammarExplanationCard, BookUpload
│ │ ├── vocabulary/ # FlashCard, QuizGame
│ │ └── writing/ # WritingTopicCard, DiffView
│ ├── hooks/
│ │ └── useTheme.ts # Dark/light mode (persisted in localStorage)
│ └── lib/
│ ├── api.ts # All fetch calls to the backend (single source of truth)
│ ├── store.ts # Zustand store — userLevel, translationLanguages, UI state
│ ├── languages.ts # 16 supported languages with RTL flags
│ └── speak.ts # Browser TTS wrapper (legacy, not used for main TTS)
├── launcher.py # Cross-platform launcher — mini HTTP progress server + subprocess
├── DeutschPath.app/ # macOS app bundle — double-click to launch
├── DeutschPath.bat # Windows first-run setup (auto-installs Python + Node.js)
├── DeutschPath.vbs # Windows silent launcher (no terminal window)
└── frontend/public/
├── logo.png # App logo — source for .icns (Mac) and .ico (Windows)
├── background.png # README banner and Contact page background
└── profile.png # Author photo (Contact page)
Contributions are welcome. For non-trivial changes, please open an issue first to discuss what you'd like to change — this avoids wasted effort if the direction doesn't fit the project.
DeutschPath started as a hobby weekend project — born out of personal frustration with existing German learning tools that are either too expensive, too gamified, or don't let you learn from real books. It is free and open source.
If it saves you time or makes learning German a little less painful, consider buying a coffee — it keeps the weekend sessions going.
Dual License: AGPL v3 + Commercial — see LICENSE for the full text.
- Free under AGPL v3 for personal, educational, open-source, and non-commercial use. Any modifications you distribute must also be released under AGPL v3.
- Commercial use (selling it, bundling it in a paid product, or offering it as a hosted service without releasing your source) requires a separate commercial license — contact saber.jelodarii@gmail.com
By submitting a pull request you agree that your contribution may also be distributed under a commercial license by the project owner.
Made by Saber Jelodari
AI responses are generated by Gemini and may occasionally contain mistakes — always verify important German.