108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# 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.
|