German Grammar Trainer

Stop memorizing rules. Build German sentences until word order feels natural.

An open-source, self-hosted language trainer: an LLM writes fresh B1-level exercises for any grammar topic you describe, spaced repetition decides what you review, and podcast mode lets you keep drilling on a walk.

Try the live demo → · Run your own · What's new

Why

Textbooks give you ten example sentences per grammar point. You need hundreds — with weil, obwohl, damit, verb + preposition, Konjunktiv II — until you stop thinking about where the verb goes. This trainer generates them on demand, in situations you choose (a Jobcenter appointment, the telc speaking exam, small talk at work), and keeps bringing back the ones you get wrong.

Screenshots

AI explains your mistakes	On your phone

Highlights

• 🧩 Build the sentence. See English, tap the German words in order (or press 1–9 / a–z, or answer by voice). Punctuation is placed for you.
• 🤖 Unlimited AI exercises. Describe a topic in plain words; the model writes varied sentences for it. Works with Claude, OpenAI or any OpenAI-compatible API, with automatic fallback when credits run out.
• 🧠 Spaced repetition. Log in with Google and the trainer schedules reviews and brings back what you got wrong.
• 💡 Explains your mistakes. Put a word in the wrong place and the AI tells you why — Time before Place, seit + Dativ — in plain English.
• 🎧 Podcast mode. Turn a topic into a Glossika-style MP3: listen, then recall. Private RSS feed for any podcast app.
• 🔊 Natural audio via ElevenLabs, cached on disk.
• 📱 Installable PWA that works offline and syncs when you're back.
• 🌳 Your own curriculum. Nested topic tree (e.g. telc B1 → Mündliche Prüfung → Teil 2) with drag-and-drop, search and archive.
• 🛠️ Small and self-hosted. One Go binary and SQLite in a Docker image. The gct CLI lets you — or a coding agent — manage topics from the terminal.

German B1 is where it started, but topics are just prompts: point it at any language or level.

Quick start

docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your_api_key \
  -e MODEL_NAME=gpt-4o-mini \
  ghcr.io/korjavin/german-conjuctions-trainer:2

Open http://localhost:8080 and start practicing. For persistent storage, Claude, Google login, audio and podcasts see Running with Docker and Environment Variables.

All features

• Exercise Caching: Generated exercises are cached for instant access, reducing API costs and wait times.
• Spaced Repetition System (SRS): For logged-in users, exercises are presented using an SRS algorithm to optimize learning and retention.
• On-Demand Generation: New exercises are generated automatically only when the cache is empty or a user has seen all available exercises.
• Automatic Prompt Refinement: Uses a meta-prompt to improve user-defined prompts during on-demand generation, leading to more creative and varied exercises.
• Searchable Topic Selector: A searchable combobox in the header to easily find and switch between grammar topics.
• Interactive Exercises: Engaging word-scramble exercises with customizable topics.
• Hint System: Provides hints for the next correct word, with usage tracking.
• Session Statistics: Detailed performance tracking, including mistakes, hints used, accuracy, and time per exercise.
• Local Word Scrambling: Ensures instant feedback by scrambling words locally.
• Keyboard Hotkeys: Use keys 1-9 and a-z for quick word selection.
• Automatic Punctuation: Handles punctuation automatically for a smoother experience.
• Secure Backend: API keys are stored securely on the server-side.
• Custom API Support: Compatible with any OpenAI-compatible API.
• Responsive Design: Fully functional on both desktop and mobile devices.
• Topics Management: Create, edit, and delete grammar topics.
• Topic Archive: The Archive button in the settings tree moves a topic, with all its subtopics, into a separate Archive root. Archived topics disappear from the practice topic picker on the main screen but keep their exercises, audio cache and podcasts; inside the archive they behave like any other branch (drag, edit, delete). Restore puts a topic back under the parent it was archived from (or at the root level if that parent is gone). API: POST /api/topics/<id>/archive and /unarchive.
• Prompt Customization: Tailor exercise generation prompts for each topic.
• Version History: Track and restore the last 10 versions of a prompt.
• Persistent Storage: Uses SQLite for fast and reliable data storage.

Optional Google Login

This application provides an optional login feature using Google OAuth 2.0. When a user logs in, the application will store their statistics and settings, allowing them to track their progress across sessions. This feature is entirely optional and the application is fully functional without logging in.

For more information on the data we store, please see our Privacy Policy.

Podcast Mode

The 🎧 button in the header builds a Glossika-style audio lesson from the selected topic and its subtopics — the same selection as a practice session. The episode plays in the browser (it keeps playing when the dialog is closed) or downloads as an MP3 for any player.

