vending-machine-game/AGENTS.md

# AGENTS.md — Frontend Coding Conventions (React & Next.js)

These rules apply to every task in this repository. Follow them exactly. If a rule conflicts with existing code, follow the rule for new code and do not refactor unrelated files. If a rule is unclear, ask before guessing.

## 0. How this file is organized

- **Sections 1–13 are general** and apply to every project (React or Next.js).
- **Section 14 is framework-specific.** Detect the project type first:
  - `next` in `package.json` dependencies → **Next.js** project → also follow 14.1.
  - Otherwise (Vite, CRA, etc.) → **React** project → also follow 14.2.
- Never apply the rules of the other framework.

## 1. Core principles

1. **Readability beats cleverness.** Write the simplest code that works. A teammate must understand it on the first read.
2. **Easy to extend.** Small, single-purpose functions and components; clear layers; no hidden coupling.
3. **Don't repeat yourself, but don't abstract early.** Duplicate once, tolerate it twice, extract on the **third** occurrence (Rule of Three).
4. **One source of truth.** All HTTP goes through one Axios client; all app-wide state lives in one Redux store; all shared UI lives in `components/shared`.
5. **Documented.** Every function has a doc comment; important places have inline comments.
6. **Formatted before it runs.** Prettier runs automatically before dev and build.

## 2. Ask before you start (mandatory)

At the **start of every task**, before writing any code, ask the user these questions and wait for the answers:

1. **Language:** "Should this be written in **TypeScript** or **JavaScript**?"
2. **Ant Design:** "Do you need **Ant Design** for this, or should I use **only Tailwind CSS**?"

Rules:
- Never assume the answers, even if the repo already contains `tsconfig.json` or Ant Design. Always ask.
- Skip a question only if the user already answered it explicitly in the current task description.
- If Ant Design is not needed, use **Tailwind only** and do not import anything from `antd`.
- State the chosen answers in your final summary.

## 3. Stack

| Concern | Choice |
|---|---|
| Language | **Asked every task** (TypeScript or JavaScript). If TypeScript: `strict: true` |
| UI | React 18 (function components + hooks only) |
| Framework | Next.js App Router **or** React + Vite (detected, see section 0) |
| Global state | Redux Toolkit |
| HTTP | Axios (no RTK Query, no raw `fetch`) |
| Forms | React Hook Form |
| Styling | Tailwind CSS by default. Ant Design **only if the user confirms** |
| Formatting | Prettier |
| Testing | Vitest + React Testing Library (Cypress for E2E) |

Do not add a dependency without stating why and asking first.

## 4. Naming

### Files and folders
- **Component files:** `PascalCase.tsx` / `.jsx` → `UserCard.tsx`
- **Everything else:** `camelCase.ts` / `.js` → `useAuth.ts`, `userService.ts`, `authSlice.ts`, `formatDate.ts`
- **Folders:** `camelCase` (`userManagement/`). A folder holding one component plus companion files is `PascalCase` (`UserCard/`).
- **Tests:** next to the file → `UserCard.test.tsx`
- **Type files (TS):** `user.types.ts`
- **Exception:** Next.js reserved names (`page.tsx`, `layout.tsx`, `loading.tsx`, `route.ts`) and route folders follow Next.js rules.

### Code identifiers
| Kind | Style | Example |
|---|---|---|
| Variables, functions | camelCase | `totalPrice`, `calculateTotal()` |
| Components | PascalCase | `UserCard` |
| Hooks | `use` + PascalCase | `useDebounce` |
| Types, interfaces | PascalCase, **no `I` prefix** | `User`, `UserCardProps` |
| Props type | `<Component>Props` | `UserCardProps` |
| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
| Booleans | `is` / `has` / `can` / `should` | `isLoading`, `hasError` |
| Internal handlers | `handle` + Event | `handleSubmit` |
| Callback props | `on` + Event | `onSubmit` |
| Slice | `<feature>Slice` | `authSlice` |
| Thunks | verb + noun | `fetchUsers` |
| Selectors | `select` + Name | `selectCurrentUser` |
| Service functions | verb + noun | `getUsers`, `createOrder` |

- Prefer union types over `enum`: `type Status = 'idle' | 'loading' | 'failed'`.
- Names are descriptive. Abbreviate only `id`, `url`, `api`, `props`.
- Identifiers and comments are in **English**.

## 5. Project structure (layer-based)

The shared layers are **identical** in both project types and live in `src/`:

