TJWaterFrontend_Refine/.github/copilot-instructions.md

Copilot Instructions for TJWaterFrontend_Refine

Environment Setup

1. Node.js: Ensure you have Node.js v18 or later installed.
2. Dependencies: Run npm install to install all project dependencies.
3. Environment Variables: Create a .env.local file in the root directory with

Using bash setup dependencies:

npm install

Build, Test, and Lint

• Dev Server: npm run dev (Runs with increased memory limit: --max_old_space_size=4096)
• Build: npm run build
• Lint: npm run lint (ESLint)
• Test: npm run test (Jest)
  • Run a specific test file: npm run test -- <path/to/file>
  • Run a specific test case: npm run test -- -t 'test name'

High-Level Architecture

• Framework: Next.js 16 (App Router) integrated with Refine (@refinedev/core).
• Routing:
  • Routes are defined in src/app.
  • Refine resources (e.g., /network-simulation, /hydraulic-simulation/*) map directly to these routes.
  • Configuration is central in src/app/_refine_context.tsx.
• State Management:
  • Global App State: Zustand (src/store).
  • Server State: Managed by Refine hooks (useList, useOne, etc.) via React Query.
• Authentication:
  • NextAuth.js handling Keycloak integration.
  • Session token is synced to Zustand (useAuthStore) in RefineContext.
• Data Layer:
  • Custom Data Provider: src/providers/data-provider.
  • API Utilities: src/lib/api.ts, src/lib/apiFetch.ts.
• UI & Styling:
  • Material UI (MUI): Primary component library (@mui/material, @refinedev/mui).
  • Tailwind CSS v4: Utility classes for layout and custom styling (@tailwindcss/postcss).
  • Mapping: OpenLayers (ol), deck.gl, Turf.js.
  • Charts: ECharts, MUI X Charts.

Key Conventions

• Refine Integration:
  • Use Refine hooks (useTable, useForm, useNavigation) for data-heavy components.
  • Resources are defined in the <Refine> component in src/app/_refine_context.tsx.
• Project Structure:
  • src/components/: Grouped by feature (e.g., olmap, project) or common UI elements.
  • src/lib/: Utility functions and API helpers.
  • src/providers/: Refine providers (data, etc.).
• Imports:
  • Use absolute imports with @/ alias (e.g., @/components, @/store, @/lib).
  • Note: @libs alias in tsconfig points to non-existent src/libs folder; prefer @/lib.
• Styling:
  • Prefer MUI components for standard UI elements.
  • Use Tailwind utility classes for layout and custom overrides.