# 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 React components in `src/`, with extraction when `App.tsx` becomes hard to review.
- Keep pure domain logic in `src/lib/`.
- Keep shared contracts in `src/types/`.
- Keep generated outputs in `dist/`, `dist-electron/`, and `outputs/`.

## UI Rules

- The scan page should prioritize the capture workspace over secondary status content.
- Details and debug information belong in modals or secondary panels.
- Avoid long, overfilled cards on scanner pages.
- 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.

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