# Project Coding Rules for LLM

This document defines coding, architectural, and project conventions for the LLM when developing the Stock market app project in Cursor IDE or Aider.
Follow strictly to ensure consistency, rapid development, and scalability for a large-scale international SaaS.

---

## 🧐 Project Type

- **React application with TypeScript**
- UI built exclusively with **MUI (Material UI)**
- Project bootstrapped with **Vite**
- ESLint and Prettier for consistent code style

---

## 📁 Project Structure

```text
src/
  components/               # Shared reusable components
  pages/                    # Top-level application pages (routing targets)
  hooks/                    # Reusable React hooks
  redux/                    # Global state management using Redux Toolkit
  features/
    [featureName]/
      components/           # Feature-specific components
      hooks/                # Feature-specific hooks
      utils/                # Utility functions
      types/                # TypeScript types
      slices/               # Redux slices specific to the feature
  i18n/
    pl.json                 # Flat message map for Polish (used by i18next)
    en.json                 # Flat message map for English (used by i18next)
```

---

## 🎨 UI & Styling Rules

- Use **MUI only**. Do **not** use Tailwind, Bootstrap, or custom CSS frameworks.
- Style components using the `sx` prop or `styled()` utility from MUI (Emotion).
- Do **not** write global CSS or use `className` for styling unless unavoidable.
- Define application theme in:

```text
src/theme.ts
```

- Provide the theme via `ThemeProvider` at the root level (`main.tsx`).
- Enable dark mode support with `palette.mode`.
- **Crucially ensure responsive design** using MUI's breakpoint system (`xs`, `sm`, `md`, `lg`, `xl`) so that the application works flawlessly on mobile devices, tablets, and desktop computers. Apply mobile-first design principles.
- To assure proper responsive design always define the: `xs` (mobile), `sm` (tablet), `md` (desktop) breakpoints where different styling depending on device type is needed.
- For logic that depends on device type use the `useDeviceType` hook that provides `{ isMobile, isTablet, isDesktop, device: isMobile ? 'mobile' : isTablet ? 'tablet' : 'desktop'}`
- Use the following custom components to maintain consistent visual style across the application:
  - `ScreenSection` for top-level sections, may be used several times on the screen
  - `LoadingOverlay` for loading states

### ✅ Suggestion: Reinforce Navigation and UX Expectations

- **All navigation must follow the responsive navigation UX spec** defined in the [specification](doc/mr/009-responsive-navigation-layout.md).
- The navigation system must:
  - Use bottom navigation for mobile and tablet (with MUI icons)
  - Use persistent left sidebar for desktop
  - Include a sticky top bar with title and chat icon across all devices
  - Include context-aware FABs (SpeedDial) for actions like adding ingredients
  - Ensure chat access is obvious but not disruptive, and supports unread indicators

This ensures every new page, feature, or layout continues to respect the globally defined navigation and UX behavior.

---

## ⚙️ Coding Conventions

- Ensure code readability by giving meaningful names to variables, functions, and components.
- Prefer descriptive names to abbreviations and comments in code.
- Avoid obvious code comments—add comments only when logic is complex or not self-explanatory and could not be broken down into smaller and easier to understand blocks of logic (functions, classes, components, etc.).
- Never put comments informing that you changed something in the code. All comments added to the code should be meaningful and informative in the long run
- Break bigger blocks of logic or components into smaller well defined functions or components with well defined responsibility.
- Adhere to SOLID principles and DRY (Don't Repeat Yourself) principles.
- Never leave commented and unnecessary code in the repository.
- **PascalCase** for React components and file names (e.g., `UserCard.tsx`).
- **camelCase** for variables, functions, and hooks (e.g., `useFetchData`).
- All logic must be strongly typed using **TypeScript**.
- Prefer functional components and hooks over class components.
- **Always use the `idGenerator` utility** (`src/utils/idGenerator.ts`) for generating random IDs. Use `generateIdSync()` for immediate ID needs and `generateId()` for async contexts.
- Use `LoadingOverlay` component to indicate loading states in components.

---

## 🌐 Localization (i18n)

- Initially, develop the application in **Polish language only** for MVP and fast prototyping.
- **Use `react-i18next`** for internationalization and translation.
- **Always code with localization in mind**:
  - Define all user-facing strings using the `t` function from the `useTranslation` hook.
  - Organize translation keys per feature in `messages.ts` files.
  - Load Polish translation strings from `pl.json` in `src/i18n/`.
- Configure i18next in a dedicated file (e.g., `src/i18n/config.ts`).
- Wrap the app with `I18nextProvider` in `main.tsx` and ensure Polish is set as the default language.
- This structure supports fast MVP development and easy expansion to 20+ languages later.

---

## 🔌 State Management

- Use **Redux Toolkit** as the **sole state management system**.
- Do not create new React Contexts for application or feature state. Theme and localization context are the only exceptions.
- All shared or persisted state must live in Redux slices under the appropriate `features/[feature]/slices/` directory.
- Feature slices requiring persistence must define versioned adapters.
- Avoid using `useState` for global or shared state.
- Use Redux selectors and actions exclusively for feature and cross-feature state.

---

## 🚣️ Routing

- Use **React Router v6** for routing.
- Routes should be clearly defined and organized in `src/pages/`.

---

## 🧪 Testing

- **Unit tests** with **Vitest** and **React Testing Library** (e.g., `*.spec.tsx`).
- **Integration/E2E tests** with **Playwright** located in `tests/`.
- **Storybook** for isolated component development and testing.

---

## 📱 Mobile and Installable Web App (PWA)

- The application **must be installable** as a Progressive Web App (PWA), providing an app-like user experience.
- Ensure it supports home screen installation, offline caching, and other PWA best practices.
- Validate and optimize regularly on real mobile devices and tablets to guarantee a native-like feel.

---

## ❗ Summary of Required Paths

```text
src/theme.ts                     # Theme definition
src/main.tsx                     # Application entry and ThemeProvider
src/redux/                       # Global state management setup
src/components/                  # Shared reusable components
src/pages/                       # Application routes
src/hooks/                       # Reusable hooks
src/features/[featureName]/      # Feature-based structure
src/i18n/                        # Global translation files and config
```

---

Follow these rules consistently for all future development unless explicitly overridden or updated.