# Semantic Contracts: LLM Table Translation Service

**Feature Branch**: `028-llm-datasource-supeset`  
**Date**: 2026-05-17 (updated to match implementation)  
**Protocol**: GRACE-Poly v2.6

---

## Backend Contracts (Python / FastAPI)

### [DEF:TranslatePlugin:Module]
`backend/src/plugins/translate/plugin.py`
@COMPLEXITY 2
@PURPOSE Plugin entry point implementing PluginBase for the translation service. Serves as registration artifact for plugin_loader auto-discovery. All business logic delegated to independent service classes.
@RELATION INHERITS -> [PluginBase:Class]
@RATIONALE Separate plugin avoids bloating LLMAnalysisPlugin beyond fractal limit (<400 lines). C2 because plugin.py is a registration skeleton; all execution logic lives in service classes.
@REJECTED Extending LLMAnalysisPlugin would conflate two distinct feature domains (dashboard validation vs table translation). Executing business logic through PluginBase.execute() was rejected in favor of service-layer architecture for testability and route flexibility.
[/DEF:TranslatePlugin:Module]

### [DEF:TranslationOrchestrator:Class]
`backend/src/plugins/translate/orchestrator.py`
@COMPLEXITY 5
@PURPOSE Central coordinator for translation run lifecycle: validates preconditions, manages preview quality gate, dispatches to executor, generates safe SQL, submits to Superset SQL Lab API, manages retry, records events, enforces retention.
@PRE Job configuration is saved and valid. Superset datasource is accessible. LLM provider is configured and reachable. For manual runs: preview session must be accepted. For scheduled runs: at least one prior successful manual run exists.
@POST TranslationRun created with translation_status and insert_status. INSERT SQL generated (safe dialect) and submitted to Superset `/api/v1/sqllab/execute/`. Superset query reference recorded. Structured events recorded for all lifecycle transitions.
@SIDE_EFFECT Creates TranslationRun, TranslationBatch, TranslationRecord, TranslationEvent, MetricSnapshot rows. Calls LLM provider API (token consumption). Calls Superset SQL Lab API.
@DATA_CONTRACT Input: TranslationJob (config snapshot) + datasource rows → Output: TranslationRun (result) + Superset query reference
@INVARIANT A run must transition through states: pending → running → (completed|partial|failed|cancelled|skipped). insert_status transitions: not_started → (submitted → running → succeeded|failed | skipped). No other state transitions allowed. Snapshot isolation: in-progress runs use config snapshot; config edits affect future runs only.
@RELATION CALLS -> [TranslationPreview:Class]
@RELATION CALLS -> [TranslationExecutor:Class]
@RELATION CALLS -> [SQLGenerator:Class]
@RELATION CALLS -> [SupersetSqlLabExecutor:Class]
@RELATION CALLS -> [TranslationEventLog:Class]
@RELATION CALLS -> [LLMProviderService:Module]
@RELATION CALLS -> [SupersetClient:Module]
@RATIONALE Centralized orchestrator is needed because preview gating, execution, SQL generation, Superset API submission, event logging, and retry share state (run_id, config snapshot) and must coordinate within a single transaction boundary for consistency.
@REJECTED Distributed actor model (Celery tasks per batch) was rejected because it introduces eventual-consistency challenges for run status tracking without proportional benefit at the expected scale. Synchronous batch processing provides simpler debugging and deterministic retry. UPDATE statements are never generated — all modifications use INSERT/UPSERT per PostgreSQL dialect.
[/DEF:TranslationOrchestrator:Class]

