# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

**Frontend** (run inside `frontend/`):
```sh
npm install          # install dependencies
npm run dev          # start Vite dev server
npm run build        # TypeScript check + production build
npm run lint         # ESLint
npm run preview      # preview production build
npm run api:gen      # regenerate TypeScript API clients from OpenAPI schema
```

**Backend** (run inside `backend/`):
```sh
python manage.py runserver                    # local dev server
python manage.py makemigrations && python manage.py migrate
celery -A vontor_cz worker -l info            # async task worker
celery -A vontor_cz beat -l info              # periodic scheduler
```

**Full stack (Docker)**:
```sh
docker-compose up    # starts backend, db, redis, celery, celery-beat, nginx
```

There is no test suite configured.

## Architecture

Django + React monorepo for a Czech e-marketplace (vontor.cz). Backend exposes a REST API consumed by the React SPA; real-time features use WebSockets.

**Services (docker-compose.yml):**
- `backend` — Django/ASGI (Gunicorn + Uvicorn workers)
- `db` — PostgreSQL 15
- `redis` — cache + Channels message broker + Celery broker
- `celery` / `celery-beat` — async and scheduled tasks
- `nginx` — reverse proxy + serves frontend `dist/`

## Frontend

**Stack:** React 19 · React Router 7 · TypeScript · Vite · Tailwind CSS 4 · Mantine · React Query · React Hook Form · Axios · Orval

**Folder layout (`frontend/src/`):**
- `api/` — Axios clients and Orval-generated hooks
- `components/` — reusable UI components (use hooks/context, keep logic-light)
- `features/` — self-contained feature modules (each owns its hooks, API calls, and UI)
- `pages/` — route-level page components
- `layouts/` — shared wrappers (nav, footer) rendered via React Router `<Outlet />`
- `routes/` — route guard components (`PrivateRoute`)
- `context/` — React Context providers (`AuthContext`)
- `hooks/` — shared custom hooks
- `utils/` — reusable pure helper functions

**Routing entry point:** `src/App.tsx` — defines all routes and layout nesting.

**Styling:** Tailwind utility classes preferred. Global CSS variables and reusable helpers (`.glass`, `.glow`, `.section`) live in `src/index.css`. Avoid inline styles and CSS-in-JS.

**Path alias:** `@/*` resolves to `src/*`.

## API Client

All API calls go through `frontend/src/api/`. Two Axios instances:

- `publicClient.ts` (`publicApi`) — no cookies, no auth header; for public endpoints
- `privateClient.ts` (`privateApi`) — `withCredentials: true` (HttpOnly cookies with JWT); auto-refreshes on 401

There is also a `Client.ts` wrapper used in some places: `Client.public` / `Client.auth` with a `Client.onError` subscription for global error toasts.

**Never import `dotenv/config` in frontend files.** Use `import.meta.env.VITE_*` for env vars.

Key env vars:
```
VITE_BACKEND_URL       # default: http://localhost:8000
VITE_API_REFRESH_URL   # default: /api/token/refresh/
VITE_LOGIN_PATH        # default: /login
```

## Orval API Client Generation

Orval auto-generates TypeScript hooks from the Django OpenAPI schema (`/api/schema/`).

- Config: `frontend/orval.config.ts`
- Output: `frontend/src/api/generated/` (split into `public/` and `private/` by tag)
- Regenerate: `npm run api:gen` (fetches schema from running backend, then runs orval)

Generated hooks use `publicMutator` / `privateMutator` as their Axios adapters. Import generated hooks directly in components/features:
```ts
import { useGetOrders } from "@/api/generated/private/orders";
```

Choice field labels come from the backend `/api/choices/` endpoint and are processed into `frontend/src/api/choices.ts` by `frontend/scripts/generate-choice-labels.cjs`.

## Backend

**Stack:** Django 5.1 · DRF · Django Channels (ASGI) · SimpleJWT · DRF Spectacular · Celery · Redis · PostgreSQL · django-filter · django-constance · WeasyPrint · Pillow · django-storages (S3)

**App structure (`backend/`):**
- `vontor_cz/` — project settings, URL root, ASGI/WSGI, Celery config, shared base models
- `account/` — `CustomUser` (extends `AbstractUser`), JWT login/logout views, custom permissions
- `commerce/` — Category, Product, Order, OrderItem, Payment models; analytics
- `advertisement/` — ad management
- `social/` — hubs, posts, and real-time chat (Channels + WebSocket)
- `configuration/` — `SiteConfiguration` model (managed via Django Admin)
- `thirdparty/` — Stripe, GoPay, Trading212, yt-dlp downloader, Deutsche Post, Zasilkovna, Cloudflare

**Key conventions:**
- Models inherit from `vontor_cz.models.SoftDeleteModel` for soft-delete (`deleted_at` field).
- Use `ActiveUserManager` / `CustomUserManager` where you need to filter deleted records.
- Async tasks are `@shared_task` in each app's `tasks.py`.
- API docs at `/api/schema/` (DRF Spectacular). Avoid duplicate serializer field schemas — define reusable `ChoiceField` subclasses (e.g. `OrderStatusField`) and reuse them across serializers.
- Logging: `logging.getLogger(__name__)` per module.
- Static/media: local in dev, S3 (`django-storages`) in production.
- Silk profiler is active in DEBUG mode (`/silk/`).

**Real-time chat (`social/chat/`):**
- `consumers.py` — WebSocket consumer: connect, receive, typing indicators, reactions
- `routing.py` — WebSocket URL patterns
- `models.py` — Chat, Message, MessageReaction, MessageHistory
- REST endpoints coexist alongside WebSocket; see `social/chat/chat app diagram.md` for the flow.

## Key Reference Files

- `.github/copilot-instructions.md` — overlapping guidance, includes `Client.ts` usage examples
- `frontend/REACT.md` — frontend folder conventions (Czech)
- `frontend/src/layouts/LAYOUTS.md` — layout/outlet patterns
- `frontend/src/routes/ROUTES.md` — routing conventions
- `frontend/src/context/EXAMPLES.md` — AuthContext usage examples
- `backend/vontor_cz/settings.py` — all backend config: CORS, JWT, Celery, logging, S3, payments
- `docker-compose.yml` — service wiring and volume mounts
- `social/chat/chat app diagram.md` — WebSocket architecture