DeutschPath

AI-powered German learning platform — runs entirely on your machine

Features

🌍 16 Supported Languages

AI explanations are delivered in your chosen language(s) — pick English only, a second language only, or both. Configurable in Settings:

🚀 Quick Start

No installation wizard. Just double-click.

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

🔑 Getting Your Gemini API Key

DeutschPath uses Google's Gemini API. The free tier covers regular personal use.

1. Go to aistudio.google.com — sign in with any Google account
2. Click Get API key → Create API key
3. Copy the key (it starts with AQ. in current AI Studio versions)
4. 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.

Important Reminder!

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.

🛠 Technologies & Tools

🏗 Architecture

╔══════════════════════════════════════════════════════════════════╗
║                        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)     ║       ║
║                             ╚════════════════════════════╝       ║
╚══════════════════════════════════════════════════════════════════╝

Key design decisions

• 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() in ai_service.py initialises 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.py runs CREATE TABLE IF NOT EXISTS plus 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.json because 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 browser speechSynthesis fallback — 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: isolate so word order renders correctly in both directions simultaneously.

💻 Developer Setup

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 8000

Frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000

GEMINI_API_KEY=your_key_here
FRONTEND_URL=http://localhost:3000

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_USER_ID=demo-user-001

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)

🤝 Contributing

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.

☕ Support

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.

📄 License

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.