• 25 phrases. If the subtree has fewer, new exercises are generated first (up to three LLM rounds).
• Part 1, listen: English, then German twice, for every phrase.
• Part 2, recall: the phrases reshuffled; English, then a silence long enough to say the German yourself (1.5× the German clip + 1.5 s), then the German.
• Selection: logged-in users get a weighted pick — phrases with many mistakes come up more often, well-learned ones less often, hidden ones never — and up to five of their weakest phrases are recalled a second time. Guests get a uniform random pick. Listening does not change SRS statistics.

German in episodes is spoken slower than in the trainer: ElevenLabs speed PODCAST_DE_SPEED (default 0.75, clamped to 0.7–1.2); English uses ELEVENLABS_VOICE_SPEED. Slow German clips are cached under their own key, so trainer audio is unaffected.

Audio uses the configured ElevenLabs voice and model (ELEVENLABS_MODEL_ID, default eleven_v4). English clips are requested with language_code: en; eleven_multilingual_v2 ignores it (a German voice then reads English with an accent), so if a eleven_multilingual_* model is configured English is synthesized with eleven_flash_v2_5. ELEVENLABS_ORIGINAL_LANGUAGE_VOICE_ID sets a separate voice (by ID) for English. English clips are cached in audio_cache next to the German ones, keyed by model and voice, so changing either re-synthesizes them. The server stitches the MP3 frames itself (no ffmpeg) and serves episodes from GET /api/podcast/<id>.mp3 (built by POST /api/podcast with {"topic_id": "..."}).

Builds are the most expensive request, so they are bounded:

• Concurrency: at most 2 builds run at once server-wide; further requests get 429 PODCAST_BUSY immediately.
• Rate: 10 builds/hour per logged-in user (burst 3), 4/hour per guest IP (burst 2), and 20/hour across all guests (burst 5); over the limit returns 429 PODCAST_RATE_LIMITED with Retry-After.
• Deadline: a build gives up after 4 minutes (504), each TTS clip after 45 s; TTS calls are cancelled when the deadline passes or the client disconnects.
• Retention: episodes are kept in audio_cache/podcasts/ for exactly seven days (expires_at in the response). The TTS cache cleanup never touches them. The episode store is capped at 1 GiB; when it is full, new builds get 503 PODCAST_STORAGE_FULL instead of evicting episodes whose links were already handed out.

Private RSS feed

Logged-in users can listen in a podcast app instead of the browser. Settings → Podcast RSS feed shows a private feed URL (/podcast/feed/<token>.xml) to add to any podcast app; it lists the episodes that user built in the web UI during the last seven days (the app downloads them before they expire). Guests get no feed.

• The URL itself is the credential (podcast apps send no cookie), so keep it private. Regenerate replaces it; the old URL returns 404 and the podcast app must be re-subscribed.
• The feed is RSS 2.0 with the iTunes namespace; enclosures are absolute URLs to /api/podcast/<id>.mp3 built from PUBLIC_BASE_URL (or the origin of GOOGLE_REDIRECT_URL), never from the request's Host header. Without either, the feed is disabled.
• API: GET /api/podcast/feed returns {"feed_url": "..."} (creating the token on first call); POST /api/podcast/feed/regenerate replaces it. Both need a session.

Prompt Refinement

This application uses a Simple Intent approach combined with optional Prompt Refinement to enhance the quality of generated exercises.

Simple Intent Prompts: When creating topics, you only need to describe what you want to practice—grammar topic, vocabulary themes, and situations. The backend automatically adds all technical details (system role instructions, variation profiles, JSON output format) before sending to the language model.

Example simple intent prompt:

Topic: um...zu and damit conjunctions
Level: B1
Vocabulary: daily life, travel, work
Situations: explaining reasons, expressing goals, giving instructions

Optional Refinement: If enabled, the application can send your simple intent to a language model with a meta-prompt that expands vocabulary range, suggests diverse real-life situations, and clarifies difficulty level while keeping the result concise.

This ensures that the exercises you receive are not repetitive and are of higher pedagogical quality.

Observability

To provide insight into the prompt refinement process, you can view the most recently used refined prompt. This is useful for debugging and understanding how the AI is interpreting and improving your prompts.

You can access this feature via the "View Last Refined Prompt" button in the settings menu.

Command-Line Client (gct)

A Go-based CLI under cmd/cli lets admins and coding agents manage topics and trigger exercise generation without using the web UI. It authenticates via Google OAuth (device flow) and stores a long-lived bearer token in ~/.config/gct/config.json. Build it with make build-cli. See CLI.md for installation, GCP setup, command reference, and troubleshooting.

Running with Docker

Using the pre-built image from GHCR:

docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your_openai_api_key_here \
  -e OPENAI_URL=https://api.openai.com/v1 \
  -e MODEL_NAME=gpt-3.5-turbo-1106 \
  ghcr.io/korjavin/german-conjuctions-trainer:2

Updates and versions

