119 lines
5.0 KiB
Markdown
119 lines
5.0 KiB
Markdown
# Copilot Instructions for Vontor CZ
|
|
|
|
## Overview
|
|
This monorepo contains a Django backend and a Vite/React frontend, orchestrated via Docker Compose. The project is designed for a Czech e-marketplace, with custom payment integrations and real-time features.
|
|
|
|
## Architecture
|
|
- **backend/**: Django project (`vontor_cz`), custom `account` app, and third-party payment integrations (`thirdparty/`).
|
|
- Uses Django REST Framework, Channels (ASGI), Celery, and S3/static/media via `django-storages`.
|
|
- Custom user model: `account.CustomUser`.
|
|
- API docs: DRF Spectacular (`/api/schema/`).
|
|
- **frontend/**: Vite + React + TypeScript app.
|
|
- Organized by `src/api/`, `components/`, `features/`, `layouts/`, `pages/`, `routes/`.
|
|
- Uses React Router layouts and nested routes (see `src/layouts/`, `src/routes/`).
|
|
- **docker-compose.yml**: Orchestrates backend, frontend, Redis, and Postgres for local/dev.
|
|
|
|
## Developer Workflows
|
|
- **Backend**
|
|
- Local dev: `python manage.py runserver` (or use Docker Compose)
|
|
- Migrations: `python manage.py makemigrations && python manage.py migrate`
|
|
- Celery: `celery -A vontor_cz worker -l info`
|
|
- Channels: Daphne/ASGI (see Docker Compose command)
|
|
- Env config: `.env` files in `backend/` (see `.gitignore` for secrets)
|
|
- **Frontend**
|
|
- Install: `npm install`
|
|
- Dev server: `npm run dev`
|
|
- Build: `npm run build`
|
|
- Preview: `npm run preview`
|
|
- Static assets: `src/assets/` (import in JS/CSS), `public/` (referenced in HTML)
|
|
|
|
## Conventions & Patterns
|
|
- **Backend**
|
|
- Use environment variables for secrets and config (see `settings.py`).
|
|
- Static/media files: S3 in production, local in dev (see `settings.py`).
|
|
- API versioning and docs: DRF Spectacular config in `settings.py`.
|
|
- Custom permissions, filters, and serializers in each app.
|
|
- **Frontend**
|
|
- Use React Router layouts for shared UI (see `src/layouts/`, `LAYOUTS.md`).
|
|
- API calls and JWT handling in `src/api/`.
|
|
- Route definitions and guards in `src/routes/` (`ROUTES.md`).
|
|
- Use TypeScript strict mode (see `tsconfig.*.json`).
|
|
- Linting: ESLint config in `eslint.config.js`.
|
|
|
|
### Frontend API Client (required)
|
|
All frontend API calls must use the shared client at frontend/src/api/Client.ts.
|
|
|
|
- Client.public: no cookies, no Authorization header (for public Django endpoints).
|
|
- Client.auth: sends cookies and includes Bearer token; auto-refreshes on 401 (retries up to 2x).
|
|
- Centralized error handling: subscribe via Client.onError to show toasts/snackbars.
|
|
- Tokens are stored in cookies by Client.setTokens and cleared by Client.clearTokens.
|
|
|
|
Example usage (TypeScript)
|
|
```ts
|
|
import Client from "@/api/Client";
|
|
|
|
// Public request (no credentials)
|
|
async function listPublicItems() {
|
|
const res = await Client.public.get("/api/public/items/");
|
|
return res.data;
|
|
}
|
|
|
|
// Login (obtain tokens and persist to cookies)
|
|
async function login(username: string, password: string) {
|
|
// Default SimpleJWT endpoint (adjust if your backend differs)
|
|
const res = await Client.public.post("/api/token/", { username, password });
|
|
const { access, refresh } = res.data;
|
|
Client.setTokens(access, refresh);
|
|
}
|
|
|
|
// Authenticated requests (auto Bearer + refresh on 401)
|
|
async function fetchProfile() {
|
|
const res = await Client.auth.get("/api/users/me/");
|
|
return res.data;
|
|
}
|
|
|
|
function logout() {
|
|
Client.clearTokens();
|
|
window.location.assign("/login");
|
|
}
|
|
|
|
// Global error toasts
|
|
import { useEffect } from "react";
|
|
function useApiErrors(showToast: (msg: string) => void) {
|
|
useEffect(() => {
|
|
const unsubscribe = Client.onError((e) => {
|
|
const { message, status } = e.detail;
|
|
showToast(status ? `${status}: ${message}` : message);
|
|
});
|
|
return unsubscribe;
|
|
}, [showToast]);
|
|
}
|
|
```
|
|
|
|
Vite env used by the client:
|
|
- VITE_API_BASE_URL (default: http://localhost:8000)
|
|
- VITE_API_REFRESH_URL (default: /api/token/refresh/)
|
|
- VITE_LOGIN_PATH (default: /login)
|
|
|
|
Notes
|
|
- Public client never sends cookies or Authorization.
|
|
- Ensure Django CORS settings allow your frontend origin. See backend/vontor_cz/settings.py.
|
|
- Use React Router layouts and guards as documented in frontend/src/routes/ROUTES.md and frontend/src/layouts/LAYOUTS.md.
|
|
|
|
## Integration Points
|
|
- **Payments**: `thirdparty/` contains custom integrations for Stripe, GoPay, Trading212.
|
|
- **Real-time**: Django Channels (ASGI, Redis) for websockets.
|
|
- **Task queue**: Celery + Redis for async/background jobs.
|
|
- **API**: REST endpoints, JWT auth, API key support.
|
|
|
|
## References
|
|
- [frontend/REACT.md](../frontend/REACT.md): Frontend structure, workflows, and conventions.
|
|
- [frontend/src/layouts/LAYOUTS.md](../frontend/src/layouts/LAYOUTS.md): Layout/component patterns.
|
|
- [frontend/src/routes/ROUTES.md](../frontend/src/routes/ROUTES.md): Routing conventions.
|
|
- [backend/vontor_cz/settings.py](../backend/vontor_cz/settings.py): All backend config, env, and integration details.
|
|
- [docker-compose.yml](../docker-compose.yml): Service orchestration and dev workflow.
|
|
|
|
---
|
|
|
|
**When in doubt, check the referenced markdown files and `settings.py` for project-specific logic and patterns.**
|