# <PROJECT NAME> — CLAUDE.md

# Generated by /init-project. Single source of truth for Claude in this repo.
# Global rules: ~/.claude/CLAUDE.md — this file extends or overrides them.

---

## Project overview

<!-- What it does and for whom. 2-4 sentences. -->
<!-- Ex: REST API for managing food delivery orders. Exposes CRUD endpoints consumed by a React frontend. Single-tenant, deployed on a VPS via Docker Compose. -->

---

## Stack

<!-- language+version, framework, runtime, database, key services -->
<!-- Ex: Python 3.12 / FastAPI / PostgreSQL 16 / Redis 7 / Docker Compose -->

---

## Build commands

<!-- Exact commands — native and Docker if applicable -->
<!-- Ex:
  Native : uvicorn src.main:app --reload
  Docker : docker compose up --build
  Build  : docker build -t myapp .
-->

---

## Test commands

<!-- Ex: pytest src/tests/ -v --cov=src -->

---

## Lint / format commands

<!-- Ex: ruff check . && black --check . && mypy src/ -->
<!-- Or: N/A -->

---

## Folder structure

<!-- Actual tree — fill after scaffolding -->
<!-- Ex:
src/
  main.py        — app init, lifespan hooks
  routes/        — one file per resource
  models/        — SQLAlchemy models
  schemas/       — Pydantic schemas
  services/      — business logic
tests/
  conftest.py
  test_orders.py
-->

---

## Architecture

<!-- Module responsibilities, data flow, key design decisions -->
<!-- Ex: Request → router → service (business logic) → repository (DB) → response.
     Auth: JWT validated in a FastAPI dependency injected at router level. -->

---

## Project conventions

<!-- Naming, file organization, patterns specific to this project -->
<!-- Ex: snake_case everywhere. Route files named after the resource (orders.py, users.py).
     All DB access goes through repository classes, never direct in routes. -->

---

## Exceptions to global rules

<!-- Explicit overrides of ~/.claude/CLAUDE.md, or: -->
<!-- none — global rules apply -->

---

## Key dependencies

<!-- library — purpose, one line each -->
<!-- Ex:
  fastapi      — web framework
  sqlalchemy   — ORM
  alembic      — DB migrations
  pydantic     — validation/serialization
  pytest       — test framework
  ruff         — linter
-->

---

## Workflow expectations

<!-- How Claude should behave in this repo -->
<!-- Ex: Always run pytest after any model/service change.
     Never modify migration files — generate new ones with alembic revision.
     Ask before touching the auth dependency or JWT logic. -->