### [DEF:TranslateJobService:Class]
`backend/src/plugins/translate/service.py`
@COMPLEXITY 4
@PURPOSE Central service layer for job CRUD, inline corrections with context capture, and bulk find-and-replace operations. Coordinates between routes, dictionary manager, and event log.
@PRE Job configuration is saved and valid. For corrections: run record must exist with translated values.
@POST Job CRUD operations reflected in database. Inline corrections create/update DictionaryEntry with context_data, usage_notes, origin tracking. Bulk find-and-replace updates TranslationLanguage.final_value for matched rows.
@SIDE_EFFECT Creates/updates DictionaryEntry rows. Updates TranslationLanguage.final_value. Logs correction events.
@RELATION CALLS -> [DictionaryManager:Class]
@RELATION CALLS -> [TranslationEventLog:Class]
@RELATION CALLS -> [ContextAwarePromptBuilder:Class]
@RELATION CALLS -> [BulkFindReplaceService:Class]
@RATIONALE C4 warranted because service coordinates multiple domains (jobs, corrections, bulk operations) with stateful side effects and origin tracking.
[/DEF:TranslateJobService:Class]

### [DEF:TranslationPreview:Class]
`backend/src/plugins/translate/preview.py`
@COMPLEXITY 4
@PURPOSE Fetch a configurable sample of source rows (1-100), send to LLM with configured context and per-batch filtered dictionary, return per-language translations side-by-side for quality gate. Creates persistent PreviewSession and PreviewRecord rows. Supports multi-target: single LLM call for ALL target languages.
@PRE Job configuration is saved with target_languages (list, min 1). Datasource is accessible. Sample size configured (default 10, range 1-100).
@POST PreviewSession created with config_hash and dict_snapshot_hash. PreviewRecord rows created with per-language TranslationPreviewLanguage entries. Accepting preview gates full execution. No data persisted to target table. For sample_size >30, cost warning displayed.
@SIDE_EFFECT Calls LLM provider API (token consumption). Creates PreviewSession, PreviewRecord, TranslationPreviewLanguage rows.
@RELATION CALLS -> [LLMProviderService:Module]
@RELATION CALLS -> [SupersetClient:Module]
@RELATION CALLS -> [DictionaryManager:Class]
[/DEF:TranslationPreview:Class]

### [DEF:TranslationExecutor:Class]
`backend/src/plugins/translate/executor.py`
@COMPLEXITY 4
@PURPOSE Process source rows in auto-sized batches through LLM, request translations for ALL target languages in single structured JSON response, parse multi-language results, create per-language TranslationLanguage entries. Features: translation cache via source_hash, preview edit carry-forward, new-key-only filtering, dictionary enforcement post-processing.
@PRE Run exists with translation_status `running`. Source rows fetched. Batch size configured. LLM provider configured.
@POST All processable rows have TranslationRecord + TranslationLanguage entries. Each batch has TranslationBatch record with statistics. Run statistics updated per language via TranslationRunLanguageStats.
@SIDE_EFFECT Calls LLM provider API (token consumption). Creates TranslationBatch, TranslationRecord, TranslationLanguage rows.
@RELATION CALLS -> [LLMProviderService:Module]
@RELATION CALLS -> [DictionaryManager:Class]
@RELATION CALLS -> [ContextAwarePromptBuilder:Class]
[/DEF:TranslationExecutor:Class]

### [DEF:SQLGenerator:Class]
`backend/src/plugins/translate/sql_generator.py`
@COMPLEXITY 3
@PURPOSE Generate safe dialect-appropriate INSERT/UPSERT SQL from TranslationRecord/TranslationLanguage rows, keyed by configured target key columns. Supports PostgreSQL/Greenplum (ON CONFLICT) and ClickHouse (plain INSERT). Pure function — no I/O, no mutation.
@PRE TranslationRecord rows exist with translated/final values. Target table schema validated at configuration time.
@POST Returns a syntactically valid, injection-safe SQL INSERT/UPSERT statement for the detected dialect.
@SIDE_EFFECT None — pure function.
@RELATION CALLS -> [SupersetClient:Module]
@RATIONALE C3 (not C4 as originally planned) because SQLGenerator is a pure function with no state, no I/O, and no external side effects.
[/DEF:SQLGenerator:Class]

