vontor-cz/CLAUDE.md

CLAUDE.md

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

Commands

Frontend (run inside frontend/):

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/):

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):

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:

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