# Project pack: InvenTree @ d11b74f

Facts about **InvenTree** 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.

> InvenTree is an inventory system for parts and stock. You define parts with categories and parameters, track stock locations and quantities, manage suppliers and purchase orders, and build assemblies from bills of materials. It has a plugin system, an API and barcode label support, and suits workshops, electronics hobbyists and makerspaces.

## Version and source
- Repository: https://github.com/inventree/InvenTree
- Pinned commit: `d11b74fd857a6ebf47658b707605a64a10be764f`. 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/inventree/InvenTree/archive/d11b74fd857a6ebf47658b707605a64a10be764f.zip
- Official docs: https://docs.inventree.org
- Live demo: https://inventree.org/demo. Official demo instance. Don't enter real data.
- 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/inventree/InvenTree bespoke-inventree
  cd bespoke-inventree
  git checkout --detach d11b74fd857a6ebf47658b707605a64a10be764f
  # Prepare development requirements and local configuration first.
  pip install invoke
  invoke dev.setup-dev
  invoke dev.server
  ```

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 Docker guide at https://docs.inventree.org/en/stable/start/docker, which provides the docker-compose.yml, env file and Caddy proxy.
  ```

- Needs: Docker for a trial, Python 3.11 and Node 22 for development
- Develop: `invoke dev.server`
- Test: `invoke dev.test`
- Check/lint: `invoke dev.lint`
- Stack: python, typescript (Django, Django REST Framework, React, Mantine, Vite). Difficulty for a non-developer with an AI: **advanced**. A mature Django and React project with a plugin system. Most customisation is parameters, categories and plugins; deeper changes involve the full stack.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **categories-and-parameters** [settings]: Structure for parts such as resistors or screws. → `Parts → Categories, Parameters`
- **stock-and-locations** [settings]: Shelves, bins and rooms. → `Stock → Locations`
- **label-and-report-templates** [extend]: Printable barcodes, packing lists and reports. → `Admin Center → Label Templates, Report Templates`
- **plugins** [extend]: Barcode, supplier import, panels and custom actions. → `src/backend/InvenTree/plugin and the plugin docs`
- **api** [extend]: Read and write parts and stock from scripts. → `/api/ and the Python client`
- **react-ui** [code]: Screens and tables. → `src/frontend/src`
- **django-core** [code]: New models and rules. → `src/backend/InvenTree`

## Must keep working
- Django migrations. Add new ones; never edit old ones.
- Stock tracking and the transaction history.
- Plugin API compatibility.

## Staying updatable
Use parameters, templates and plugins first. Keep source changes in a separate plugin where possible.

## Data, costs and safety
- Personal data: **no**. Stored in: A database plus a media folder for images and attachments. Contains your inventory, supplier prices and customers. Back up the database and the media folder.
- Service: Email (SMTP) (optional, usually free to a few dollars): Notifications and password resets.
- Service: Supplier plugins (DigiKey, Mouser, LCSC) (optional, free keys): Import part data from suppliers.
- Setting `INVENTREE_SITE_URL`: The address people use to reach InvenTree.
- Setting `INVENTREE_DB_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password.
- Setting `INVENTREE_ADMIN_PASSWORD` (**secret**: the person enters it themselves, never in chat): Password of the first admin user. Never paste it into an AI chat.
- Prices and supplier details may be commercially sensitive. Use a strong admin password and HTTPS.
- Plugins run code on your server. Install only trusted ones.

---

# Customising InvenTree

InvenTree has a Django back end, a React front end and a plugin system. The repo has AGENTS.md and CLAUDE.md with conventions.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Django apps (part, stock, order, build, company) | src/backend/InvenTree/<app>/ |
| Plugin system and built-in plugins | src/backend/InvenTree/plugin/ |
| React front end | src/frontend/src/ |
| Reusable front-end library | src/frontend/lib/ |
| Dev tasks | tasks.py |
| Container deployment | contrib/container/ |
| Docs | docs/ |

## Use the gentlest change first

1. **Settings (no code):** categories, parameters, locations, label and report templates.
2. **Extend:** plugins and the API.
3. **Code:** Django apps and React screens.

## Recipes

- **New plugin:** create a plugin class with the mixins you need (for example barcode or API), and install it as a Python package or drop it in the plugin folder.
- **New report:** copy a report template, edit the HTML and register it in the Report Templates settings.

## Running and checking your changes

- `invoke dev.test` for the apps you changed and `invoke dev.lint`.
- Create a part, add stock, make a purchase order and receive it.

## Pitfalls

- Back up the database before running migrations.
- Plugin versions must match your InvenTree version.

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