Initial commit
This commit is contained in:
@@ -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
@@ -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`
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
```
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user