# Project pack: Firefly III @ b9c3100

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

> Firefly III is a personal money manager. You record your bank accounts, spending and income, and it shows where your money goes with budgets, categories, charts and reports. Rules can sort your spending for you, and "piggy banks" help you save towards a goal. It runs on your own computer or server, so your bank data never has to go to the cloud.

## Version and source
- Repository: https://github.com/firefly-iii/firefly-iii
- Pinned commit: `b9c31006e8d3008df3d12e23de86b66088c9480e`. 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/firefly-iii/firefly-iii/archive/b9c31006e8d3008df3d12e23de86b66088c9480e.zip
- Official docs: https://docs.firefly-iii.org
- Live demo: https://demo.firefly-iii.org. Public demo with an example administration already filled in. Shared with everyone, so don't enter anything real.
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. Private use has no extra obligations.

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

  ```sh
  git clone https://github.com/firefly-iii/firefly-iii bespoke-firefly-iii
  cd bespoke-firefly-iii
  git checkout --detach b9c31006e8d3008df3d12e23de86b66088c9480e
  # Prepare development requirements and local configuration first.
  # Follow development setup in this checkout’s README and agents.md; configure a local database first.
  ```

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 docker-compose.yml and database.env (save as .db.env) from github.com/firefly-iii/docker, and .env.example from this repo (save as .env). Set APP_KEY to a random 32-character string, and set the same database password in .env (DB_PASSWORD) and .db.env (MYSQL_PASSWORD). Then run: docker compose -f docker-compose.yml up -d --pull=always # then open http://localhost and create the first account
  ```

- Needs: Docker with Docker Compose, or for development PHP 8.5 + Composer + Node + MySQL/PostgreSQL/SQLite
- Test: `composer unit-test && composer integration-test`
- Stack: php, javascript, blade (Laravel 13, Alpine.js, Bootstrap 5, AdminLTE 4, Vite). Difficulty for a non-developer with an AI: **advanced**. A large Laravel app (PHP 8.5) with a strict double-entry bookkeeping model, a big REST API and many tests. Most personal changes are better done through rules, webhooks or the API than in the code.

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

## Customisation points (settings → extend → code)
- **currency-language-and-dates** [settings]: Main currency, language, date format, first day of the financial year and which home-screen boxes to show. → `Options → Preferences (languages listed in config/firefly.php; translations in resources/lang/)`
- **rules** [settings]: Automatically set the category, budget or tags of a transaction based on its description, amount or account. → `Automation → Rules (engine in app/TransactionRules/)`
- **budgets-bills-piggy-banks** [settings]: Monthly budgets with auto-budget, expected bills with reminders, and savings goals. → `Budgets, Subscriptions (bills) and Piggy banks pages`
- **notifications** [settings]: Bill reminders and security alerts by email, Slack or Pushover. → `Options → Preferences → Notifications (channels in config/notifications.php)`
- **webhooks** [extend]: Send new or changed transactions to another service such as n8n, Home Assistant or your own script. → `Automation → Webhooks (app/Api/V1/Controllers/Webhook/, app/Generator/Webhook/)`
- **rest-api** [extend]: Scripts, phone shortcuts, spreadsheets and third-party apps that read or add transactions. → `REST API at /api/v1 (routes/api.php); personal access tokens under Options → Profile → Personal Access Tokens`
- **pages-and-views** [code]: New screens, changed layouts and styling. → `resources/views/** (Blade templates, layout in resources/views/layout/v3/), resources/assets/v3/js/pages/**, resources/assets/v3/sass/app.scss`
- **backend-logic** [code]: New reports, new calculations or new kinds of data. → `app/Http/Controllers/**, app/Repositories/**, app/Generator/Report/**, routes/web.php`

## Must keep working
- Existing accounts, transactions and balances. Back up the database and upload volumes before changing anything.
- Double-entry bookkeeping. Every transaction must keep its source and destination account, and balances must still add up.
- Database changes need a new Laravel migration in database/migrations/; never edit old ones.
- Login, two-factor authentication and API token security.
- The REST API (routes/api.php), because the Data Importer and third-party apps depend on it.

## Staying updatable
Firefly III changes quickly and is hard to merge. Use rules, budgets, webhooks and the REST API first. Small companion scripts or apps that talk to the API keep working after upgrades; code changes need re-merging every release.

## Data, costs and safety
- Personal data: **yes**. Stored in: MySQL/MariaDB (default Docker setup), PostgreSQL or SQLite; uploaded files in the firefly_iii_upload volume. This is detailed financial data. Back up both the database volume and the upload volume before upgrades or code changes. Options → Export data gives you a CSV copy of your transactions.
- Service: Firefly III Data Importer (separate app) (optional, free (self-hosted)): Import bank statements from CSV files or bank-connection services.
- Service: Email (SMTP or Mailgun, Mailersend and similar) (optional, free with most providers): Bill reminders, security warnings and password resets.
- Service: Slack or Pushover (optional, free tier): Push notifications for bill reminders and security alerts.
- Setting `APP_KEY` (**secret**: the person enters it themselves, never in chat): A random string of exactly 32 characters. Never share it or paste it into an AI chat.
- Setting `SITE_OWNER`: Your email address, shown to other users in some error messages.
- Setting `DB_CONNECTION`: Which database to use (mysql, pgsql or sqlite).
- Setting `DB_PASSWORD` (**secret**: the person enters it themselves, never in chat): The database password. Must match the password in .db.env when using the Docker setup.
- Setting `TZ`: Your time zone (e.g. Europe/London).
- Setting `DEFAULT_LANGUAGE`: Language for new users and the login page (e.g. en_GB).
- Setting `APP_URL`: The address you open Firefly III at. Used for links in emails.
- Setting `TRUSTED_PROXIES`: Set to ** when Firefly III sits behind a reverse proxy.
- Setting `STATIC_CRON_TOKEN` (**secret**: the person enters it themselves, never in chat): A 32-character token so a daily cron job can create recurring transactions and send bill reminders.
- Holds detailed financial records. Use a strong password, turn on two-factor authentication and put it behind HTTPS before exposing it to the internet.
- APP_KEY, database passwords, STATIC_CRON_TOKEN and API tokens are secrets. Never paste them into an AI chat.
- Firefly III makes no outside connections until you turn on a feature that needs one (such as webhooks or notifications).

---

# Customising Firefly III

Firefly III is a large Laravel app with strict bookkeeping rules. **Almost every personal adaptation is a setting, a rule or an API script.** Treat code changes as a last resort, because they must be re-merged with every release.

## Level 1: Settings (no code)
- **Currency, language and dates:** Options → Preferences. Pick your main currency, language (e.g. English (GB)), date format and the start of your financial year. The login page language comes from `DEFAULT_LANGUAGE`.
- **Home screen:** Options → Preferences → Home screen accounts, plus the options for which boxes and charts to show.
- **Budgets:** monthly amounts per budget, with *auto-budget* to top up or roll over each month.
- **Subscriptions (bills):** expected regular payments. Firefly III links matching transactions and warns you before they are due.
- **Piggy banks:** savings goals with a target amount and date.
- **Rules (Automation → Rules):** "if the description contains *Tesco*, set the category to *Groceries*". Rules can run on new transactions or on old ones in bulk.
- **Notifications:** Options → Preferences → Notifications. Email needs the `MAIL_*` settings; Slack and Pushover are set up in the app.

## Level 2: Extend (no fork)
- **Webhooks (Automation → Webhooks):** Firefly III sends a POST to your URL when a transaction is stored, updated or deleted. Good for n8n, Home Assistant or a small script that messages your phone.
- **REST API (`/api/v1`):** create a personal access token under Options → Profile → Personal Access Tokens. Almost every part of the app is in the API, so phone shortcuts, spreadsheets and small companion apps can read and add data.
- **Data Importer:** a separate official app that imports bank CSV files and bank connections into Firefly III.
- **Cron:** set `STATIC_CRON_TOKEN` and call `/api/v1/cron/<token>` once a day so recurring transactions and bill warnings run.

## Level 3: Code
Read upstream `agents.md` first. Then:

| Change | Where |
|---|---|
| Page templates | `resources/views/**` (Blade); main layout in `resources/views/layout/v3/` |
| Page scripts and styling | `resources/assets/v3/js/pages/**`, `resources/assets/v3/sass/app.scss` (built with Vite) |
| Web routes and controllers | `routes/web.php`, `app/Http/Controllers/**` |
| API endpoints | `routes/api.php`, `app/Api/V1/Controllers/**` |
| Data access | `app/Repositories/**` |
| Reports and charts | `app/Generator/Report/**`, `app/Generator/Chart/**` |
| Rule actions | `app/TransactionRules/Actions/**` |
| New data | a new migration in `database/migrations/` plus a model in `app/Models/` |
| Text | `resources/lang/en_US/*.php` (other languages come from Crowdin) |

## Running locally
- **Just use it:** the official Docker Compose setup.
  1. Download `docker-compose.yml` and `database.env` from github.com/firefly-iii/docker. Save `database.env` as `.db.env`.
  2. Download `.env.example` from this repo and save it as `.env`.
  3. Set `APP_KEY` to a random 32-character string.
  4. Use the same database password in `.env` (`DB_PASSWORD`) and `.db.env` (`MYSQL_PASSWORD`). Change it *before* the first start.
  5. Run `docker compose -f docker-compose.yml up -d --pull=always` and open http://localhost.
- **Develop:** PHP 8.5, Composer and a database (SQLite works with `DB_CONNECTION=sqlite`). Run `composer install`, copy `.env.example` to `.env`, then `php artisan key:generate` and `php artisan migrate`. Build the frontend with `npm install` at the repo root, then `npm run build` inside `resources/assets/v3/`.
- **Check:** `composer unit-test` and `composer integration-test`.

## Pitfalls
- Back up the database and the upload volume first. Money records are hard to rebuild.
- Every transaction has a source and a destination account (double-entry). Don't "simplify" this away; balances and reports depend on it.
- `APP_KEY` must stay the same after the first start, or encrypted data and sessions break.
- Changing the database password after the first start locks Firefly III out of its own database.
- Keep using the API for automations. It is stable across releases, while internal code moves often.

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