# Project pack: InvoiceShelf @ 98acbe2

Facts about **InvoiceShelf** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> InvoiceShelf is invoicing software for freelancers and small businesses that you run yourself. Create quotes and invoices, turn them into tidy PDFs and email them to customers. Record payments, see who still owes you, log expenses and set up repeat invoices for regular work. Customers get their own page to see their invoices, and your business records stay on your own server.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://raw.githubusercontent.com/InvoiceShelf/InvoiceShelf/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/InvoiceShelf/InvoiceShelf
- Pinned commit: `98acbe2622da3d5bc5738b16f5e7ca6688cdd95d`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/InvoiceShelf/InvoiceShelf/archive/98acbe2622da3d5bc5738b16f5e7ca6688cdd95d.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://docs.invoiceshelf.com
- Live demo: https://demo.invoiceshelf.com. Official public demo with sample data that resets automatically; it may run a newer version than the pinned 2.4.7. Don't enter real customer details.
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (for example customers opening the portal), you must offer them your source code under the same licence, for example with a link to your copy. Using it for your own business has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/InvoiceShelf/InvoiceShelf bespoke-invoiceshelf
  cd bespoke-invoiceshelf
  git checkout --detach 98acbe2622da3d5bc5738b16f5e7ca6688cdd95d
  # Prepare development requirements and local configuration first.
  # Setup notes: interactive Docker setup (MySQL/MariaDB, PostgreSQL or SQLite, optional Gotenberg); then pnpm install && pnpm dev, app at http://invoiceshelf.test. Native alternative: composer run dev
  ./devenv
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  git clone https://github.com/InvoiceShelf/docker.git invoiceshelf
  cd invoiceshelf
  cp docker-compose.sqlite.yml docker-compose.yml
  # Optional: in docker-compose.yml change image: invoiceshelf/invoiceshelf:latest to :2.4.7 to stay on this exact release.
  docker compose up -d
  # Then open http://localhost:8090 and finish the setup wizard.
  ```
- Tools these commands use: Docker with Docker Compose, For development, Docker via ./devenv (or PHP 8.4 with Composer natively), plus Node 24 (.node-version) with pnpm
- Develop: `./devenv   # interactive Docker setup (MySQL/MariaDB, PostgreSQL or SQLite, optional Gotenberg); then pnpm install && pnpm dev, app at http://invoiceshelf.test. Native alternative: composer run dev`
- Test: `php artisan test --compact`
- Check/lint: `vendor/bin/pint --test && pnpm test   # pnpm test runs ESLint on resources/scripts`
- Build: `pnpm build`
- Stack: php, typescript, vue (Laravel 13, Vue 3, Pinia, Tailwind CSS 4, Vite, Pest). Difficulty for a non-developer with an AI: **moderate**. A conventional Laravel + Vue app with an AGENTS.md for AI coding tools. Company details, number formats, taxes, payment methods, custom fields and email wording are settings, and a built-in command scaffolds your own invoice and quote PDF layouts. Code changes need a Pest test and must work on SQLite, MySQL and PostgreSQL. The pinned 2.4.7 is the stable 2.x line, which upstream supports with security fixes until 1 September 2027.
- The project's own AI instructions, in the repository: `AGENTS.md`, `.github/CONTRIBUTING.md`.
Personal data: **yes**. Stored in: SQLite file in the storage volume by default (or MySQL/MariaDB/PostgreSQL); PDFs, logos, receipts and custom PDF templates in storage/ or on an assigned file disk. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/invoiceshelf/98acbe2/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/invoiceshelf/98acbe2/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/invoiceshelf/98acbe2/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/invoiceshelf/98acbe2/r3/SKILL.md)