Files
Speech/docs/architecture.md
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

3.6 KiB

Architecture

Runtime

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.

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.