A web application for cataloguing the contents of packing boxes before a house move. Create labelled boxes, record what's inside, attach photos, print QR code labels, and search across all boxes to find where any item is packed.
- Create boxes with a name, description, location, and type
- Record contents — free-text inventory list per box, full-text searchable
- Photo attachments — select multiple photos at once; stored on disk with auto-generated thumbnails
- QR code labels — generated automatically on box creation; print directly to a Brother QL thermal label printer
- Full-text search — find which box contains any item by name, description, contents, type, or location; natural sort order (Box 2 before Box 10)
- Box types — define reusable categories (e.g. Bedroom, Kitchen) and assign them to boxes; managed via a modal in the UI without leaving the page
- Geolocation logging — records GPS coordinates when a box's QR code is scanned; the last 50 scans are shown on the box page with timestamps and locations. Requires HTTPS — browsers block geolocation on plain
http://addresses (see INSTALL.md) - Named locations — map GPS coordinates to human-readable names (e.g. Storage Unit) with a configurable radius; scans within range display the name instead of raw coordinates
- Soft delete / restore — mark boxes as disposed without losing their records; search disposed boxes separately and restore them if needed
- Web-based config & status — configure database, printer, and storage settings through the UI without editing files; health dashboard shows DB connectivity, upload storage, printer reachability, and schema migration status; app redirects to the config page automatically on first run
If you find Boxmaster useful, consider buying me a coffee — it's always appreciated!
| Layer | Technology |
|---|---|
| Language | Python 3.11+ |
| Framework | Flask 3.x |
| ORM | SQLAlchemy 2.x + Flask-Migrate (Alembic) |
| Database | MySQL 8+ |
| Templates | Jinja2 + Bootstrap 5.3 |
| Image processing | Pillow |
| QR codes | qrcode[pil] |
| Label printing | brother_ql |
| Printer discovery | zeroconf (mDNS/Bonjour) |
| Deployment | Docker / Gunicorn |
See INSTALL.md for full installation instructions.
docker compose up --buildOpen http://localhost:5091 — the app will redirect you to the Settings page on first run. Fill in the database details and save, then visit Config → Status to apply the database schema.
- New Box — click New Box in the navbar, fill in the name and description, click Create Box
- Add contents — on the box page, open Box Contents and type or paste the item list
- Add photos — open Add Photos, select one or more images, and click Upload Photos
- Print label — click Print Label to send a QR + text label to the configured Brother printer
- Search — use the Search box to find any item by name, description, contents, type, or location; click Show All to list every box
- Dispose — when a box is unpacked, use the Dispose page to mark it done; disposed boxes can be searched and restored from there
app/
├── __init__.py # Flask app factory + first-run redirect
├── config.py # Config from .env (no hardcoded defaults)
├── extensions.py # SQLAlchemy + Migrate instances
├── models.py # Box, BoxType, Photo, ScanLog, NamedLocation ORM models
├── routes/
│ ├── boxes.py # CRUD, search, dispose, restore
│ ├── photos.py # Photo serving + thumbnails
│ ├── labels.py # QR label generation + printing
│ ├── api.py # AJAX endpoints — autocomplete, box types, named locations, scan log
│ └── config_bp.py # Settings, status dashboard, printer discovery
├── utils/
│ ├── qr.py # QR code generation
│ ├── label.py # Brother QL label builder
│ └── image.py # Thumbnail generation
└── templates/ # Jinja2 / Bootstrap 5 templates
migrations/ # Alembic migration scripts
uploads/ # Photo files (Docker volume)
MIT — see LICENCE.
Please note that AI (Claude) was used in the creation of this code.
