Ü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.
90 lines
5.0 KiB
Markdown
90 lines
5.0 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
|
|
|
|
The current multilingual rollout is described in [README.md](../README.md#mehrsprachigkeit).
|
|
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.
|