phpengine/specs/conventions-frontend.md

Read this when changing the React application, MUI components, routing, or frontend API calls.

Frontend Conventions

Application Structure

• main.jsx mounts StrictMode, MUI ThemeProvider, CssBaseline, and BrowserRouter.
• Routes and session coordination live in routes.jsx; feature pages live in features/<area>/.
• api/client.js is the only shared HTTP client. Route feature requests through it rather than direct fetch() calls.

Authentication and Routing

• getSession() initializes in-memory CSRF state before protected mutations.
• The client always uses same-origin requests with credentials: 'include'; non-GET requests attach X-CSRF-Token only when a token is available.
• Frontend redirects are usability controls only. The API remains the authorization authority; administration uses role ID 1 and the Inventory Monitor demo uses role ID 2.
• Role-management controls use {id, name, description} records while user assignments use numeric role IDs.
• Use APPLICATION_BASE_PATH for internal application and static-asset paths so the /phengine deployment prefix is retained.

UI

• Role-catalog and Inventory Monitor demo pages use the shared API client and preserve the server-side authorization and CSRF contracts.
• Prefer MUI components for structure, controls, feedback, and responsive behavior.
• Tailwind utilities are used through className for layout and small visual adjustments.
• Theme defaults are in theme.js, including the custom navigation palette, typography families, and shared border radius; global CSS only imports Tailwind layers and sets root sizing/margins.
• AppShell derives top-level links and populated groups from the flat navigation payload, assigns known icons with a fallback icon, and selects entries from location.pathname.
• Pages use local state/hooks, explicit loading/error feedback, and cleanup guards for asynchronous effects; use responsive sx values for control sizing/alignment when a layout needs a breakpoint-specific adjustment.

Formatting

.prettierrc specifies single quotes, semicolons, LF endings, no trailing commas, a 200-column print width, and 2-column indentation width. Existing files use tabs; preserve local formatting and do not reformat unrelated code.

See api-routes.md and integrations/browser-api.md.