Initial commit

This commit is contained in:
Eugenius Naumenko
2026-06-07 22:20:57 +00:00
commit a7d8f72129
357 changed files with 168337 additions and 0 deletions
+31
View File
@@ -0,0 +1,31 @@
# Agent Design
## Role
The Flowise agent acts as a precise A1 English teacher for German-speaking adults.
## Inputs
- `target_language`
- `cefr_level`
- current exercise
- Azure scores
- weak words
- recent attempts
## Output
The backend expects valid JSON:
```json
{
"exercise_type": "repeat_sentence",
"target_text": "Hello, my name is Anna.",
"teacher_feedback": "Uebe besonders 'name'.",
"tts_text": "Hello, my name is Anna.",
"ssml": "",
"next_recommendation": "Sprich den Satz noch einmal langsam."
}
```
The agent must not create pronunciation scores. Azure is the scoring source.
+42
View File
@@ -0,0 +1,42 @@
# API
Base URL in local development: `http://localhost:8080`
## Auth
- `POST /auth/register`
- `POST /auth/login`
- `POST /auth/logout`
Successful register/login returns a bearer token. Send it as:
```txt
Authorization: Bearer <token>
```
## Learner
- `GET /me`
- `PATCH /me/preferences`
- `GET /dashboard`
- `GET /progress`
## Languages
- `GET /languages`
- `GET /languages/{code}/voices`
## Lessons and Practice
- `POST /lessons/next`
- `POST /practice/attempts`
`POST /practice/attempts` expects multipart form data:
- `exercise_id`
- `audio`
## Conversation
- `POST /conversation/start`
- `POST /conversation/{id}/turn`
+27
View File
@@ -0,0 +1,27 @@
# Architecture
## Runtime
```txt
React web app -> Go API -> PostgreSQL
-> Redis
-> FlowiseAI
-> Azure Speech
```
FlowiseAI runs as a Docker container on the same VPS and Docker network. The frontend never calls Flowise or Azure directly.
## Backend
The Go API is the system of record. It owns auth, learner profiles, language profiles, exercises, attempts, progress, Azure calls, and Flowise calls.
Important boundaries:
- `httpapi`: request/response handling.
- `services`: auth, Azure Speech, Flowise teacher logic.
- `store`: PostgreSQL schema, seed data, repositories.
- `domain`: shared API/domain structs.
## Multilingual Design
The MVP enables only `en-US`, but every exercise and profile stores `target_language` and `cefr_level`. New languages are added through `language_profiles`, seed exercises, Azure voice settings, and Flowise prompt variables.
+15
View File
@@ -0,0 +1,15 @@
# Data Model
Core tables are created automatically by the Go API at startup:
- `users`
- `learner_profiles`
- `language_profiles`
- `lessons`
- `exercises`
- `attempts`
- `progress_events`
- `conversation_sessions`
- `conversation_turns`
The MVP seeds `en-US` A1 lessons and exercises. Additional languages should be added by inserting a new `language_profiles` row and matching lessons/exercises.
+155
View File
@@ -0,0 +1,155 @@
# Deployment
## VPS Deployment
```bash
docker compose up --build -d
```
Services:
- Web: intern `speech-web:80`, oeffentlich nur ueber Caddy
- API: intern `speech-api:8080`, oeffentlich nur ueber Caddy `/api`
- PostgreSQL: nur internes Docker-Netz
- Redis: nur internes Docker-Netz
- Flowise: vorhandene Instanz ueber `FLOWISE_BASE_URL`
## Lokale Entwicklung
```bash
cp .env.example .env
docker compose -f docker-compose.dev.yml up --build -d
```
Lokale Ports:
- Web: `5173`
- API: `8080`
- Flowise: `3000`
- PostgreSQL: `5432`
- Redis: `6379`
## Production Notes
- Change `APP_JWT_SECRET`.
- Set strong Flowise credentials.
- Restrict exposed database/Redis ports or remove public port mappings.
- Put a reverse proxy with TLS in front of web/API/Flowise.
- Set `AZURE_ENABLE_MOCK=false` only after configuring Azure credentials.
- Add backups for PostgreSQL and Flowise volume.
## VPS mit bestehendem Caddy, CrowdSec und WireGuard
Fuer deinen VPS ist die Default-Variante `docker-compose.yml`. `docker-compose.prod.yml` bleibt als identische explizite Produktionsdatei erhalten.
Annahmen:
- Caddy laeuft bereits in Docker.
- Caddy ist der einzige oeffentliche HTTP/HTTPS-Einstieg.
- CrowdSec + nftables Bouncer schuetzen die oeffentlichen Ports.
- Dein Arbeits-PC ist per WireGuard erreichbar, z. B. ueber `10.8.0.0/24`.
Setup:
```bash
docker compose up --build -d
```
Dann den Inhalt aus `deploy/caddy/speech.Caddyfile` in `/srv/docker/caddy/Caddyfile` einfuegen und Caddy neu laden.
Wichtig:
- `speech-web` und `speech-api` haengen am externen Docker-Netzwerk von Caddy.
- Auf deinem VPS ist das passende Caddy-Netzwerk `web`; setze also `CADDY_DOCKER_NETWORK=web`.
- PostgreSQL und Redis haben keine Host-Port-Freigabe.
- Die API ist nur ueber `https://speech.v2202510301049387828.goodsrv.de/api` erreichbar.
- Flowise wird standardmaessig wiederverwendet: `FLOWISE_BASE_URL=http://flowise:3000`.
- Wenn dein Caddy-Netzwerk anders heisst, `CADDY_DOCKER_NETWORK` in `.env` anpassen.
Das echte Caddy-Netzwerk findest du auf dem VPS mit:
```bash
docker inspect caddy-caddy-1 --format '{{json .NetworkSettings.Networks}}'
```
Bei dir stehen `monitoring_default` und `web`. Fuer Speech nimm `web`:
```env
CADDY_DOCKER_NETWORK=web
```
Wenn der Flowise-Hostname im Caddy-Netzwerk nicht `flowise` ist, pruefen:
```bash
docker inspect flowise-main --format '{{json .NetworkSettings.Networks}}'
```
Dann `FLOWISE_BASE_URL` entsprechend setzen, z. B.:
```env
FLOWISE_BASE_URL=http://flowise-main:3000
```
Wegen deiner laufenden Container werden in der Produktions-Compose bewusst keine Host-Ports fuer Speech veroeffentlicht. Dadurch gibt es keine Kollision mit:
- Caddy: `80`, `443`
- Grafana: `127.0.0.1:3000`
- Prometheus: `127.0.0.1:9090`
- Adminer: `10.8.0.1:8080`
- Gitea SSH: `2222`
- Qdrant: `6333-6334`
- vorhandenen PostgreSQL/Redis/Flowise-internen Ports
Falls du doch eine dedizierte Flowise-Instanz fuer Speech willst:
```bash
docker compose -f docker-compose.yml -f docker-compose.flowise.yml up --build -d
```
Auch diese Variante publiziert keine Host-Ports.
Empfohlen fuer dein bestehendes Flowise: Ersetze den vorhandenen `flowise.v220...` Caddy-Block optional durch `deploy/caddy/flowise-wireguard-only.Caddyfile`, damit Flowise nur noch ueber WireGuard erreichbar ist.
Minimaler Caddy-Reload:
```bash
docker exec caddy caddy validate --config /etc/caddy/Caddyfile
docker exec caddy caddy reload --config /etc/caddy/Caddyfile
```
## Debugmodus
Der Debugmodus wird ueber `.env` gesteuert:
```env
DEBUG_ENABLED=true
DEBUG_VERBOSE=false
LOG_LEVEL=debug
```
Nach einer Aenderung muss die API neu erzeugt/gestartet werden:
```bash
docker compose up -d --force-recreate speech-api
```
Debug ist nur fuer eingeloggte Nutzer erreichbar. Die Frontend-Navigation zeigt dann einen Punkt `Debug`. Die API-Endpunkte liegen intern unter:
- `/api/debug/status`
- `/api/debug/db`
- `/api/debug/flowise`
- `/api/debug/azure`
- `/api/debug/runtime`
Wieder deaktivieren:
```env
DEBUG_ENABLED=false
LOG_LEVEL=info
```
Danach erneut:
```bash
docker compose up -d --force-recreate speech-api
```
+32
View File
@@ -0,0 +1,32 @@
# Product Blueprint
## MVP
The MVP is an A1 English pronunciation and speaking trainer for German-speaking adults.
Core loop:
1. User logs in.
2. App selects the next A1 sentence.
3. User records audio.
4. Backend sends audio to Azure Speech or mock scorer.
5. UI shows word-level visual feedback.
6. Flowise teacher returns short German feedback and the next action.
## Learning Concepts
- Short daily sessions.
- Word-level color feedback.
- Repetition of weak words.
- A1 roleplays.
- Teacher agent with strict CEFR constraints.
- Progress dashboard with average score and weak words.
## Later Extensions
- Real mobile app or PWA.
- More target languages.
- Native audio pipeline with WAV conversion.
- Payment/subscription.
- Teacher/admin dashboard.
- More detailed phoneme UI.