curo1305
112 lines
3.5 KiB
Markdown
112 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Stack
|
|
|
|
| Layer | Tech |
|
|
|---|---|
|
|
| Backend | FastAPI (async), SQLAlchemy 2 (async), Alembic, PostgreSQL |
|
|
| Auth | JWT via `python-jose`, bcrypt via `passlib` |
|
|
| Frontend | React 18, TypeScript, Vite, React Router v6, TanStack Query, Axios |
|
|
| Dev DB | PostgreSQL 16 via Docker Compose |
|
|
|
|
## Commands
|
|
|
|
### Backend (run from `backend/`)
|
|
|
|
```bash
|
|
# Install
|
|
python -m venv .venv && source .venv/bin/activate
|
|
pip install -e ".[dev]"
|
|
|
|
# Run dev server
|
|
uvicorn app.main:app --reload
|
|
|
|
# Lint / format
|
|
ruff check . && ruff format .
|
|
|
|
# Tests
|
|
pytest
|
|
pytest tests/test_auth.py # single file
|
|
|
|
# Migrations
|
|
alembic revision --autogenerate -m "describe change"
|
|
alembic upgrade head
|
|
alembic downgrade -1
|
|
```
|
|
|
|
### Frontend (run from `frontend/`)
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev # Vite dev server at :5173, proxies /api → :8000
|
|
npm run build
|
|
npm run typecheck
|
|
npm run lint
|
|
```
|
|
|
|
### Full stack via Docker
|
|
|
|
```bash
|
|
cp .env.example backend/.env
|
|
docker compose up --build
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Request flow
|
|
|
|
```
|
|
Browser → Vite dev server (:5173)
|
|
/api/* → proxy → FastAPI (:8000)
|
|
→ router → dependency injection (get_db, get_current_user)
|
|
→ SQLAlchemy async session → PostgreSQL
|
|
```
|
|
|
|
### Backend layout
|
|
|
|
- `app/main.py` — FastAPI app, CORS, router registration
|
|
- `app/core/config.py` — all settings via `pydantic-settings` (reads `.env`)
|
|
- `app/core/security.py` — password hashing and JWT encode/decode
|
|
- `app/database.py` — async engine, `AsyncSessionLocal`, `Base` (all models inherit from here)
|
|
- `app/models/` — SQLAlchemy ORM models; import them all in `__init__.py` so Alembic detects them
|
|
- `app/schemas/` — Pydantic request/response models (separate from ORM models)
|
|
- `app/routers/` — one file per resource; mount in `main.py`
|
|
- `app/deps.py` — FastAPI dependencies: `get_current_user` validates JWT and returns `User`
|
|
|
|
### Frontend layout
|
|
|
|
- `src/api/client.ts` — single Axios instance; all API calls live here, token injected via interceptor
|
|
- `src/hooks/useAuth.ts` — token state (localStorage), `login`, `logout`; consumed by pages and `App.tsx`
|
|
- `src/pages/` — one file per route; data fetching via TanStack Query
|
|
- `src/App.tsx` — route tree; `PrivateRoute` wrapper redirects to `/login` when no token
|
|
|
|
### Auth flow
|
|
|
|
1. `POST /api/auth/login` returns a JWT bearer token
|
|
2. Token stored in `localStorage`, attached to every request by the Axios interceptor
|
|
3. Protected routes call `GET /api/users/me`; `get_current_user` dep validates the token on the server
|
|
|
|
## Changelog convention
|
|
|
|
Every time files are added or modified, append an entry to the relevant file in `changelog/` (one file per date, named `YYYY-MM-DD_<slug>.md`). If a file for today already exists, append to it rather than creating a new one.
|
|
|
|
Each entry must include:
|
|
- A heading with the date and a short description
|
|
- `**Timestamp:**` in ISO-8601 format
|
|
- A **Summary** sentence
|
|
- A **Files Added / Modified / Deleted** list with one-line descriptions
|
|
|
|
The `README.md` **Current State** section should be kept up to date whenever significant features are added or removed.
|
|
|
|
---
|
|
|
|
### Adding a new resource
|
|
|
|
1. Add ORM model in `app/models/`, import it in `app/models/__init__.py`
|
|
2. Run `alembic revision --autogenerate -m "add <resource>"` + `alembic upgrade head`
|
|
3. Add Pydantic schemas in `app/schemas/`
|
|
4. Add router in `app/routers/`, mount it in `app/main.py`
|
|
5. Add API function(s) to `src/api/client.ts`, add page/component, register route in `App.tsx`
|