Auf Deutsch

Auf Deutsch is an open source, local-first German learning app focused on self-study. It packages a FastAPI app, curated A1/A2 learning content, spaced repetition, stories, listening practice, and review tracking into a project people can install and run on their own machines.

What It Includes

• guided daily learning sessions
• spaced repetition review
• phrase packs, dialogues, grammar, stories, and listening exercises
• local SQLite progress tracking
• optional audio generation with gTTS
• a CLI entry point: auf-deutsch

Quick Start

Install from GitHub

pip install "git+https://github.com/jrootn/auf-deutsch.git"
auf-deutsch

Install from a local checkout

git clone https://github.com/jrootn/auf-deutsch.git
cd auf-deutsch
pip install .
auf-deutsch

Contributor setup

git clone https://github.com/jrootn/auf-deutsch.git
cd auf-deutsch
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
pytest
auf-deutsch --skip-audio

The default app URL is http://127.0.0.1:8000.

CLI

auf-deutsch --help
auf-deutsch --no-browser
auf-deutsch --skip-audio
auf-deutsch --port 8010
auf-deutsch-validate

Data Storage

The app stores user data outside the repo:

• Linux: ~/.local/share/auf-deutsch
• macOS: ~/Library/Application Support/auf-deutsch
• Windows: %LOCALAPPDATA%\auf-deutsch

Useful overrides:

• AUF_DATA_DIR=/custom/path
• AUF_DB_PATH=/custom/path/progress.db
• AUF_SKIP_STARTUP_AUDIO=1

Dependencies

pip install . installs the runtime dependencies declared by the package:

• fastapi
• uvicorn
• jinja2
• gtts
• itsdangerous
• python-multipart

The app works best online if you want generated pronunciation audio, because gTTS uses Google text-to-speech. The rest of the learning flow still works with --skip-audio.

Troubleshooting

If first run fails or the app starts in a restricted environment:

• try auf-deutsch --skip-audio
• set AUF_DATA_DIR=/some/writable/path
• set AUF_DB_PATH=/some/writable/path/progress.db if you want the database somewhere specific

The package includes a compatibility wrapper for current FastAPI/Starlette template rendering, so fresh installs should not depend on older TemplateResponse behavior.

Project Layout

src/auf_deutsch/      Python package
src/auf_deutsch/content/    Bundled learning materials
src/auf_deutsch/templates/  Server-rendered UI
src/auf_deutsch/static/     Static assets
tests/               Smoke tests
.github/workflows/   CI and PyPI release automation

GitHub Release Readiness

This repo is set up for GitHub use with:

• a standalone package layout under src/
• a contributor install path
• CI workflow for tests and build checks
• a PyPI publish workflow using GitHub Actions trusted publishing

GitHub repository: https://github.com/jrootn/auf-deutsch

PyPI Release Readiness

The package can be built and checked locally with:

python -m build
python -m twine check dist/*

The included publish workflow expects:

1. a real GitHub repository
2. a PyPI project named auf-deutsch
3. PyPI trusted publishing configured for that repository

Detailed release steps are in RELEASING.md.

License

MIT