Files
Speech/docs/architecture.md
T
Eugenius Naumenko 16cceae28a Muttersprache koppeln und russischen A1-Kurs ergänzen
GUI und neue Erklärungen verwenden gemeinsam native_language. Deutsch und
Russisch sind die beiden Muttersprachen; Englisch bleibt die Lernsprache.
Kompatibilitätsfelder werden atomar gekoppelt, widersprüchliche Eingaben
abgewiesen und bestehende Profile sowie eingefrorene Inhalte erhalten.

Ergänzt vollständige russische GUI-Kataloge und 840 geprüfte Aufgabenansichten
in sieben Modulen einschließlich A1-Test, mit getrennten Sprachrollen für
Ausgangs- und Lernmaterial. Äquivalente Ansichten teilen ihre Nachweisidentität.
Stabile API-Fehlercodes, neue deterministische Hilfen und Trainingsbegründungen
berücksichtigen die Muttersprache. Dokumentiert das Sprachmodell in AGENTS.md.

Validierung: Go-Race-Suite mit eigener lokaler PostgreSQL-Testdatenbank, go vet,
Web-Build, Offline-Bank-/Variantenaudit, Diff-Prüfung sowie lokale Browser-Smokes
für Sprachen, Kurs, Administration, Aussprache und Aufnahme. Keine Live-Anbieter,
Produktionsprofile, Deployment-Schritte oder historischen Neubewertungen.
2026-11-07 17:02:17 +00:00

69 lines
3.6 KiB
Markdown

# 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, generated exercises, attempts, progress, Azure calls, and Flowise calls.
Flowise owns the first version of the lesson logic: when the dashboard or `POST /lessons/next`
needs the next task, the API sends profile/progress context to Flowise with a stable
`sessionId`. Flowise returns one exercise JSON object. The API stores that exercise in PostgreSQL
for the current user and returns it to the frontend. If Flowise is unavailable or returns invalid
JSON, the API falls back to seeded A1 exercises. Feedback and the simple conversation screen stay
local backend behavior in this first Flowise-generation phase.
Important boundaries:
- `httpapi`: request/response handling.
- `services`: auth, Azure Speech, Flowise teacher logic.
- `store`: PostgreSQL schema, seed data, generated exercise persistence, repositories.
- `domain`: shared API/domain structs.
## Multilingual Design
There are exactly two roles: native language (interface and explanations together)
and target/learning language. Native catalogs are German and Russian; the complete
A1 learning course remains English. See [README](../README.md#mehrsprachigkeit).
`users.native_language` is canonical. Legacy `ui_language` and
`instruction_language` fields are coupled aliases protected by a database check.
Registration and preferences reject conflicting aliases. Partial profile updates
preserve the active target, level and goal in one transaction. Migration derives
the initial native preference from supported legacy UI values, otherwise German.
Stored task snapshots, job locales, attempts, audio and feedback remain unchanged.
Typed frontend catalogs cover all controls, formatting and Russian plural forms.
Transient messages retain translation keys; API errors expose stable codes.
Technical provider diagnostics stay original data. A native switch updates labels
without clearing answers, unsaved fields or an active recording.
All 840 German base tasks have reviewed Russian presentations across seven modules
and six skills, including the twelve-question internal exam. Each presentation
separates instruction, stimulus role/language, option role/language and private
reference-answer language. English target media and answer IDs remain unchanged;
vocabulary meanings and short-writing source sentences are Russian. Combined
`prompt` is retained for compatibility. Module labels come from reviewed packages.
Each Russian translation shares its base canonical identity. Frozen assignments
retain variant ID, revision and the earliest owned evidence identity. Distinct-task
counts and new scripted speech observations use the shared identity; attempts and
historical observations are not rewritten. Reviewed exam assignments also retain
these fields. Model outputs cannot declare server-owned evidence metadata.
`course_v2_jobs.instruction_language` captures native language when enqueued;
retries/replays retain it. Existing English pilot variants are retired, not deleted
from databases. Missing packages fail explicitly rather than selecting German
reserves. Offline authored sources, checksum-bound review and audits accompany the
840 Russian translations. New target languages require separate complete course
packs and verified speech capabilities. No provider profile or budget is activated.