imexrps/.ai/architecture.md

Architecture

Process Model

ImEX RPS has two main runtimes:

• Electron main process: window lifecycle, native menus, file system access, estimate decoding, file watching/scanning, audit file dialogs, updater, app-level settings, analytics, and IPC.
• React renderer process: UI, routing, Redux state, Apollo GraphQL operations, Firebase auth, and renderer-side IPC listeners.

The renderer does not get Node integration. The preload script exposes a controlled bridge:

• window.ipcRenderer.send(channel, data)
• window.ipcRenderer.on(channel, handler)
• window.ipcRenderer.invoke(channel, data)
• window.ipcRenderer.removeAllListeners(...)
• window.logger.*

Entrypoints

Electron:

• electron/main.js decides whether to run the source main file or bundled dist-electron/main.cjs.
• electron/main-src.js is the main source file.
• electron/preload.js decides whether to run the source preload or bundled dist-electron/preload.cjs.
• electron/preload-src.js exposes IPC/logger bridges.
• scripts/build-electron.mjs bundles main/preload outputs.

Renderer:

• src/index.jsx initializes Sentry renderer, Redux Provider, MemoryRouter, PersistGate, and <App />.
• src/App/App.jsx initializes Apollo, AntD context/theme, auth session check, IPC side effects, and authorized/unauthorized routing.
• src/components/pages/routes/routes.page.jsx renders the main app shell and routes.

Routing

Routes are memory-router routes because this is an Electron app:

• / Jobs
• /settings Settings
• /reporting Reporting
• /audit Audit
• /scan Scan
• /admin Admin

The app shell includes the side menu, notifications modal, release notes, and update manager.

Redux Shape

Store setup:

• src/redux/store.js
• Redux core legacy_createStore
• Saga middleware
• Redux logger in development
• Redux DevTools compose if present
• redux-persist wrapper with all active reducers currently blacklisted

Reducers:

• application: watcher status, watched paths, selected job id, selected target percent, settings, update state, release notes, estimate scrubber results.
• user: current user, bodyshop, targets, fingerprint, auth errors, notifications, dark mode.
• reporting: report date range, report rows, scorecard, audit data/errors/loading, excluded ids, cached jobs.
• scan: scan loading state, last scanned, estimate list.

Sagas:

• applicationSagas
• userSagas
• reportingSagas
• scanSagas

Data Flow for Estimate Import

1. User configures filePaths in settings.
2. Electron store persists those paths.
3. electron/file-watcher/file-watcher.js watches paths with chokidar.
4. New/changed estimate files are decoded by electron/decoder/decoder.js.
5. Main process sends decoded payloads over IPC.
6. Renderer src/ipc/ipc-renderer-handler.js receives decoded estimates.
7. Renderer GraphQL helper UpsertEstimate writes jobs/joblines to Hasura.
8. Jobs UI queries data back through Apollo.

Data Flow for Job Details

1. A list item dispatches selected job id to Redux application.
2. jobs-detail.organism.jsx debounces selected id briefly to avoid rendering a stale/partial left panel.
3. Apollo queries QUERY_JOB_BY_PK.
4. Detail subcomponents render job metadata, joblines, targets, group controls, claims clerk, estimate scrubber, and other actions.

IPC Contract

IPC channel names live in src/ipc.types.json, imported by:

• src/ipc.types.js for ESM renderer code.
• src/ipc.types.commonjs.js for CommonJS Electron code.

When adding IPC:

• Add channel names to src/ipc.types.json.
• Register main handlers in the relevant Electron module.
• Register renderer listeners in src/ipc/ipc-renderer-handler.js or a local component effect.
• Keep handlers idempotent when possible; repeated imports/listeners can create duplicate events.