kokot
This commit is contained in:
3
.vscode/settings.json
vendored
3
.vscode/settings.json
vendored
@@ -1,5 +1,6 @@
|
|||||||
{
|
{
|
||||||
"files.autoSave": "afterDelay",
|
"files.autoSave": "afterDelay",
|
||||||
"files.autoSaveDelay": 1000,
|
"files.autoSaveDelay": 1000,
|
||||||
"python.analysis.autoImportCompletions": true
|
"python.analysis.autoImportCompletions": true,
|
||||||
|
"claudeCodeChat.permissions.yoloMode": false
|
||||||
}
|
}
|
||||||
134
CLAUDE.md
Normal file
134
CLAUDE.md
Normal file
@@ -0,0 +1,134 @@
|
|||||||
|
# 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
|
||||||
Reference in New Issue
Block a user