imexrps/AGENTS.md

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.

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:

npm run build
npm run build:electron

For Electron package or builder changes:

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:

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.