Files
Speech/docs/architecture.md
T
Eugenius Naumenko f3d42ee2b6 Mehrsprachige Bedienung und versionierte Aufgabenvarianten einführen
Übersetzungskataloge, getrennte Sprachpräferenzen und einen versionierten Aufgabenpilot ergänzen. Historische Aufgaben und Bewertungen bleiben erhalten; äquivalente Ansichten teilen Nachweise. Lokal mit Race-Tests und PostgreSQL, Vet, Web-Build, Bank-Audits und Browser-Fixtures geprüft. Dieser Stand dient als Ausgangspunkt für die anschließend beauftragte Zusammenführung zur Muttersprache.
2026-11-07 16:26:26 +00:00

5.0 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

The current multilingual rollout is described in README.md. The runtime description above documents the historical Flowise integration; current runtime uses the Go course bank and optional direct model APIs.

The React interface uses typed translation keys in src/i18n/I18n.tsx with German and English catalogs. Only static interface text is translated. Server content, learner answers, target texts and historical feedback are not passed through a blanket translator. Both course renderers, recording controls, conversation, administration, AI settings and diagnostics now use the same catalogs as authentication, navigation, dashboard and progress. Action and skill labels live in src/i18n/labels.ts, outside API clients. Local transient messages use useLocalizedMessage to retain keys and parameters across interface switches; API error strings and historical feedback remain original data.

The document language follows the selected interface language. Learning-language text retains its own lang/dir attributes; known curated task prompts retain German. Dates, counts and USD cost formatting use the selected UI locale without changing stored values. Switching the UI updates labels in place, preserving answers, unsaved form fields and active recording state. Current backend errors still need a future stable-code contract for full localization.

The API distinguishes the user's interface preference (ui_language) from the preferred explanation language (instruction_language) and the learner profile's target_language. Model input contracts still name the explanation language ui_language for compatibility, but receive instruction_language from the account. A UI-only PATCH preserves the active learning profile atomically.

Reviewed task variants now cover a twelve-task English-explanation pilot in the introductions module. instruction, a typed stimulus (target/source/context), option language/role and reference-answer language describe the new presentation. The original prompt remains for compatible clients and historical tasks. variant_id, content_revision and canonical_task_id are frozen in each assigned task. Curated German base entries remain unchanged. Module display labels can be derived from the reviewed variant package without modifying stored course packs.

Nine equivalent translations share their base canonical identity. Three adapted vocabulary/writing exercises use separate identities because same-language identity translations would disclose the answer. A frozen presentation uses the earliest existing assignment as its internal evidence_task_id; new equivalent variants reuse that identity for distinct-task counts and scripted pronunciation grouping. Historical snapshots and pronunciation records are not rewritten. Model outputs cannot declare these server-owned metadata fields.

course_v2_jobs.instruction_language captures the preference when enqueued, including idempotent request replays. Availability and inventory are scoped to target language, course version and explanation language. Unsupported bank variants raise an explicit error instead of falling back to a German reserve. Existing German exams remain resumable; new English exams are unavailable until the whole required bank coverage is reviewed. course_variant_unavailable is the first stable API error code translated by the frontend; other errors remain original.

Variant sources, build and audits are offline. Their own checksum-bound review and manifest are separate from the 840-entry baseline. Each additional language pair needs editorial review, including distractors, visible requirements and equivalence classification. New target languages also require complete course packs and verified speech capabilities; adding an interface catalog cannot enable them.