# 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)

```bash
# 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)

```bash
# 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

```bash
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.