imexrps/.ai/frontend.md

Frontend Guide

Stack

• React 18
• Vite 6
• Ant Design 5
• React Router DOM 6 with MemoryRouter
• Redux 5, redux-saga, redux-persist, reselect
• Apollo Client 3
• SCSS modules/files by component where present

Component Layout

Components are organized by a loose atomic design convention:

• src/components/atoms/
• src/components/molecules/
• src/components/organisms/
• src/components/templates/
• src/components/pages/

File naming usually includes the level:

• jobs-detail.organism.jsx
• jobs-list-item.molecule.jsx
• loading-spinner.atom.jsx
• error-boundary.template.jsx
• jobs.page.jsx

Preserve this style for new code.

AntD 5 Rules

Use current AntD 5 APIs:

• Dropdown menu={{ items, onClick }} instead of overlay.
• Collapse items={[...]} instead of Collapse.Panel children.
• expandIconPosition="start" or "end", not "left" or "right".
• DatePicker.RangePicker presets={...} instead of ranges.
• Table rowKey="stableId" or a function using a real stable field; do not rely on the deprecated index argument.
• Prefer AntD App context-aware feedback APIs.

Global feedback:

• Use src/util/antdFeedback.js.
• Import antdMessage/antdNotification instead of static message/notification from antd in files outside the AntD app context.
• src/App/App.jsx configures these through AntdFeedbackBridge.

Theming

src/App/App.jsx wraps the app with:

• ConfigProvider
• theme.darkAlgorithm or theme.defaultAlgorithm based on Redux darkMode
• AntD locale en_US
• AntD App

Dark mode is stored in Redux user.darkMode.

Data Loading Notes

Apollo defaults are network-only for query and watchQuery. Components should be resilient to loading states and should not assume cached data is available.

Pagination:

• Latest jobs and search jobs use offset/limit style pagination.
• Apollo cache merge policies exist for Query.jobs and Query.search_jobs.
• Guard fetchMoreResult and previous data as arrays before spreading; an earlier crash came from assuming prev.search_jobs was iterable.

Job detail:

• Selection is debounced briefly to prevent a stale left-panel flash.
• Show stable loading/skeleton states during selection/query transitions.
• Guard against stale Apollo data that does not match the currently selected job id.

Redux Notes

Reducers are old-style switch reducers with action constants. Sagas are used for side effects. When adding logic:

• Add action type constants.
• Add action creators.
• Update reducers immutably.
• Add selectors with reselect where state is consumed.
• Add sagas for async or cross-system side effects.

Common UI Pitfalls

• Avoid static AntD feedback APIs.
• Avoid adding in-component globals/listeners without cleanup.
• Keep table/list row keys stable.
• Keep list pagination state defensive around empty or missing arrays.
• Do not introduce new routing assumptions based on browser history; this is a MemoryRouter Electron app.
• Use existing visual density. This is an operational desktop app, not a marketing site.