### [DEF:SupersetSqlLabExecutor:Class]
`backend/src/plugins/translate/superset_executor.py`
@COMPLEXITY 3
@PURPOSE Submit generated SQL to Superset SQL Lab API `/api/v1/sqllab/execute/` with fallback to `/api/v1/sql_lab/execute/` (underscore variant). Poll `/api/v1/query/{id}` for completion. Supports multiple Superset response formats. Record Superset query reference, status, and error details.
@PRE TranslationRun exists with translation_status completed/partial. SQL is generated and syntactically valid. Superset is accessible.
@POST TranslationRun.insert_status updated (submitted → running → succeeded|failed). Superset query reference, error details, rows_affected stored.
@SIDE_EFFECT Calls Superset API (SQL execution, database write). Updates TranslationRun row.
@RELATION CALLS -> [SupersetClient:Module]
@RELATION CALLS -> [TranslationEventLog:Class]
[/DEF:SupersetSqlLabExecutor:Class]

### [DEF:DictionaryManager:Class]
`backend/src/plugins/translate/dictionary.py`
@COMPLEXITY 4
@PURPOSE CRUD for TerminologyDictionary and DictionaryEntry with language-pair-aware unique constraint `(dictionary_id, source_term_normalized, source_language, target_language)`. CSV/TSV import with conflict detection. Per-batch language-pair-filtered term extraction for LLM prompts.
@PRE Dictionary model exists. User has required permissions.
@POST CRUD operations reflected in database. Filtered term list returned for batch with language-pair matching.
@SIDE_EFFECT Creates/updates/deletes DictionaryEntry rows. May read TranslationRun for origin tracking.
@RELATION CALLS -> [DictionaryEntry:Class]
@RELATION CALLS -> [TranslationJobDictionary:Class]
@RELATION CALLS -> [ContextAwarePromptBuilder:Class]
[/DEF:DictionaryManager:Class]

### [DEF:ContextAwarePromptBuilder:Class]
`backend/src/plugins/translate/prompt_builder.py`
@COMPLEXITY 3
@PURPOSE Construct LLM prompts with context-aware dictionary entries. For entries with has_context=True, render context annotations with format: `"source_term" (context: key=value, ...) → "target_term"`. Compute Jaccard similarity between entry context_data and incoming row context columns to flag priority_context entries (>50% overlap). Cap context rendering at ~500 tokens per entry.
@RELATION DEPENDS_ON -> [DictionaryManager:Class]
@RELATION DEPENDS_ON -> [LLMProviderService:Module]
[/DEF:ContextAwarePromptBuilder:Class]

### [DEF:TranslationScheduler:Class]
`backend/src/plugins/translate/scheduler.py`
@COMPLEXITY 4
@PURPOSE Manage translation job schedules with timezone and concurrency policy support: create/update/delete, register with APScheduler, handle trigger dispatch with skip/queue, enforce new-key-only strategy with baseline_expired fallback (>90 days), failure notification dispatch.
@PRE SchedulerService is running. Job has configuration. For execution bypass: at least one prior successful manual run exists.
@POST Schedule registered with APScheduler or removed. On trigger: new TranslationRun created with trigger_type=scheduled. New-key-only filter applied. On failure: NotificationService called. Schedule remains enabled.
@SIDE_EFFECT Creates TranslationRun rows. Calls SchedulerService. Emits schedule_triggered/skipped/failed events.
@RELATION CALLS -> [SchedulerService:Class]
@RELATION CALLS -> [TranslationOrchestrator:Class]
@RELATION CALLS -> [TranslationEventLog:Class]
@RELATION CALLS -> [NotificationService:Module]
[/DEF:TranslationScheduler:Class]