```
src/
  components/
    shared/          # reusable components used by 2+ pages/features
    layout/          # Header, Sidebar, PageLayout
  hooks/             # shared custom hooks
  services/          # Axios client + API functions (the ONLY place for HTTP)
    apiClient.ts
    userService.ts
  store/
    index.ts         # configureStore + RootState/AppDispatch
    hooks.ts         # useAppDispatch, useAppSelector
    slices/
  types/
  utils/             # pure helpers
  constants/
  styles/
  tests/
```

Only the routing layer differs (see section 14):
- **Next.js:** `src/app/` (routes only).
- **React (Vite):** `src/pages/`, `src/routes/`, `src/main.tsx`, `src/assets/`.

### Layer rules
- Route files (`app/` or `pages/`) compose components and wire data; no business logic beyond that.
- A component used by **one** page stays in that page's folder. On its **third** use (or when a second page needs it) move it to `components/shared`.
- `components/shared` must be **generic and props-driven**: no imports from pages/routes, `services`, or `store`.
- Components never call Axios. They call hooks, dispatch thunks, or use data passed as props.
- `utils` are pure functions (no React, no side effects).
- No circular imports. Use the `@/` alias for `src/`; avoid `../` chains deeper than two levels.

## 6. Writing simple, readable code

- **Max nesting: 2 levels** (an `if` inside a loop is the limit). Flatten with early returns, guard clauses, or by extracting a named function.
- **Max function length: ~30 lines.** If longer, split into well-named helpers.
- **One function, one job.** If you need "and" to describe it, split it.
- **Max 3 parameters.** Beyond that, pass a single object.
- **Rule of Three:** repeated logic/markup is extracted on the third occurrence into a util, hook, or `shared` component. Do not pre-abstract.
- No nested ternaries. Use `if`/early return or a lookup object.
- Name intermediate values instead of writing long chained expressions.
- No magic numbers or strings: move them to `constants/`.
- Prefer plain `map`/`filter`/`find` over clever `reduce` chains.
- Avoid premature optimization: add `useMemo`/`useCallback` only for a measured problem or a memoized child.

```ts
// Bad: nested and hard to scan
function getLabel(user) {
  if (user) {
    if (user.isActive) {
      return user.name;
    }
  }
  return 'Unknown';
}

// Good: guard clause, flat
function getLabel(user: User | null): string {
  if (!user?.isActive) return 'Unknown';
  return user.name;
}
```

## 7. Documentation and comments

### Every function gets a doc comment
Every function must have a short JSDoc block directly above it describing **what it does**: components, hooks, helpers, services, thunks, selectors, and handlers.

- First line: one clear sentence about the purpose.
- Add `@param` and `@returns` when the function has parameters or a return value.
- One line is enough for trivial functions.
- Not required for tiny inline callbacks (e.g. inside `.map()`).

```ts
/**
 * Returns the display name of a user, or "Unknown" when the user is inactive.
 * @param user - The user to read the name from.
 * @returns The name to show in the UI.
 */
function getLabel(user: User | null): string {
  if (!user?.isActive) return 'Unknown';
  return user.name;
}
```

### Inline comments for important places
Always comment:
- **Why** something is done in a non-obvious way (workarounds, browser/device quirks, offline handling).
- Business rules, calculations, and necessary magic values.
- Complex conditions, regex, and data transformations.
- Side effects and cleanup in `useEffect`, and why the dependencies are what they are.
- Anything that looks like a bug but is intentional.
- Open work as `// TODO: <what and why>`.

Do **not** write comments that only repeat the code (`// increment i`). No commented-out code. No leftover `console.log`.

## 8. Components

- Function declarations for components; arrow functions for inline callbacks.
- One component per file, under ~150 lines. Split when larger.
- Define a props type right above the component (TS) or a `@typedef` (JS). Do not use `React.FC`.
- **Named exports only.** Default export only where a framework requires it (Next.js special files, `React.lazy` pages).
- Order: hooks → derived values → handlers → effects → early returns → JSX.
- Always render **loading, error, and empty** states for async UI.
- Extract repeated logic into custom hooks and repeated UI into `components/shared` (Rule of Three).
- Semantic HTML and basic accessibility (labels, alt text, focus).

```tsx
type UserCardProps = {
  user: User;
  onSelect: (id: string) => void;
};

/**
 * Shows a clickable card for one user and reports the selection.
 */
export function UserCard({ user, onSelect }: UserCardProps) {
  const handleClick = () => onSelect(user.id);

  return (
    <button type="button" onClick={handleClick}>
      {user.name}
    </button>
  );
}
```

