main_frontend/AGENTS.md

# AGENTS.md — Coffee Project Frontend

## Project Overview

Next.js 16 application using **Feature-Sliced Design (FSD)** architecture, powered by **Bun** runtime and package manager.

---

## Tech Stack

| Category      | Technology                                 |
| ------------- | ------------------------------------------ |
| Runtime       | Bun 1.3.5                                  |
| Framework     | Next.js 16.1.1 (App Router)                |
| Language      | TypeScript 5.9                             |
| UI Library    | React 19                                   |
| Styling       | SCSS Modules, normalize.css                |
| State/Fetch   | TanStack React Query 5, Axios, Xior        |
| Animation     | Framer Motion                              |
| Utilities     | Lodash, Moment.js, classnames, usehooks-ts |
| Icons         | Lucide React, SVGR (custom icons)          |
| Notifications | React Toastify                             |
| File Upload   | React Dropzone                             |
| Linting       | ESLint 9, Prettier, Stylelint              |
| Testing       | Jest, Testing Library                      |

---

## Commands

```bash
bun dev              # Start dev server
bun run build        # Production build
bun run start        # Start production server
bun run lint         # Run ESLint + Prettier
bun run gc <layer> <ComponentName>  # Generate FSD component
bun run gicons       # Convert SVGs to React components
```

---

## Project Structure (FSD)

```
app/                  # Next.js App Router entry
pages/                # Keep empty (Next.js requires it)
public/               # Static assets
src/
├── app/              # App layer: global styles, providers
├── pages/            # Page compositions
├── widgets/          # Large UI blocks (header, sidebar)
├── features/         # User interactions (auth, search)
├── entities/         # Business entities (user, product)
└── shared/           # Reusable: UI kit, utils, API, assets
    ├── ui/           # Button, Input, Icons...
    ├── api/          # API clients
    ├── lib/          # Utilities
    └── assets/       # Images, raw-icons
```

### Path Aliases

```ts
@app/*       → ./src/app/*
@pages/*     → ./src/pages/*
@widgets/*   → ./src/widgets/*
@features/*  → ./src/features/*
@entities/*  → ./src/entities/*
@shared/*    → ./src/shared/*
@/*          → ./src/*
```

---

## Component Structure

Each component follows FSD slice structure:

```
ComponentName/
├── index.ts              # Public API (re-export)
├── ui/
│   ├── ComponentName.tsx
│   └── ComponentName.module.scss
├── model/
│   └── ComponentName.d.ts  # Props interface
└── api/                  # Optional: component-specific API
```

### Component Template

```tsx
import type { JSX } from "react"

import { FunctionComponent } from "react"

import { IComponentNameProps } from "../model/ComponentName.d"
import styles from "./ComponentName.module.scss"

export const ComponentName: FunctionComponent<
	IComponentNameProps
> = (): JSX.Element => {
	return (
		<div className={styles.root} data-testid="ComponentName">
			ComponentName
		</div>
	)
}
```

### Generate Component

Use one of these commands to generate new project-wide standardized component, don't create new component file by file by yourself

```bash
bun run gc <layer> <ComponentName>
# Examples:
bun run gc shared Button
bun run gc feature AuthForm
bun run gc entity UserCard
bun run gc page HomePage
bun run gc widget Sidebar
```

---

## Best Practices

### Code Style

1. **Small Functions** — max 20-30 lines; extract helpers
2. **Single Responsibility** — one function = one purpose
3. **Descriptive Names** — `getUserById` not `getData`
4. **Early Returns** — reduce nesting with guard clauses
5. **No Magic Values** — use constants: `const MAX_ITEMS = 10`

### TypeScript

```ts
// ✅ Use interfaces for props
interface IButtonProps {
	variant: "primary" | "secondary"
	disabled?: boolean
	onClick: () => void
}

// ✅ Prefer explicit types over `any`
// ✅ Use `type` for unions/intersections, `interface` for objects
```

### React Patterns

```tsx
// ✅ Functional components with explicit return type
export const Button: FC<IButtonProps> = ({ variant, onClick }): JSX.Element => { ... }

// ✅ Destructure props
// ✅ Use data-testid for testing
// ✅ Colocate styles with components (CSS Modules)
```

### FSD Rules

1. **Import Direction** — only downward: `features → entities → shared`
2. **Public API** — export only through `index.ts`
3. **No Cross-Slice Imports** — features cannot import from other features
4. **Shared is Agnostic** — no business logic in shared layer

### File Naming

| Type      | Convention        | Example                |
| --------- | ----------------- | ---------------------- |
| Component | PascalCase        | `UserCard.tsx`         |
| Module    | PascalCase.module | `UserCard.module.scss` |
| Types     | PascalCase.d      | `UserCard.d.ts`        |
| Hook      | camelCase (use-)  | `useAuth.ts`           |
| Utility   | camelCase         | `formatDate.ts`        |
| Constant  | UPPER_SNAKE_CASE  | `API_ENDPOINTS.ts`     |

### Performance

1. Use `React.memo` for expensive renders
2. Use `useMemo` / `useCallback` for derived data and callbacks
3. Lazy load pages/heavy components with `next/dynamic`
4. Prefer server components where possible (Next.js App Router)

### Testing

- Place tests next to components: `ComponentName.test.tsx`
- Use `data-testid` attributes for queries
- Test behavior, not implementation

---

## Icons Workflow

1. Place raw SVG in `src/shared/assets/raw-icons/`
2. Run `bun run gicons`
3. Import from `@shared/ui/Icons/IconName`

---

## Notes

- **Keep `pages/` folder** in root — removing causes Next.js build errors
- **Bun only** — use `bun` commands, not npm/yarn
- **SCSS Modules** — all styles are scoped via `.module.scss`
- **Strict TypeScript** — `strict: true` in tsconfig

---

## Quick Reference

| Task               | Command / Location              |
| ------------------ | ------------------------------- |
| Add dependency     | `bun add <package>`             |
| Add dev dependency | `bun add -d <package>`          |
| Create component   | `bun run gc <layer> <Name>`     |
| Global styles      | `src/app/styles/global.scss`    |
| API client         | Use Axios/Xior with React Query |
| State management   | TanStack Query (server state)   |

## Implementation sentiments

Write less complicated code, simple but readable code
Less overhead - better
Write all components with html semantics in mind