# Project pack: InvoicePlane @ ef00e30

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

> InvoicePlane is a self-hosted invoicing application. You keep a list of clients, create quotes and invoices from templates, record payments, send reminders and generate PDFs. It is built with PHP and MySQL and runs on ordinary web hosting as well as Docker.

## Version and source
- Repository: https://github.com/InvoicePlane/InvoicePlane
- Pinned commit: `ef00e30708a8024debda68dbc2674b775bbc1ee4`. 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/InvoicePlane/InvoicePlane/archive/ef00e30708a8024debda68dbc2674b775bbc1ee4.zip
- 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/InvoicePlane/InvoicePlane bespoke-invoiceplane
  cd bespoke-invoiceplane
  git checkout --detach ef00e30708a8024debda68dbc2674b775bbc1ee4
  # Prepare development requirements and local configuration first.
  cp ipconfig.php.example ipconfig.php
  docker compose up -d --build
  ```

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
  Download the latest release zip from https://github.com/InvoicePlane/InvoicePlane/releases, upload it to PHP hosting with MySQL, copy ipconfig.php.example to ipconfig.php, set your site address, and open the site in a browser to run the setup.
  ```

- Needs: Docker, or PHP 8.1+ with MySQL or MariaDB and a web server
- Develop: `docker compose up -d --build`
- Test: `composer test`
- Check/lint: `composer lint`
- Stack: php, javascript (CodeIgniter 3, Bootstrap). Difficulty for a non-developer with an AI: **moderate**. A classic PHP application on CodeIgniter 3 with modules, views and templates. Templates and languages are easy to change; new features follow familiar MVC patterns.

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

## Customisation points (settings → extend → code)
- **invoice-templates** [settings]: Wording, layout and numbering of invoices and quotes. → `Settings → Invoice templates, Email templates`
- **taxes-and-payments** [settings]: Tax rates and how you accept payment. → `Settings → Taxes, Payment methods`
- **languages** [settings]: Translate or reword the interface. → `application/language/`
- **pdf-and-themes** [extend]: Custom PDF layouts and colours. → `application/views/invoice_templates and assets/`
- **modules** [code]: New features such as reports or custom fields. → `application/modules/`

## Must keep working
- Invoice numbering and totals calculation.
- Database migrations. Add new ones; never edit old ones.
- Permission checks for users and client logins.

## Staying updatable
Use custom templates and a new module. Avoid editing core files, so upgrades stay simple.

## Data, costs and safety
- Personal data: **yes**. Stored in: A MySQL database plus an uploads folder. Contains client names, addresses and amounts. Back up the database and uploads regularly.
- Service: Email (SMTP) (optional, usually free to a few dollars): Send invoices and reminders.
- Service: Online payments (Stripe or PayPal) (optional, per-payment fees): Let clients pay online.
- It holds client contact details and amounts. Use a strong admin password and HTTPS.
- Remove the setup files after installing.

---

# Customising InvoicePlane

InvoicePlane is plain PHP on CodeIgniter 3, so the structure is easy to follow.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Controllers, models and views | application/modules/<feature>/ (controllers, models, views) |
| Invoice and quote PDF layouts | application/views/invoice_templates/ |
| Email templates | the Email templates settings page and application/views |
| Translations | application/language/<language>/ |
| Database schema and migrations | application/migrations/ and the install SQL |
| Styles and scripts | assets/ |
| Docker setup | compose.yml and resources/docker/ |

## Use the gentlest change first

1. **Settings (no code):** templates, taxes, numbering, payment methods and languages.
2. **Extend:** custom invoice templates and CSS.
3. **Code:** a new module for new features.

## Recipes

- **New PDF layout:** copy a template in `application/views/invoice_templates/pdf`, edit it and choose it in Settings.
- **New client field:** add a migration, include it in the clients model and form view, and show it in the invoice template.

## Running and checking your changes

- Start with `docker compose up -d --build` and create a client, an invoice and a PDF.
- `composer lint` and the PHPUnit tests where present.
- Check totals with several tax rates.

## Pitfalls

- Do not commit `ipconfig.php` with real settings.
- Test money maths with rounding cases.

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