Business-Management/CLAUDE.md

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

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

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

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