FluentGerman.ai

Personalized AI-powered German language learning platform.

A web-based tool for a German language teacher to provide clients with customized LLM-powered tutoring through personalized instructions, voice interaction, and a clean admin panel.

Features

• 🔐 User Management — Admin creates clients with username, email, password
• 📝 Custom Instructions — Global teaching method + per-client instructions + homework
• 💬 AI Chat — Streaming LLM responses with personalized system prompts
• 🎤 Voice Mode — Speech-to-text & text-to-speech (API or browser fallback)
• 🛠 Admin Panel — Manage users, upload instruction files, voice-to-instruction generator
• 🔄 Flexible LLM — Swap OpenAI, Anthropic, or 100+ providers via LiteLLM
• 📱 Mobile Ready — Responsive design, works on all devices

Tech Stack

Layer	Technology
Backend	Python 3.12 + FastAPI
Database	PostgreSQL (async via SQLAlchemy + asyncpg)
Auth	JWT + bcrypt
LLM	LiteLLM (provider-agnostic)
Voice	OpenAI Whisper/TTS or Web Speech API (feature flag)
Frontend	Vanilla HTML/CSS/JS
Deployment	systemd + nginx on Debian

Quick Start (Development)

# 1. Clone & setup backend
cd backend
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 2. Configure
cp .env.example .env
# Edit .env with your API keys, database URL, and admin password

# 3. Run
uvicorn app.main:app --reload
# Open http://localhost:8000

Production Deployment (Debian)

# Prerequisites: PostgreSQL and nginx already installed
sudo bash deploy/setup.sh

# Then edit the .env file:
sudo nano /opt/fluentgerman/backend/.env

# Restart after config changes:
sudo systemctl restart fluentgerman

Project Structure

├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI entry point
│   │   ├── config.py            # Environment-based settings
│   │   ├── database.py          # Async PostgreSQL setup
│   │   ├── models.py            # User & Instruction models
│   │   ├── schemas.py           # Pydantic request/response
│   │   ├── auth.py              # JWT + bcrypt + dependencies
│   │   ├── routers/             # API endpoints
│   │   └── services/            # LLM, voice, instruction logic
│   ├── tests/                   # pytest async tests
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── index.html               # Login
│   ├── chat.html                # Client chat + voice
│   ├── admin.html               # Admin dashboard
│   ├── css/style.css            # Design system
│   └── js/                      # Modules (api, auth, chat, voice, admin)
└── deploy/                      # systemd, nginx, setup script

Running Tests

cd backend
pip install aiosqlite  # needed for test SQLite backend
python -m pytest tests/ -v

Configuration

All settings via .env file (see .env.example):

Variable	Description
SECRET_KEY	JWT signing key (generate a strong random one)
DATABASE_URL	PostgreSQL connection string
LLM_API_KEY	Your LLM provider API key
LLM_MODEL	Model to use (e.g. gpt-4o-mini, claude-3-haiku-20240307)
VOICE_MODE	api (OpenAI Whisper/TTS) or browser (Web Speech API)

License

Private — All rights reserved.