## 9. TypeScript / JavaScript

Follow the answer to the question in section 2.

### If TypeScript
- No `any`. Use `unknown` and narrow, or define a type.
- Type all parameters and exported return values; let inference handle locals.
- Request/response shapes live in `types/` and are shared by services and slices.
- `type` for unions and props; `interface` only when extending.
- No non-null assertion (`!`) without a comment explaining why it is safe.
- Files use `.ts` / `.tsx`.

### If JavaScript
- Files use `.js` / `.jsx`. Same naming and structure rules apply.
- Describe data shapes with JSDoc (`@typedef`, `@param {Type}`, `@returns {Type}`), kept in `types/`.
- Document props with a `@typedef` above the component.
- `const`/`let` only (never `var`), strict equality (`===`), optional chaining where needed.

## 10. API layer (all requests via Axios)

- **Every HTTP request goes through Axios.** Do not use `fetch`, `XMLHttpRequest`, or other HTTP clients. (WebSocket is not HTTP; see 14.2.)
- There is **one Axios instance**: `services/apiClient.ts`. It configures `baseURL`, timeout, auth header, and interceptors for token refresh and error normalization.
- Requests are made **only inside `services/`**, one file per domain (`userService.ts`). Services are plain async functions that return data and know nothing about Redux or React.
  ```ts
  /**
   * Fetches the list of all users from the API.
   * @returns The users array.
   */
  export async function getUsers(): Promise<User[]> {
    const { data } = await apiClient.get<User[]>('/users');
    return data;
  }
  ```
- Endpoint paths are constants (in the service file or `constants/endpoints.ts`), not scattered strings.
- Errors are normalized **once** in the interceptor into a single shape (`{ message, status }`). Callers show `error.message`; they do not parse Axios errors themselves.
- Cancel or ignore stale requests with `AbortController` when a component can unmount mid-request.

## 11. Global state (Redux Toolkit)

The store holds **only** these categories. Anything else stays local (`useState`, or a small hook calling a service).

| Category | Slice | Holds |
|---|---|---|
| Auth & current user | `authSlice` | token, profile, permissions |
| General UI settings | `uiSlice` | theme, language, sidebar state |
| Device connection | `deviceSlice` | online/offline status, connected device info (only if the project talks to devices) |
| Shared cross-page data | one slice per domain (e.g. `lookupsSlice`) | data needed by 2+ pages |
| Shopping cart | `cartSlice` | cart items and quantities (header badge, cart page, product pages) |

Rules:
- One slice per feature in `store/slices/`. Slice shape for fetched data:
  `{ items, status: 'idle' | 'loading' | 'succeeded' | 'failed', error: string | null }`.
- Async work uses `createAsyncThunk` that calls a **service**; handle `pending/fulfilled/rejected` in `extraReducers`.
- Use typed `useAppDispatch` / `useAppSelector` only (plain equivalents in JS).
- Write selectors beside the slice; components do not read deep state shapes directly.
- Page-local data (a table on one page, form state, open/closed flags) does **not** go in Redux.
- Keep the state shape documented: when adding a slice, add one line to the table above.

## 12. Formatting (Prettier is mandatory)

Code **must** be formatted with Prettier before the project runs in dev or build.

`package.json` scripts:
```json
{
  "scripts": {
    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,css,json,md}\"",
    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,css,json,md}\"",
    "predev": "npm run format",
    "prebuild": "npm run format",
    "typecheck": "tsc --noEmit",
    "lint": "eslint . --max-warnings 0"
  }
}
```
(`predev` and `prebuild` run automatically before `npm run dev` / `npm run build`. `typecheck` is TypeScript only.)

`.prettierrc`:
```json
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 100
}
```

- Run `npm run format` after editing files and before reporting a task as done.
- Never hand-format against Prettier; never use `// prettier-ignore` without a reason in a comment.
- ESLint passes with zero warnings (`react-hooks`, `@typescript-eslint` if TS, import order).
- Import order: React → third-party → `@/` aliases → relative → styles. Remove unused imports.

## 13. Styling, testing, and git

### Styling
- **Default is Tailwind CSS only.** Use Ant Design **only** if the user said yes in section 2.
- Tailwind utilities for layout/spacing; `clsx` for conditional classes; extract a component when the same class list repeats 3+ times.
- When Ant Design is approved: customize via theme tokens, not CSS overrides, and do not mix it with custom components that do the same job.
- No inline `style` except for truly dynamic values. No hard-coded colors or sizes: use tokens.
- Mobile-first and responsive; for Persian UI use RTL-safe logical utilities (`ms-*`, `me-*`, `ps-*`, `pe-*`).

