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 dark purple fintech glassmorphism with premium, focused controls.
• Disable buttons when their required data does not exist.

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

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.