### [DEF:TranslationEventLog:Class]
`backend/src/plugins/translate/events.py`
@COMPLEXITY 5
@PURPOSE Structured event logging: write immutable events, enforce invariants (exactly one run_started + one terminal event per run), query for audit/dashboard, enforce 90-day retention pruning with MetricSnapshot persistence before deletion.
@PRE TranslationEvent table exists. Event type recognized from VALID_EVENT_TYPES. For run-scoped events: run exists.
@POST Event row created with type-specific payload. Pruning job persists MetricSnapshot, then removes events/records older than 90 days.
@SIDE_EFFECT Creates TranslationEvent rows. Creates MetricSnapshot rows at pruning time. Deletes expired rows.
@DATA_CONTRACT Input: (run_id?, job_id, event_type, payload: dict) → Output: TranslationEvent
@INVARIANT Every created run MUST have exactly one run_started event and exactly one terminal event among: run_succeeded, run_partial, run_failed, run_cancelled, run_skipped. Events are immutable after creation. Cumulative metrics survive pruning via MetricSnapshot.
@RELATION CALLS -> [TranslationEvent:Class]
@RELATION CALLS -> [MetricSnapshot:Class]
@RATIONALE C5 warranted: event log is single source of truth for observability, metrics, and audit. Immutability, retention, and metric continuity invariants must be enforced to prevent data loss or tampering.
@REJECTED stdout-only logging lacks structured payload integrity and cannot enforce terminal-event invariant. Event-sourced metrics without snapshots would lose cumulative data after pruning.
[/DEF:TranslationEventLog:Class]

### [DEF:TranslationMetrics:Class]
`backend/src/plugins/translate/metrics.py`
@COMPLEXITY 3
@PURPOSE Aggregate per-job metrics from live TranslationEvent log AND persistent MetricSnapshot table. For recent data (<90 days): compute from events. For cumulative totals: read latest MetricSnapshot + recent events. Includes per-language breakdown from per_language_metrics JSON.
@RELATION CALLS -> [TranslationEventLog:Class]
@RELATION CALLS -> [MetricSnapshot:Class]
[/DEF:TranslationMetrics:Class]

### [DEF:TranslateRoutes:Package]
`backend/src/api/routes/translate/`
@COMPLEXITY 4
@PURPOSE FastAPI route handlers organized as package with 11 sub-modules: job CRUD (249 строк), run execution (554), run list (225), preview (194), dictionary (391), correction (100), schedule (239), metrics (65), helpers (71). All endpoints enforce RBAC per access-control matrix. Runs execute in background threads with isolated DB sessions.
@RELATION CALLS -> [TranslationOrchestrator:Class]
@RELATION CALLS -> [TranslateJobService:Class]
@RELATION CALLS -> [DictionaryManager:Class]
@RELATION CALLS -> [TranslationScheduler:Class]
@RELATION CALLS -> [TranslationEventLog:Class]
@RELATION CALLS -> [TranslationMetrics:Class]
@RELATION BINDS_TO -> [PermissionChecker:Dependency]
@RATIONALE C4 because routes package spans 11 files, coordinates 6+ service dependencies, and enforces RBAC across 13 permission strings. Split into sub-modules by domain to respect fractal limit (<400 lines per file, except _run_routes.py at 554).
@REJECTED Single translate.py file rejected — would exceed fractal limit at 2 141 lines. Multiple route files with shared state would couple domains.
[/DEF:TranslateRoutes:Package]

### [DEF:TranslateModels:Module]
`backend/src/models/translate.py`
@COMPLEXITY 2
@PURPOSE 15 SQLAlchemy ORM models: TranslationJob, TranslationRun, TranslationBatch, TranslationRecord, TranslationLanguage, TranslationEvent, TranslationPreviewSession, TranslationPreviewRecord, TranslationPreviewLanguage, TerminologyDictionary, DictionaryEntry, TranslationJobDictionary, TranslationSchedule, MetricSnapshot, TranslationRunLanguageStats.
[/DEF:TranslateModels:Module]

### [DEF:TranslateSchemas:Module]
`backend/src/schemas/translate.py`
@COMPLEXITY 2
@PURPOSE 35+ Pydantic v2 request/response schemas for translation API endpoints including multi-language, context-aware, and bulk operations.
[/DEF:TranslateSchemas:Module]

### [DEF:BulkFindReplaceService:Class]
`backend/src/plugins/translate/service.py` (extended)
@COMPLEXITY 3
@PURPOSE Apply find-and-replace across translated values in a completed run. Supports regex or literal patterns, filtered by target language. Generates preview of affected rows before atomic apply. Optionally submits corrections to dictionary with context capture.
@PRE Run must be completed. Pattern must be valid regex (if regex flag set).
@POST All matching cells updated. Optional dictionary entries created with context_source="bulk".
@SIDE_EFFECT Updates TranslationLanguage.final_value. Optionally creates DictionaryEntry rows.
@RELATION DEPENDS_ON -> [InlineCorrectionService:Class]
[/DEF:BulkFindReplaceService:Class]

