# ImEX RPS Agent Guide

This file is the first stop for coding agents working in this repository. It is intentionally practical: read this before changing code, then use the deeper files in `.ai/` when you need more context.

## Project Snapshot

ImEX RPS is an Electron desktop app with a Vite/React renderer. It is used by body shops to import, inspect, report on, and audit repair estimate data. The app reads estimate files from configured local folders, decodes DBF-based estimate data in the Electron main process, stores jobs/joblines in Hasura/Postgres through GraphQL, and presents workflows for jobs, reporting, scanning, settings, admin work, audits, and estimate scrubbing.

Primary technologies:

- Electron 42, electron-builder 26, Vite 6, React 18
- Ant Design 5
- Redux 5, redux-saga, redux-persist, reselect
- Apollo Client 3 against a Hasura GraphQL endpoint
- Firebase authentication
- Sentry Electron 7
- Hasura metadata and SQL migrations under `hasura/`

## Fast Start

Use npm scripts, not the stale yarn commands in `README.md`.

```powershell
npm install
npm run dev
```

Useful scripts:

- `npm run start` starts Vite on `http://localhost:3006`.
- `npm run electron` starts Electron.
- `npm run dev` runs Vite and Electron together with `concurrently`.
- `npm run build` builds the renderer to `build/`.
- `npm run build:electron` bundles `electron/main-src.js` and `electron/preload-src.js` into `dist-electron/`.
- `npm run pack` performs a local unpacked electron-builder package check with `--publish never`.
- `npm run distp` publishes. Do not run it unless the user explicitly asks to publish.
- `npm run distnopublish` builds a distributable with publish disabled.

Expected local runtime:

- Node must satisfy Electron 42 requirements. At the time of the upgrade, Node 22.22.1 was used successfully.
- `VITE_APP_GRAPHQL_ENDPOINT` must be available in the renderer environment.
- Firebase config lives in `src/firebase/firebase.utils.js`.
- Electron dev mode loads `http://localhost:3006`; packaged mode loads `build/index.html`.

## Important Safety Rules

- Do not publish releases unless the user explicitly says to publish.
- `npm run pack` is safe for local packaging checks because it includes `--publish never` and uses `electron-builder.pack-check.cjs`.
- `dist-electron/`, `build/`, and `dist/` are generated artifacts and are ignored. Do not manually edit them.
- Do not commit local secrets. The repo contains legacy-sensitive assets such as `certificate.p12`, deployment notes, and Sentry/Firebase/AWS-related configuration. Treat them carefully.
- Avoid broad refactors. This project has older patterns and domain-heavy workflows; make narrow changes and preserve behavior.
- Be careful with Electron main/renderer boundaries. Renderer code should use the exposed preload bridge on `window.ipcRenderer`; main-process code should register IPC handlers under `electron/`.

## Architecture Map

Renderer entry:

- `src/index.jsx` wires Redux, redux-persist, `MemoryRouter`, Sentry renderer, and `<App />`.
- `src/App/App.jsx` wires Apollo, AntD `ConfigProvider`, AntD `App`, auth session check, IPC setup, and authorized/unauthorized routing.
- `src/components/pages/routes/routes.page.jsx` defines app pages: jobs, reporting, audit, scan, settings, admin.

Electron entry:

- `electron/main.js` chooses source vs bundled Electron main file.
- `electron/main-src.js` is the source of truth for main-process window creation, Sentry main, auto-updater, app menu, DevTools behavior, and global IPC initialization.
- `electron/preload-src.js` exposes `window.ipcRenderer` and `window.logger`.
- `electron/ipc-main-handler.js` registers shared IPC channels and imports file watcher, file scan, audit, decoder, and estimate scrubber handlers.
- `scripts/build-electron.mjs` produces `dist-electron/main.cjs` and `dist-electron/preload.cjs`.

State/data:

- `src/redux/store.js` still uses Redux core with `legacy_createStore` to avoid Redux's visual createStore deprecation.
- Root reducers: `application`, `user`, `reporting`, `scan`.
- Sagas coordinate auth, user/shop setup, reporting, scanning, and application actions.
- `src/graphql/GraphQLClient.js` sets Apollo auth, retry, Sentry, logger, error links, and cache field policies for `jobs` and `search_jobs`.
- GraphQL operations live in `src/graphql/*.queries.js`.

Domain logic:

