genshin-assistant/docs/CONVENTIONS.md

Conventions

This document defines project engineering standards.

Naming

• Use Genshin domain language where it makes behavior clearer: artifact, slot, set, main stat, substat, triage, build.
• Name booleans as predicates such as isScanning, bridgeReady, or isGenshinCandidate.
• Prefer explicit scanner names such as createArtifactCrops over generic names such as processImage.

File Organization

• Keep Electron OS integration in electron/.
• Keep Electron main.ts as composition/wiring. Move durable window, file, helper, capture, OCR, or dev-control responsibilities into named modules under electron/.
• Keep React components in src/, with extraction when App.tsx becomes hard to review.
• Keep feature controller hooks small enough to review. If a hook owns persistence, import/export, entry choreography, scan-loop orchestration, and UI state at once, split those concerns into feature-local hooks or services.
• Keep pure domain logic in src/lib/.
• Keep shared contracts in src/types/.
• Keep generated outputs in dist/, dist-electron/, and outputs/.
• Keep src/styles/global.css as the stylesheet entrypoint. Put broad app styles in base.css and dev/diagnostic-only styling in diagnostics.css unless a more specific style module is introduced.

UI Rules

• The scan page should prioritize the capture workspace over secondary status content.
• The active scan view should read as preview plus compact result rail, not as a dashboard of live diagnostics.
• Details and debug information belong in modals or secondary panels.
• Avoid long, overfilled cards on scanner pages.
• Do not collapse OCR/extraction confidence and artifact value into one ambiguous UI state; uncertain reads should be visibly Review.
• Artifact value pills should be short, stable labels backed by deterministic data, with detailed reasons behind click-through detail.
• The design direction is a premium, cinematic Galaxy system with restrained glass surfaces, semantic contrast, and focused controls; reuse shared tokens instead of feature-local state colors.
• Use skeletons for initial content layout, inline spinners for bounded work, and toasts only for explicit mutation outcomes. Durable progress, blockers, and errors stay in the owning view.
• Respect prefers-reduced-motion, keep focus-visible styling intact, and never rely on color or animation as the only status signal.
• Disable buttons when their required data does not exist.
• Route user-facing renderer copy through src/i18n. English is the default application locale; German is an explicit settings choice. Do not use an app language switch to imply that another Genshin OCR/capture language is supported.
• Keep stable data-* hooks for scripted renderer acceptance. Tests should not depend on localized visible strings when a semantic hook is available.
• A destructive-looking local-data control must say what it removes and state that it does not change Genshin. Require confirmation before local deletion.

Scanner Rules

• Prefer focused crops over full-screen OCR.
• Confidence and raw OCR details must remain inspectable.
• Heuristics should fail safely into unknown fields or review notes.
• Do not add irreversible game actions.
• Treat global aliases as unsafe when the OCR text is ambiguous across pieces. Canonicalize a partial artifact name only when independent high-confidence field evidence, such as a direct slot read, leaves one valid match.
• Keep auto-entry choreography separate from scan-loop execution. Entry code may navigate to a readable artifact detail state; loop code should process verified grid targets.

TypeScript Rules

• Keep strict type checks passing.
• Do not use any for capture, OCR, artifact, or recommendation contracts unless a boundary genuinely requires it.
• Parser functions should be deterministic and testable.

Testing

• Use unit tests for parser and scoring logic.
• Use build/type checks for Electron IPC contract changes.
• Use manual Smart Capture smoke tests for crop and capture changes.
• For native timing claims, validate a complete run-timing.json and derive end-to-end time from one request-to-reconciliation interval. Never add overlapping capture and processing durations.
• Test local native-result removal for active-run blocking, tombstone filtering, raw-evidence preservation, crop-path containment, and exact Store-record scope.

Documentation

• Update docs/PROJECT.md when product scope changes.
• Update docs/ARCHITECTURE.md when module boundaries or flows change.
• Add an ADR to docs/DECISIONS.md for durable technical trade-offs.
• Keep workflow/runbook docs linked from docs/PROJECT.md so future sessions do not depend on chat history.
• Do not store tokens, passwords, cookies, or generated credentials in project files. Use Git Credential Manager for Gitea HTTPS credentials; document only the setup path in docs/GITEA_AUTH.md.