---

## Frontend Contracts (Svelte 5 / SvelteKit)

### [DEF:TranslateJobList:Component]
`frontend/src/routes/translate/+page.svelte`
@COMPLEXITY 3
@PURPOSE SvelteKit page listing all translation jobs with status/schedule indicators, target languages as badges, create/duplicate/delete actions.
@UX_STATE idle, loading, empty, populated, error
[/DEF:TranslateJobList:Component]

### [DEF:TranslationJobConfig:Component]
`frontend/src/routes/translate/[id]/+page.svelte`
@COMPLEXITY 4
@PURPOSE Tabbed page with Configuration, Preview, Run, and Schedule sections. Multi-language target selection, datasource column mapping, composite key support, LLM provider/dictionary attachment with priority ordering, sample size slider (1-100), inline correction, bulk find-replace.
@UX_STATE idle, loading, configured, saving, validation_error, datasource_unavailable
@UX_REACTIVITY Column list $derived from datasource; dictionary list filtered by target_language; per-language columns in preview/run results
@UX_FEEDBACK Cost warning at sample size >30; per-language statistics on run completion
[/DEF:TranslationJobConfig:Component]

### [DEF:TranslationPreview:Component]
`frontend/src/lib/components/translate/TranslationPreview.svelte`
@COMPLEXITY 4
@PURPOSE Side-by-side per-language preview of source rows with LLM translations, per-language approve/edit/reject, bulk approve, configurable sample size slider, cost estimate card, carry-forward edits to full run.
@UX_STATE idle, loading, preview_loaded, preview_error, accepted, rejected, stale_config
@UX_FEEDBACK Spinner during LLM call; visual distinction for LLM-generated vs user-edited vs "und" warning
@UX_RECOVERY Retry preview; re-fetch with updated config; individual row re-translate
[/DEF:TranslationPreview:Component]

### [DEF:TranslationRunProgress:Component]
`frontend/src/lib/components/translate/TranslationRunProgress.svelte`
@COMPLEXITY 4
@PURPOSE Live progress display: progress bar, per-language batch counter, success/failure counts, cancel button. WebSocket-driven for real-time updates.
@UX_STATE idle, running, cancelling, cancelled, completed, partial, failed, insert_pending, insert_running, insert_failed
@UX_FEEDBACK Per-language progress $derived; real-time batch/insert status
@UX_RECOVERY Retry failed batches; cancel run; download skipped rows as CSV
[/DEF:TranslationRunProgress:Component]

### [DEF:TranslationRunResult:Component]
`frontend/src/lib/components/translate/TranslationRunResult.svelte`
@COMPLEXITY 4
@PURPOSE Completion summary with per-language statistics, Superset execution status/reference, generated SQL (audit/debug), inline feedback-loop correction controls.
@UX_STATE completed, partial, failed, insert_failed
@UX_FEEDBACK Superset execution status badge; per-language statistics section; SQL block for audit
@UX_RECOVERY Retry failed rows; retry insert; submit corrections; bulk find & replace
@RELATION CALLS -> [TermCorrectionPopup:Component]
@RELATION CALLS -> [CorrectionCell:Component]
[/DEF:TranslationRunResult:Component]

### [DEF:CorrectionCell:Component]
`frontend/src/lib/components/translate/CorrectionCell.svelte`
@COMPLEXITY 3
@PURPOSE Inline-editable cell for translation results. Click to edit, shows "Submit to Dictionary" button after edit. Auto-fills language pair from row metadata. Supports context capture and usage notes.
@UX_STATE view, editing, submitting, submitted, error
@UX_FEEDBACK Toast on submit success/error; "Dictionary ✓" badge on corrected rows
@UX_RECOVERY Retry button on submit failure; edit persists locally
@RELATION DEPENDS_ON -> [TranslateApiClient:Module]
@RELATION BINDS_TO -> [translateStore:Store]
[/DEF:CorrectionCell:Component]

