tonym
a55194ba16
Some checks failed
CI / style (push) Has been cancelled
CI / build-client (push) Has been cancelled
CI / build-amd64 (push) Has been cancelled
CI / build-tester (push) Has been cancelled
CI / test (cockroachdb) (push) Has been cancelled
CI / test (mariadb) (push) Has been cancelled
CI / test (postgres) (push) Has been cancelled
CI / test (sqlite) (push) Has been cancelled
CI / build-arm64 (push) Has been cancelled
CI / build-armv7 (push) Has been cancelled
CI / publish-images (push) Has been cancelled
CI / publish-release (push) Has been cancelled
Includes development commands, architecture overview, and Gitea repository configuration for issue tracking. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
123 lines
3.9 KiB
Markdown
123 lines
3.9 KiB
Markdown
# 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.
|