Ü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.
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.