- `electron/decoder/decoder.js` decodes estimate files and applies MPI/SGI/ruleset logic.
- `electron/file-watcher/` watches configured estimate folders.
- `electron/file-scan/` scans configured folders for estimates.
- `electron/audit/` reads audit spreadsheets.
- `electron/estimate-scrubber/` sends estimate JSON to the external scrubber API and opens/sends report results.
- `electron/claims-clerk/` computes jobline alerts.

## Current Conventions

Frontend:

- Components are organized by atomic-ish folders: `atoms`, `molecules`, `organisms`, `templates`, `pages`.
- File names generally follow `name.type.jsx` and optional `name.type.styles.scss`.
- Use Ant Design 5 APIs. Avoid deprecated props such as `Dropdown overlay`, `Collapse.Panel` children, `expandIconPosition="left/right"`, `RangePicker ranges`, and `Table rowKey` functions that rely on index.
- Use `src/util/antdFeedback.js` for message/notification calls outside React component context. Static AntD `message`/`notification` calls can miss dynamic theme context.
- Keep UI state stable during data transitions. Job detail selection uses a short debounce/skeleton to avoid flashing stale detail content.

Electron:

- `electron-store` v11 is ESM-only. Use `initializeStore()` before modules that read `store`, then access `store` through the proxy exported from `electron/electron-store.js`.
- `electron-context-menu` v4 is ESM-only. Import dynamically in `app.whenReady()`.
- Do not reintroduce circular imports from `electron/main-src.js` into IPC modules. IPC modules should use `BrowserWindow.fromWebContents(event.sender)` or `BrowserWindow.getAllWindows()` where needed.
- Sentry main uses `ipcMode: Sentry.IPCMode.Protocol`; keep this unless deliberately changing Sentry IPC behavior.
- DevTools are enabled in dev and auto-open by default. Set `ELECTRON_OPEN_DEVTOOLS=0` to suppress auto-open. In packaged builds DevTools are opt-in via `ELECTRON_ENABLE_DEVTOOLS=1` and auto-open via `ELECTRON_OPEN_DEVTOOLS=1`.
- React DevTools extension install is opt-in with `ELECTRON_INSTALL_REACT_DEVTOOLS=1`. It can trigger Chromium DevTools protocol noise.

GraphQL/Apollo:

- Default Apollo query/watchQuery fetch policy is `network-only`; do not assume Apollo cache is the source of truth.
- Apollo cache has custom offset merge functions for `Query.jobs` and `Query.search_jobs` to avoid cache replacement warnings during pagination.
- Firebase current user token is attached as `Authorization: Bearer <token>` through `authLink`.

## Recent Maintenance Context

Recent warning/deprecation cleanup included:

- AntD v5 deprecations fixed for Collapse, Dropdown, RangePicker, Table rowKey, and static message/notification usage.
- Redux `createStore` deprecation warning avoided with `legacy_createStore`.
- Apollo cache warning fixed with field policies for `jobs` and `search_jobs`.
- Job detail left-panel flash reduced by debouncing selected job id and using a skeleton.
- Electron circular dependency warnings removed by avoiding `mainWindow` export/import.
- Electron Sentry preload deprecation path avoided with protocol IPC mode.
- Electron package upgrades completed for `electron`, `electron-builder`, `electron-context-menu`, `electron-is-dev`, `electron-store`, and `@sentry/electron`.
- `dist-electron/` is ignored and should remain generated only.

## Verification Expectations

For most renderer/main changes:

```powershell
npm run build
npm run build:electron
```

For Electron package or builder changes:

```powershell
npm run pack
```

Remember: `npm run pack` is configured to avoid publishing. It may still perform local signing of the unpacked executable.

For AntD deprecation checks, if `antd-style` tooling is available:

```powershell
npx antd-style-cli lint src --only deprecated
```

If a command is unavailable, report that clearly and run the nearest reliable build/check instead.

## More Context

- `.ai/project-overview.md`: product/domain summary.
- `.ai/architecture.md`: process, renderer, state, and data architecture.
- `.ai/electron-main.md`: Electron-specific lifecycle, packaging, IPC, and upgrade notes.
- `.ai/frontend.md`: React/AntD/Redux conventions and common UI pitfalls.
- `.ai/data-graphql-hasura.md`: GraphQL, Hasura, auth, cache, and schema notes.
- `.ai/workflows.md`: development, packaging, release, and troubleshooting workflows.
- `.ai/recent-changes.md`: migration and warning cleanup history.
- `.ai/file-map.md`: important files and directories by responsibility.
- `.ai/domain-glossary.md`: project/domain terms used across code and UI.
- `.github/copilot-instructions.md`, `CLAUDE.md`, and `GEMINI.md` all point agents back to this guide.