### [DEF:BulkReplaceModal:Component]
`frontend/src/lib/components/translate/BulkReplaceModal.svelte`
@COMPLEXITY 3
@PURPOSE Modal for bulk find-and-replace across translated values. Pattern input (regex toggle), target language selection, preview table with "N rows affected", apply with confirmation. Optional "Submit to dictionary with context" with usage notes.
@UX_STATE closed, configuring, previewing, applying, applied, error
@UX_FEEDBACK Preview table showing before/after; counter of affected rows; warning at >50 rows
@UX_REACTIVITY Preview list $derived from pattern + run data
@RELATION DEPENDS_ON -> [TranslateApiClient:Module]
[/DEF:BulkReplaceModal:Component]

### [DEF:TermCorrectionPopup:Component]
`frontend/src/lib/components/translate/TermCorrectionPopup.svelte`
@COMPLEXITY 3
@PURPOSE Popup for submitting corrections: source term (pre-filled), incorrect translation, corrected translation, source language (auto), target language (auto), dictionary selector (filtered by language pair), context_data preview (editable/removable), usage notes textarea. Conflict dialog (overwrite/keep/cancel).
@UX_STATE closed, selecting, editing, submitting, conflict_detected, submitted
[/DEF:TermCorrectionPopup:Component]

### [DEF:BulkCorrectionSidebar:Component]
`frontend/src/lib/components/translate/BulkCorrectionSidebar.svelte`
@COMPLEXITY 3
@PURPOSE Sidebar for bulk correction: collect multiple selected terms across rows, per-term correction inputs, submit all to dictionary atomically.
@UX_STATE closed, collecting, reviewing, submitting, submitted
@UX_REACTIVITY Selected terms list $state
[/DEF:BulkCorrectionSidebar:Component]

### [DEF:ScheduleConfig:Component]
`frontend/src/lib/components/translate/ScheduleConfig.svelte`
@COMPLEXITY 3
@PURPOSE Schedule panel: type selector (cron/interval/once), cron expression with validation, interval input, timezone selector, next-3-executions preview, concurrency policy (skip/queue), enable/disable toggle. Warns if no prior successful manual run.
@UX_STATE idle, editing, validating, enabled, disabled, no_prior_run_warning
@UX_REACTIVITY Next execution times $derived with timezone display
[/DEF:ScheduleConfig:Component]

### [DEF:DictionaryEditor:Component]
`frontend/src/routes/translate/dictionaries/[id]/+page.svelte`
@COMPLEXITY 3
@PURPOSE Inline term editor with per-row language pair: add/edit/delete entries, CSV/TSV import with conflict preview (overwrite/keep), export, context_data + usage_notes display in expandable rows, context_source badges.
@UX_STATE idle, loading, editing, importing, import_preview, import_conflict, saving
[/DEF:DictionaryEditor:Component]

### [DEF:DictionaryList:Component]
`frontend/src/routes/translate/dictionaries/+page.svelte`
@COMPLEXITY 3
@PURPOSE SvelteKit page listing dictionaries with name, term count, attached job count, create/delete actions. Blocks deletion of attached dictionaries.
@UX_STATE idle, loading, empty, populated, delete_blocked
[/DEF:DictionaryList:Component]

### [DEF:TranslationHistory:Component]
`frontend/src/routes/translate/history/+page.svelte`
@COMPLEXITY 3
@PURPOSE Filterable run history: datasource, target table, per-language row counts, translation_status, insert_status, date, user. Detail view with config snapshot, prompt, per-language translations with edit marks, INSERT SQL, Superset execution reference. Pruned runs show metadata only with "data unavailable" markers.
@UX_STATE idle, loading, empty, populated, detail_open, pruned
[/DEF:TranslationHistory:Component]

