initial commit

2026-02-12 18:45:10 +01:00
commit be7bbba456
42 changed files with 3767 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,107 @@
+# 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.