Add CLAUDE.md with project guidance and Gitea config

Includes development commands, architecture overview, and
Gitea repository configuration for issue tracking.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,122 @@
+# 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.