### [DEF:TranslationMetricsDashboard:Component]
`frontend/src/lib/components/translate/TranslationMetricsDashboard.svelte`
@COMPLEXITY 2
@PURPOSE Admin dashboard displaying per-job metrics: run counts, success/failure ratio, cumulative tokens, cumulative cost, average latency, per-language breakdown.
@UX_STATE idle, loading, populated, error
[/DEF:TranslationMetricsDashboard:Component]

### [DEF:TranslationRunGlobalIndicator:Component]
`frontend/src/lib/components/translate/TranslationRunGlobalIndicator.svelte`
@COMPLEXITY 2
@PURPOSE Global indicator showing active translation runs with progress. Polls or WebSocket-driven.
@UX_STATE hidden, active, completed
[/DEF:TranslationRunGlobalIndicator:Component]

### [DEF:TranslateApiClient:Module]
`frontend/src/lib/api/translate.js`
@COMPLEXITY 2
@PURPOSE API client wrapping requestApi/fetchApi for all translate endpoints: jobs, runs, preview, dictionaries, entries, corrections, schedules, metrics, bulk replace.
[/DEF:TranslateApiClient:Module]

### [DEF:translateStore:Store]
`frontend/src/lib/stores/translationRun.js`
@COMPLEXITY 3
@PURPOSE Svelte 5 rune store for translation feature state: run progress, WebSocket connection status, per-language progress.
@RELATION BINDS_TO -> [TranslateApiClient:Module]
@RELATION BINDS_TO -> [TaskWebSocket:Module]
[/DEF:translateStore:Store]

---

## Integration Contracts (Existing System — Reused)

| Contract ID | What It Provides | How Translation Uses It |
|-------------|-----------------|------------------------|
| `[LLMProviderService:Module]` | LLM API call with provider selection, key encryption, retry/fallback | Sends batches with constructed prompts; receives structured JSON translations for all target languages |
| `[SupersetClient:Module]` | Superset API: datasource schema, SQL Lab execution, column metadata | Fetch column metadata, submit SQL to `/api/v1/sqllab/execute/`, poll status |
| `[SchedulerService:Class]` | APScheduler lifecycle, add_job/remove_job, cron/interval/date triggers | Translation schedules registered as APScheduler jobs; load_schedules discovers active TranslationSchedule rows |
| `[NotificationService:Module]` | Email/Telegram/Slack notification dispatch | Scheduled run failure notifications with job name, failure reason, run link |
| `[PermissionChecker:Dependency]` | FastAPI dependency for RBAC enforcement with ownership scoping | Route handlers annotated per 13-permission access-control matrix |
| `[TaskWebSocket:Module]` | WebSocket for real-time task progress streaming | Translation run progress events (per-language) streamed to frontend store |
| `[TaskContext:Class]` | Background task lifecycle context with structured logging | Orchestrator runs as async background task with source-tagged log entries |

---

## Updated Contracts (2026-05-17 — aligned with implementation)

### [DEF:TranslationLanguage:Class]
`backend/src/models/translate.py`
@COMPLEXITY 1
@PURPOSE Per-language translation storage for a TranslationRecord. One row per (record_id, language_code). Fields: language_code, source_language_detected (BCP-47), translated_value, user_edit, final_value, status.
@RELATION DEPENDS_ON -> [TranslationRecord:Class]
[/DEF:TranslationLanguage:Class]

### [DEF:TranslationPreviewLanguage:Class]
`backend/src/models/translate.py`
@COMPLEXITY 1
@PURPOSE Per-language preview results. Mirrors TranslationLanguage structure for preview records.
@RELATION DEPENDS_ON -> [TranslationPreviewRecord:Class]
[/DEF:TranslationPreviewLanguage:Class]

### [DEF:TranslationRunLanguageStats:Class]
`backend/src/models/translate.py`
@COMPLEXITY 1
@PURPOSE Per-language statistics for a translation run: total_rows, translated_rows, failed_rows, skipped_rows, token_count, estimated_cost per language_code.
@RELATION DEPENDS_ON -> [TranslationRun:Class]
[/DEF:TranslationRunLanguageStats:Class]