# Project pack: Spoolman @ 488eb74

Facts about **Spoolman** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Spoolman is a self-hosted inventory for 3D-printing filament. You record each spool with its material, colour, weight and price, and it keeps track of how much is left as you print. It connects to printer software such as Klipper and OctoPrint, and can print spool labels.

## Version and source
- Repository: https://github.com/Donkie/Spoolman
- Pinned commit: `488eb7455bead9b2968ff9466ba2f59091a6c23b`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/Donkie/Spoolman/archive/488eb7455bead9b2968ff9466ba2f59091a6c23b.zip
- Official docs: https://github.com/Donkie/Spoolman/wiki
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/Donkie/Spoolman bespoke-spoolman
  cd bespoke-spoolman
  git checkout --detach 488eb7455bead9b2968ff9466ba2f59091a6c23b
  # Prepare development requirements and local configuration first.
  pip install uv
  uv sync
  uv run uvicorn spoolman.main:app --reload
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the install guide at https://github.com/Donkie/Spoolman/wiki/Installation, which provides a docker-compose.yml using ghcr.io/donkie/spoolman.
  ```

- Needs: Docker for a trial, Python 3.11 and Node 22 for development
- Develop: `uv run uvicorn spoolman.main:app --reload`
- Test: `uv run pytest`
- Stack: python, typescript (FastAPI, SQLAlchemy, React, Ant Design, Refine). Difficulty for a non-developer with an AI: **easy**. A small FastAPI server with a React front end. The data model is a few tables (vendors, filaments, spools), so new fields and reports are simple.

## Customisation points (settings → extend → code)
- **vendors-filaments-spools** [settings]: Your catalogue of materials and what you own. → `In the app, under Vendors, Filaments and Spools`
- **custom-fields** [settings]: Add your own fields such as drying date or shelf. → `Settings → Extra Fields`
- **labels** [settings]: Make QR-code labels for spools. → `Print label designer in the app`
- **printer-integration** [extend]: Auto-update usage from your printer. → `Moonraker, OctoPrint and the REST API`
- **client** [code]: Screens and charts. → `client_v2/src`
- **server** [code]: New endpoints and rules. → `spoolman/`

## Must keep working
- Alembic migrations. Add new ones; never edit old ones.
- The REST API contract used by printer software.
- Spool weight calculations.

## Staying updatable
Use extra fields and the API where possible. Keep code changes small and in new modules.

## Data, costs and safety
- Personal data: **no**. Stored in: A SQLite database in the data folder (a Docker volume). Contains only your filament inventory. Back up the data folder.
- Service: Printer software integration (Moonraker or OctoPrint) (optional, free): Automatically deduct filament as you print.
- Setting `SPOOLMAN_DB_TYPE`: Database type. Defaults to sqlite.
- Setting `TZ`: Your time zone for correct timestamps.
- It has no login by default. Keep it on your home network or behind a login proxy.

---

# Customising Spoolman

Spoolman is small enough to read in one sitting: a FastAPI server, a database and a React client.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| API and logic | spoolman/ |
| Database migrations | migrations/ |
| Current React client | client_v2/ |
| Older client | client/ |
| Tests | tests/ |
| Docker | Dockerfile |

## Use the gentlest change first

1. **Settings (no code):** extra fields, vendors, filaments and labels.
2. **Extend:** printer integrations and the REST API.
3. **Code:** endpoints and screens.

## Recipes

- **New spool field:** add a column and Alembic migration, extend the Pydantic models and routes, then add it to the spool form.
- **Alert script:** poll `/api/v1/spool` and send a notification for spools below your threshold.

## Running and checking your changes

- `uv run pytest` for the API.
- Create a spool, use some filament and check the remaining weight.

## Pitfalls

- Weights are stored in grams. Keep units consistent.
- Don't edit shipped migrations.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/spoolman/488eb74/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/spoolman/488eb74/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/spoolman/488eb74/r2/SKILL.md)