Every release is listed on the Releases page with human-readable notes (same text as CHANGELOG.md). To get an email when a new version ships, click Watch → Custom → Releases on GitHub, or subscribe to the releases Atom feed.

Image tags:

Tag	Moves when
:2.0.0	never — exact version
:2.0	patch releases (fixes only)
:2	any release without breaking changes — recommended
:latest	every release, including breaking ones

Before moving to a new major version, read the "Before you upgrade" part of its release notes and back up your SQLite database.

Building locally:

# Build the image
docker build -t german-conjunctions-trainer .

# Run the container
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your_openai_api_key_here \
  -e OPENAI_URL=https://api.openai.com/v1 \
  -e MODEL_NAME=gpt-4 \
  german-conjunctions-trainer

Environment Variables

Variable	Required	Default	Description
OPENAI_API_KEY	Yes	-	Your OpenAI API key or compatible API key
OPENAI_URL	No	https://api.openai.com/v1	API endpoint URL
OPENAI_TIMEOUT_SECONDS	No	180	Timeout for each LLM request (refinement and generation)
ENABLE_PROMPT_REFINEMENT	No	false	When true, runs refinement before generation; otherwise uses variation-profile generation directly
MODEL_NAME	No	gpt-3.5-turbo-1106	Model name to use
LLM_PROVIDER	No	-	anthropic = call the native Claude Messages API at OPENAI_URL/messages (set OPENAI_URL=https://api.anthropic.com/v1) with prompt caching; unset = OpenAI-compatible /chat/completions
LLM_FALLBACK_URL	No	-	OpenAI-compatible endpoint retried once when the primary answers with a 4xx/5xx status (e.g. out of credits). Timeouts are not retried. Unset = no fallback
LLM_FALLBACK_API_KEY	No	-	API key for the fallback endpoint
LLM_FALLBACK_MODEL	No	MODEL_NAME	Model name for the fallback endpoint
LLM_BATCH_MIN_POOL	No	-	With LLM_PROVIDER=anthropic: every 15 minutes, topics with fewer cached exercises than this get topped up in the background through the Message Batches API (50% cheaper, async). The in-flight batch id is kept in llm_batch.json next to the database. Unset/0 = off
SQLITE_PATH	No	german.db	Path to the SQLite database file
PORT	No	8080	Port for the web server

Database Migrations

The application automatically runs database migrations on startup to update the schema. If you're upgrading from an older version:

• Migrations will add parent_id and sort_order columns to the topics table
• A unique constraint on (parent_id, name) will be added to prevent duplicate topic names at the same level
• Additional tracking columns may be added for user exercise statistics

Important: If you have duplicate topic names at the same parent level in your existing database, the migration will fail. You must manually resolve duplicates by renaming or deleting duplicate topics before the migration can complete.

Migrations are designed to be idempotent - running them multiple times has no effect.

Running Tests

The project includes comprehensive test suites for both backend and frontend functionality.

Backend Tests (Go)

# Run all tests
go test ./...

# Run tests for specific package
go test ./internal/app/...
go test ./pkg/storage/...

# Run tests with verbose output
go test -v ./...

# Run tests with coverage
go test -cover ./...

Frontend Tests (JavaScript)

Vitest unit suites live in js/__tests__/ (happy-dom) and run in CI on every pull request (pnpm test).

Test Coverage

The comprehensive test suite covers:

• Backend API validation and error handling
• Database operations and migrations
• Frontend UI interactions
• Topic tree rendering, search, keyboard navigation and Manage actions (vitest)
• User workflows (CRUD operations, drag-and-drop)

Airtable Setup (Deprecated)

Note: Airtable storage is deprecated and will be removed in future versions. Use SQLite (default) instead.

To use Airtable (legacy), set STORAGE_TYPE=airtable and configure the following:

Variable	Required	Default	Description
AIRTABLE_TOKEN	Yes (if Airtable)	-	Your Airtable Personal Access Token
AIRTABLE_BASE_ID	Yes (if Airtable)	-	Your Airtable Base ID

Default Topics

On first startup, the application will create two default topics:

• Conjunctions: Focus on German conjunctions (weil, obwohl, etc.)
• Verb + Preposition: Verb-preposition combinations

Topic Hierarchy

Topics can be organized hierarchically in a tree structure with advanced features:

Topic Hierarchy Features:

• Visual Tree Lines: Clear visual connectors show parent-child relationships at any depth level
• Expand/Collapse: Collapse branches to reduce clutter, with state persisted across sessions
• Topic Icons: Folder icons for topics with children, leaf icons for leaf topics
• Search & Filter: Instant search (Ctrl/Cmd+F in Manage) with auto-expansion of parent topics and text highlighting
• Top-Level Sorting: Tree (custom order), A–Z, Z–A, Newest, Oldest, without affecting nested children
• Drag-and-Drop (desktop): drag a row onto a gap to reorder or onto a row to nest it, with a ghost preview
• Row menu: each row's ⋯ menu offers Add child, Rename, Archive/Restore and Delete (with an "Archive instead" option)
• Editor: real-time validation, recently-used parent quick-select, prompt version history with Restore, Ctrl+Enter to save
• Accessibility: keyboard navigation (Arrow keys, Home, End, Left/Right to collapse/expand, Space to toggle, Enter to open), ARIA tree attributes, and screen reader announcements

Topic Name Uniqueness: Topic names must be unique at the same parent level (case-insensitive). You cannot create two topics with the same name that share the same parent, but you can reuse names at different levels (e.g., "Grammar" -> "Verbs" and "Adjectives" -> "Verbs" are both allowed).

Sort Order Field: Topics have a sort_order field that determines their display position within their parent. Lower values appear first. When using the "Tree" sort option, topics are displayed based on their sort_order value.

Tree Depth Limit: Topic trees are limited to a maximum depth of 100 levels to prevent performance issues.

Topic Creation Rules:

When creating or editing topics, the following validation rules apply:

• Topic Name: Required, max 200 characters
• Prompt: Required, min 10 characters, max 10,000 characters
• Sort Order: Required, must be a non-negative integer (0-999,999)

You can assign a parent topic to any new or existing topic to keep your exercises neatly categorized (e.g., "Grammar" -> "Verbs" -> "Verb + Preposition"). Deleting a topic that has children is prevented with a HTTP 409 Conflict to ensure data integrity.

Keyboard Shortcuts for Topic Tree:

• Arrow Up/Down/Left/Right: Navigate between topics
• Home: Jump to first topic
• End: Jump to last topic
• Enter or Space: Toggle expand/collapse for topics with children
• Escape: Exit tree navigation
• Ctrl+F or Cmd+F: Focus topic search input

Custom API Providers

The application supports any OpenAI-compatible API through environment variables:

# Example: Claude via the native Messages API, with OpenAI as fallback
# when the Anthropic credits run out
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your_anthropic_console_key \
  -e LLM_PROVIDER=anthropic \
  -e OPENAI_URL=https://api.anthropic.com/v1 \
  -e MODEL_NAME=claude-sonnet-5-5 \
  -e LLM_FALLBACK_URL=https://api.openai.com/v1 \
  -e LLM_FALLBACK_API_KEY=your_openai_api_key \
  -e LLM_FALLBACK_MODEL=gpt-4o-mini \
  german-conjunctions-trainer

# Example: Using Azure OpenAI
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your_azure_key \
  -e OPENAI_URL=https://your-resource.openai.azure.com/v1 \
  -e MODEL_NAME=gpt-4 \
  german-conjunctions-trainer

Anthropic's compatibility layer ignores response_format, so replies may arrive wrapped in a ```json fence or in prose; the app extracts the outermost JSON object before parsing. The app sends no temperature, so the compat layer's cap of 1 does not apply.

With LLM_PROVIDER=anthropic the topic part of the generation prompt is sent as a cached system prompt: each call logs cache_read_input_tokens, which is above 0 on the second generation of a topic within 5 minutes. Topic prompts shorter than the model's minimum cacheable length (512 tokens on the 5.x models) are not cached. Structured outputs (output_config json_schema) are deliberately not used: under the schema grammar Claude mostly returned one exercise instead of the requested set, so the reply is parsed like the compat one.

Development

Local Development:

# Set required environment variables
export OPENAI_API_KEY=your_openai_api_key

# Run the Go backend
go run main.go

# The server will serve static files from ./static/ (for Docker) or current directory (local)
# Access the app at http://localhost:8080

Rate Limiting

The backend includes rate limiting to prevent abuse. By default, it allows one request every three seconds per IP address.

Project Structure

.
├── main.go              # Go backend server with API and Airtable integration
├── index.html           # Main application UI
├── js/, css/            # Frontend ES modules (entry js/main.js) and stylesheets
├── agent.md             # Context file for AI development
├── Dockerfile           # Container definition for production
├── docker-compose.yml   # Docker Compose for local development
├── go.mod               # Go module dependencies
├── example.prompt.md    # Example prompt for exercise generation
└── .github/workflows/   # CI/CD pipelines for Docker builds

Security

• API keys are stored server-side only
• No sensitive data in browser localStorage
• CORS headers properly configured
• Non-root container user

License

MIT License - see LICENSE file for details.

---

Automated Frontend Unit Tests (Vitest)

The application includes a fast, automated unit test suite for the vanilla JS frontend using Vitest and happy-dom.

To run the automated tests:

# Run all tests once
pnpm test

# Run tests in watch mode
pnpm run test:watch

# Run tests and generate coverage report
pnpm run test:coverage