# Repository Guidelines

## Project Structure & Module Organization
- `spoolman/` holds the FastAPI backend, SQLAlchemy models, and API routes (`spoolman/api/v1/`).
- `client/` is the React + TypeScript UI (Vite), with pages under `client/src/pages/` and shared components under `client/src/components/`.
- `migrations/` contains Alembic migrations; versions live in `migrations/versions/`.
- `tests_integration/` holds pytest integration tests and Docker Compose configs for multiple databases.
- `scripts/` provides install/start helpers; `Dockerfile` and `entrypoint.sh` support container builds.

## Build, Test, and Development Commands
- `pdm install` installs backend dependencies (including dev tools).
- `pdm run app` starts the API server (`uvicorn spoolman.main:app`).
- `pdm run itest` runs integration tests across all databases.
- `pdm run docs` generates API documentation.
- `python tests_integration/run.py sqlite postgres` runs tests for selected DBs.
- `cd client && npm ci` installs UI deps; `npm run dev` starts the UI dev server; `npm run build` creates a production build.
- `bash scripts/install.sh` bootstraps a local install; `bash scripts/start.sh` runs using `.env`.

## Coding Style & Naming Conventions
- Python: Black + Ruff, 120-char lines (`pyproject.toml`). Prefer async patterns in backend code.
- TypeScript/React: follow existing conventions (pages in lowercase file names, shared components in `PascalCase`).
- Keep naming aligned with existing modules (e.g., `spool`, `filament`, `vendor`).

## Testing Guidelines
- Tests use `pytest` with async support; files follow `test_*.py` and functions start with `test_`.
- Integration tests are the primary suite; run via `pdm run itest` or `python tests_integration/run.py`.

## Database Migrations
- Update models in `spoolman/database/models.py`.
- Start the server once, then generate a migration: `pdm run alembic revision -m "desc" --autogenerate`.
- Review and format migrations with Black/Ruff before committing.

## Commit & Pull Request Guidelines
- Follow commit history conventions (e.g., `feat:`, `docs:`, `fix:`) and keep messages concise.
- PRs should include a short summary, testing performed, and screenshots for UI changes.
- Link relevant issues where applicable.

## Configuration Tips
- Copy `.env.example` to `.env` for local runs; key variables include `SPOOLMAN_DB_TYPE`, `SPOOLMAN_PORT`, and `VITE_APIURL`.