LinguaGacha Documentation

LinguaGacha follows a design philosophy described as a "Quiet Local Alchemist" (安静的本地炼金台). The UI is designed to feel like a reliable native desktop application, prioritizing high information density, compact controls, and a stable workspace for translation, configuration, and file processing.

Key Design Principles:

• Native Desktop Priority: Uses fixed shells, sidebars, workspace boundaries, and immediate feedback.
• Color Strategy: Uses a cool gray light theme by default (with a matching dark theme). Warm orange (primary) is used sparingly for main actions, selection, focus, and progress to maintain a subtle, professional feel.
• Information Density: High density with compact controls, optimized for tables and editors.
• Decoration with Purpose: Visual elements must serve status, selection, hierarchy, editability, or task feedback.

Implementation Note: Global tokens and theme entry points are located in src/frontend/index.css. Basic controls are handled in src/frontend/shadcn/. Widgets, features, and pages should consume these tokens rather than defining their own visual styles.

The LinguaGacha backend is structured around a set of authoritative boundaries that define how data is stored, how tasks are executed, and how the frontend communicates with the system.

Key architectural components include:

• ApiGatewayServer: The single entry point for all /api/* routes in the Electron runtime. It uses register_api_routes to bind paths to BackendServices.
• State Ownership: Different services own specific parts of the system state (e.g., AppSettingService for settings, ProjectSessionState for loaded projects, and TaskRuntime for active tasks).
• Project Storage: Data is stored in .lg files using a structured format containing sections like project, files, items, quality, prompts, analysis, and proofreading.
• Task Execution: Tasks are managed by TaskService and executed via TaskEngine, utilizing workers for LLM orchestration and heavy computations.
• Database: ProjectDatabase provides a typed interface for interacting with .lg files, managing SQLite transactions and Zstd-compressed assets.

LinguaGacha operates through a unified backend architecture shared by both the GUI (Electron) and the CLI.

Core Components

• src/index.ts: The single product entry point. It dispatches to either the GUI or CLI based on the --cli flag. It handles application roots and BackendWorkerExecution but does not hold business services or window states.
• BackendBootstrap: The authority for process resource lifecycles. It manages the start and stop sequences.
• BackendServices: The composition root used by both GUI and CLI to assemble shared services. It includes the TaskEngine and is used by the Gateway and CLI jobs.
• Gateway: A component enabled in GUI mode to handle requests. In CLI mode, the Gateway is disabled, and the CLI consumes typed services and task snapshot subscriptions directly.

Lifecycle and Shutdown Order

When the application (GUI or CLI) exits, BackendBootstrap ensures a fixed shutdown sequence to prevent data loss or resource leaks. If a step fails, the subsequent release steps are still executed:

1. Gateway: Stops accepting requests and drains existing ones.
2. BackendServices: Waits for active tasks and workers to complete.
3. System Proxy
4. ProjectDatabase
5. LogManager

Execution Model

• Production: Backend workers are configured to run as worker_threads.
• Development/Testing: in_process execution is permitted only for explicit testing or source code runs and is not used as a fallback for failures.

The CLI operates using a transient project model to ensure isolation and cleanliness:

1. Isolation: Each job uses a dedicated temporary .lg project.
2. Configuration Overrides: The CLI explicitly overrides several settings for the duration of the job:
   • Source and target languages.
   • Whether to open the output directory upon completion.
   • It disables default presets for glossaries, text protection, pre/post-replacement, and translation/analysis prompts. Only the resources explicitly provided via command-line arguments are used.
3. Persistence: Settings not explicitly overridden by the CLI (such as models, concurrency, prompt enhancement, pre-filtering, and export settings) are inherited from the current application settings.
4. Cleanup: Regardless of whether the job succeeds, fails, or the export fails, the CLI automatically uninstalls the project, revokes transient settings, and deletes the temporary directory.

The DesktopStateProvider serves as the shared state entry point for the main window. It manages:

• Project identity
• Tasks
• Settings
• Event streams
• Write results

Note: The Log window does not start this runtime; it only reads the language and consumes the log stream.

State Synchronization Rules:

• Project Identity: Guarded by path + epoch + phase. This identity applies to project switching, re-initialization at the same path, late events, and transient events during initial load.
• Settings: Synchronized only via backend payloads.
• Tasks: Synchronized only via backend snapshots or command acknowledgments (ack).
• Project Identity: Synchronized only via backend project payloads.
• Task Snapshotting: TaskSnapshotStore caches full backend task snapshots using run_revision to discard old values. DesktopRefreshScheduler only retains the highest revision; identical revisions allow late snapshots to overwrite based on type.

The color system uses a palette of cool blue-grays for work surfaces and low-frequency warm oranges for emphasis. Dark mode maps these same semantics to deep graphite surfaces.

Color Categories

• Primary: Warm orange (colors.primary) for main buttons, current navigation rails, selected rows, and progress. Used sparingly. Focus is indicated by colors.ring.
• Secondary: Cool gray (colors.secondary) for secondary buttons, segmented controls, and toolbar partitions.
• Tertiary (Charts): Amber (chart-amber), Coral (chart-coral), and Slate (chart-slate) for statistics and project file categories.
• Status: Success (success), Warning (warning), and Failure (failure). These are strictly for status and must not be used for general decoration.
• Neutral: Includes background, foreground (graphite), cards/popovers (near-white), muted surfaces (foggy gray), and borders (soft cool gray).

Named Design Rules

• The Cool Desktop Rule: Neutral grays must maintain a slight blue-gray tone. Avoid pure black, pure white, or high-saturation cool blues.
• The Icon Glow Scarcity Rule: Warm orange is reserved for primary actions, selection, focus, and progress. Large areas of orange break the design intent.
• The Status Honesty Rule: Success, Warning, and Failure colors are reserved exclusively for status expression.
• The Scoped Exception Rule: Model provider brand colors or CodeMirror syntax colors may exist within their own boundaries but must not be promoted to global emphasis colors.

Tasks (like translation or analysis) are managed through a lifecycle that ensures state consistency.

Starting a Task

To start a task, you must provide the expected_section_revisions required by the TaskService for that specific task type and scope. Once the ProjectOperationGate is acquired, the system enters a busy state.

Monitoring Task Progress

Task status is communicated through snapshots. TaskRuntime.build_snapshot combines:

• In-memory state: status, busy, run_revision, and request pressure.
• .lg metadata: progress and analysis candidate count.

Task Execution Model

• TaskEngine: Orchestrates the task lifecycle and command execution.
• Workers:
  • Work-unit workers: Handle prompt construction, runners, pipelines, and response processing.
  • Planning workers: Handle calculation during the planning phase.
  • BackendWorkerClient: Used for heavy, stateless computations that do not require database or project cache access.
• Concurrency: Actual LLM concurrency is determined by model key leases and limiters, not by the number of threads.

Typography is designed to support scanning and operation, avoiding "web-style" oversized headings. The primary font is LGMono, which provides a code-editor aesthetic for paths, model names, terms, logs, and table numbers. It falls back to LGBaseFont and system fonts for Chinese readability.

Font Hierarchy

Named Design Rules

• The Tool Text Rule: Typography must serve scanning and operation. Avoid large promotional headings or decorative display fonts in the workspace.
• The Production Spacing Rule: Keep letter spacing restrained for standard text. Only allow deviations for statistical numbers, titles, or special editor characters.