# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Spoolman is a self-hosted web service for managing 3D printer filament spools. It tracks inventory, monitors usage, and integrates with OctoPrint and Klipper/Moonraker.

**Tech Stack:**
- Backend: Python 3.9-3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic
- Frontend: React 19, TypeScript, Vite, Ant Design, Refine framework
- Databases: SQLite (default), PostgreSQL, MySQL, CockroachDB

## Common Commands

### Python (PDM)

```bash
pdm install                    # Install all dependencies including dev
pdm sync --prod --no-editable  # Install production dependencies only
pdm run app                    # Run backend server (uvicorn)
pdm run itest                  # Run integration tests (all databases)
pdm run docs                   # Generate API documentation
```

### Frontend

```bash
cd client
npm ci                         # Install dependencies
npm run dev                    # Development server with hot reload
npm run build                  # Production build
npm run tsc                    # Type check only
```

### Linting/Formatting

```bash
black .                        # Format Python code
ruff check . --fix             # Lint and auto-fix Python
pre-commit run --all-files     # Run all pre-commit hooks
```

### Integration Tests

Tests run in Docker containers against multiple database types:

```bash
python tests_integration/run.py sqlite          # Single database
python tests_integration/run.py sqlite postgres # Multiple databases
pdm run itest                                   # All databases
```

Run a single test:
```bash
pytest tests_integration/tests/spool/test_add.py::test_add_spool_remaining_weight -v
```

### Database Migrations

1. Edit models in `spoolman/database/models.py`
2. Run the server to update local SQLite
3. `pdm run alembic revision -m "description" --autogenerate`
4. Review generated migration, format with Black/Ruff

## Architecture

### Backend (`/spoolman/`)

- `main.py` - FastAPI app entry, startup/shutdown, SPA mounting
- `env.py` - Environment variable parsing and configuration
- `ws.py` - WebSocket manager for real-time updates
- `api/v1/` - REST endpoints and WebSocket handlers
  - `router.py` - Main router with WebSocket root endpoint
  - `spool.py`, `filament.py`, `vendor.py` - CRUD endpoints per resource
  - `models.py` - Pydantic response models
- `database/` - SQLAlchemy models and async database operations
  - `models.py` - ORM definitions (Vendor, Filament, Spool, Setting, *Field)
  - `database.py` - Connection setup, backup logic, migrations

### Frontend (`/client/src/`)

- `App.tsx` - Routing and Refine framework setup
- `pages/` - Page components (spools/, filaments/, vendors/, settings/)
- `components/dataProvider.ts` - REST API integration
- `components/liveProvider.ts` - WebSocket live updates

### Data Model

```
Vendor (1) ──→ (many) Filament (1) ──→ (many) Spool
```

All entities support custom fields via *Field tables (VendorField, FilamentField, SpoolField).

### API Patterns

- REST: Standard CRUD at `/api/v1/{resource}`
- WebSocket: Real-time events at `WS /api/v1/` or `WS /api/v1/{resource}`
- Query params: `?skip=0&limit=50&sort_by=name&sort_order=asc`

### Key Configuration

Environment variables (see `.env.example`):
- `SPOOLMAN_DB_TYPE` - Database type (sqlite/mysql/postgres/cockroachdb)
- `SPOOLMAN_PORT` - Server port (default: 7912)
- `SPOOLMAN_DEBUG_MODE` - Enables permissive CORS
- `VITE_APIURL` - Frontend API base URL (e.g., `/api/v1`)

## Code Quality

- Line length: 120 characters
- Python target: 3.9
- Pre-commit hooks enforce Black formatting and Ruff linting
- Backend is fully async using SQLAlchemy AsyncSession

## Gitea Repository

- **URL:** http://192.168.0.5:3022/tonym/spoolman2
- **API Token:** 8a04b3cb5dbb54e2d895b707305523c3ad83a945

This is a fork with UX improvements. Issues are tracked on the Gitea instance above.