### Testing
- Test behavior via React Testing Library; query by role/label/text.
- Mock the network at the **service** boundary; never call real APIs.
- New utils, slices, and non-trivial components ship with tests; bug fixes ship with a regression test.

### Git
- Branches: `feature/<name>`, `fix/<name>`. Commits: Conventional Commits (`feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`).
- Keep changes small and focused; do not mix refactors with features.

## 14. Framework-specific rules

### 14.1 Next.js (App Router)

```
src/
  app/               # routes only: page.tsx, layout.tsx, loading.tsx, route.ts
  components/ hooks/ services/ store/ types/ utils/ constants/ styles/
```

- Components are **Server Components by default**. Add `'use client'` to the smallest leaf that needs state, effects, or browser APIs.
- Public/SEO data is fetched on the server (the same Axios client may be used server-side), not through Redux.
- Redux and browser-only hooks live in client components, provided via a client `Providers` component. Create the store only if client state is actually needed.
- Every page defines metadata (`generateMetadata`) with title and description.
- Use `next/image` and `next/link`. Use route handlers (`route.ts`) only when an API layer is truly needed.
- Never touch `window`/`localStorage` during server rendering.
- Default exports are allowed for `page`, `layout`, `loading`, `error`, `not-found`.

### 14.2 React (Vite SPA / PWA / embedded UI)

```
src/
  assets/            # images, fonts, icons
  pages/             # one folder per route; page-specific components live here
  routes/            # router config, route guards
  main.tsx
  components/ hooks/ services/ store/ types/ utils/ constants/ styles/ tests/
```

- Lazy-load pages with `React.lazy` + `Suspense`.
- Assume **unreliable or no network** if the app targets devices (vending, PWA). Handle offline state explicitly; never block the UI on a failed request.
- Device communication over HTTP goes through Axios in `services/`. WebSocket/serial live in a dedicated `services/` module with typed messages and reconnect logic, updating `deviceSlice`.
- For ESP32 / Orange Pi targets keep bundles small: avoid heavy dependencies and unused polyfills.
- Document PWA caching/queue strategy in the PR description.

## 15. Refactoring an existing project

When asked to refactor a project to match this file:

1. **Detect the project type** (section 0) and ask the questions in section 2 before starting. Do not migrate between TypeScript and JavaScript unless explicitly asked.
2. **Audit first.** Scan the project and report what violates these rules (structure, naming, HTTP calls outside `services/`, missing doc comments, deep nesting, duplicated code, unformatted files). Do not change code yet; present a short plan and wait for approval.
3. **Preserve behavior.** A refactor must not change what the app does. No new features, no UI changes, no dependency upgrades.
4. **Work in small steps,** one concern at a time, in this order:
   1. Add Prettier config and scripts, then format the project (formatting-only commit).
   2. Centralize HTTP: create `apiClient` and move every request into `services/`.
   3. Restructure folders and rename files per sections 4 and 5; update imports.
   4. Organize global state per section 11; move page-local state out of Redux.
   5. Extract duplicated code (Rule of Three) and move reusable components to `components/shared`.
   6. Flatten nesting and split long functions (section 6).
   7. Add doc comments and important inline comments (section 7).
5. **Verify after every step:** run `format`, `typecheck` (TS only), `lint`, and `test`, and make sure the project still builds. Fix breakage before moving on.
6. **One commit per step,** using Conventional Commits (`refactor: ...`).
7. **Do not touch** anything you are unsure about; list it in the final report instead.

## 16. Agent checklist (before finishing any task)

1. Did I detect the project type and ask the TypeScript/JavaScript and Ant Design questions (section 2)?
2. Did I read the surrounding code and match its patterns?
3. Is new code in the correct layer (section 5)? Any new HTTP call goes in `services/` via `apiClient`.
4. Nesting ≤ 2, functions ≤ ~30 lines, no third copy of repeated code?
5. Does every function have a JSDoc description, and do important places have inline comments?
6. Did I run `npm run format`, `typecheck` (TS only), `lint`, and `test`?
7. Did I summarize what changed, the chosen language/UI library, assumptions, and follow-ups?
8. Did I avoid touching unrelated files, configs, and dependencies?