# AGENTS.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

## Project Overview

CGR App - A Next.js 16 admin dashboard application with internationalization (i18n) support for English, German, and Russian. Uses React 19, TypeScript, Tailwind CSS v4, and shadcn/ui components.

## Commands

### Development
```bash
# Run dev server via Docker (preferred)
make run

# Or directly with npm
npm run dev
```

### Build & Lint
```bash
npm run build      # Production build
npm run lint       # ESLint
```

### Docker Operations
```bash
make run           # Start dev container (docker-compose.yml)
make stop          # Stop containers
make logs          # View container logs
make build         # Rebuild container

# Production deployment (uses docker-compose.prod.yml)
make ENV=prod deploy
```

### Adding Dependencies
```bash
# Install npm package via Docker
make i package=<package-name>

# Add shadcn/ui component via Docker
make ui component=<component-name>
```

## Architecture

### App Router Structure
```
app/
├── layout.tsx                    # Root layout (pass-through for i18n)
├── [locale]/                     # Dynamic locale segment (en, de, ru)
│   ├── layout.tsx               # Main layout with providers (Theme, i18n)
│   └── (backend)/               # Route group for admin dashboard
│       ├── layout.tsx           # Dashboard shell (Sidebar + Header)
│       ├── page.tsx             # Overview page
│       ├── admin/
│       └── users/
│           └── components/      # Page-specific components
```

### Key Patterns

**Internationalization (next-intl)**
- Routing config: `i18n/routing.ts` defines supported locales
- Request handler: `i18n/request.ts` loads messages dynamically
- Navigation: Use `@/i18n/navigation` exports (`Link`, `useRouter`, `usePathname`) for locale-aware navigation
- Messages: JSON files in `messages/` directory (`en.json`, `de.json`, `ru.json`)

**Component Organization**
- `components/ui/` - shadcn/ui primitives (new-york style, RSC enabled)
- `components/` - App-specific components (Header, Sidebar, etc.)
- Page-specific components live under their route: `app/[locale]/(backend)/users/components/`

**Providers Hierarchy** (in `app/[locale]/layout.tsx`)
```
ThemeProvider (next-themes) → NextIntlClientProvider → children
```

### Path Aliases
- `@/*` maps to project root (e.g., `@/components`, `@/lib/utils`, `@/hooks`)

## Styling

- Tailwind CSS v4 with CSS variables for theming
- `cn()` utility from `lib/utils.ts` for conditional class merging
- Global styles in `app/globals.css`