Firefly Iii Laravel Package

Technical Evaluation

Architecture fit. Firefly III is not a library — it is a complete, opinionated Laravel monolith (PHP 8.3+, Laravel 11.x, Blade + Vue/Inertia-style front end, MySQL 8 / PostgreSQL 13+ / SQLite back end). composer require grumpydictator/firefly-iii is not a supported consumption path, which is exactly why the dependents count is zero. Any evaluation must therefore frame "integration" as service integration or fork, never as a package dependency. It fits a stack when the requirement is "a personal-finance ledger and rules engine with an API," and fits poorly when the requirement is "a billing/subscription engine" or "a multi-tenant finance SaaS." The domain model is genuinely strong for the former: double-entry transactions, multi-currency with per-transaction exchange rates, budgets, categories, tags, piggy banks (savings goals), recurring transactions, bills, rule-based auto-categorisation, and a JSON:API surface with OAuth2.

Integration feasibility. High for read/write API integration; medium for deep customisation. The REST API is documented and reasonably stable within a major, and is protected by Laravel Passport (OAuth2 authorization-code + personal access tokens). Webhooks support HMAC-SHA256 signing with a per-webhook secret, which is workable for event-driven sync. Bulk historical data lands through CSV/OFX/QIF import, or via the separately maintained firefly-iii-data-importer service. There is no officially supported PHP SDK, so expect to hand-roll a thin client with retry, pagination, and rate-limit handling. Custom fields are limited — the data model is fixed, so anything Firefly does not model natively (e.g. approval workflows, cost-centre hierarchies, invoice attachments with structured metadata) becomes a fork or a sidecar database.

Technical risk. Four material risks, in order:

1. AGPL-3.0 is the gating risk. Network copyleft means that if you modify Firefly and expose it to users over a network, you must offer the corresponding source. Running it unmodified behind your own SSO for internal staff is generally defensible; white-labelling it inside a commercial product, or embedding it in a SaaS offering, is not without either publishing your modifications or obtaining commercial terms. Legal review is a prerequisite, not a follow-up.
2. No multi-tenancy. One instance serves one organisation; users within it are separated but administrative surface, configuration, and exchange-rate/currency settings are global. Any per-tenant isolation requirement means one instance per tenant, which multiplies operational cost linearly.
3. Single-maintainer concentration. The project is historically driven by one primary author with a contributor community. Release cadence is fast (monthly-ish majors and minors) and majors do carry breaking changes and non-trivial migration steps. Community support via GitHub Discussions only — no SLA, no vendor.
4. Metadata anomaly. The stated last release of 2026-10-17 is in the future relative to any real evaluation date; treat the score inputs as unverified until you check tags, commit activity, and open-issue trends yourself.

Secondary risks: financial data sensitivity (GDPR/CCPA scope, encryption at rest is your responsibility), dependency on third-party currency-rate APIs for multi-currency correctness, and webhook delivery being at-most-once with no built-in replay queue.

Key questions to resolve before commitment.

• Is the requirement a ledger and rules engine (Firefly's strength) or a product surface we ship to customers (where AGPL and single-tenant bite)?
• Do our users need isolation that Firefly cannot express, or is one shared instance with per-user accounts acceptable?
• Who owns the upgrade treadmill — platform team running stock containers, or an engineering team owning a fork?
• Which behaviours must be custom, and can they be achieved via the rules engine + webhooks + a sidecar service rather than patching core?
• What is our data-retention and export obligation, and does Firefly's API/CSV export satisfy it?
• Is there budget for a commercial AGPL exception, or is the licence a hard stop?

Integration Approach

Stack fit. Firefly slots in cleanly as a bounded-context service in a container platform: official fireflyiii/core images, an external MySQL 8 or PostgreSQL 13+ instance, Redis for cache and queue, and a cron-driven scheduler. Treat it as an appliance with a database — not as a codebase you edit. The natural integration boundary is the JSON:API plus webhooks; everything else (identity, permissions, reporting, downstream accounting) should live in your own services.

Migration path. Sequence it as a strangler-style adoption rather than a rewrite:

1. Shadow mode. Stand up a pinned-version instance with a dedicated database. Import 12–24 months of historical data via CSV/OFX through the data importer to validate that the domain model can represent your real accounts, splits, transfers, and multi-currency positions without lossy mapping. This is the cheapest possible go/no-go test and it surfaces data-model gaps early.
2. Read-only mirroring. Sync transactions outward to your system of record (or inward from it) on a schedule using the API. Establish idempotency keys and a reconciliation job that compares balances daily.
3. Write-back and events. Enable webhooks for transaction create/update/delete, verify HMAC signatures, and add a dead-letter queue on your side since Firefly will not retry reliably.
4. Cutover by capability. Move budgeting/rules/reporting users first; keep payments and reconciliations in the incumbent until two clean month-ends have passed.
5. Fork only if forced. If custom behaviour is unavoidable, decide explicitly between (a) a rules-engine + sidecar approach, (b) a thin fork with a documented patch set and a rebase cadence each major, or (c) exit. Do not drift into an undocumented fork.

Compatibility. Pin to a specific minor and pin the image digest. Maintain a written compatibility matrix across: Firefly major ↔ PHP version ↔ Laravel major ↔ MySQL/PostgreSQL major. Validate the data importer version against the core version — they drift independently. If you sit behind a reverse proxy with SSO (Authelia, oauth2-proxy), confirm the auth path you intend (Firefly supports LDAP and 2FA natively; OIDC is via proxy plus AUTHENTICATION_GUARD configuration) and test the API token flow separately from the browser flow, because proxied SSO and Passport tokens take different paths.

Sequencing. Weeks 1–2: licence review and POC deployment. Weeks 3–5: historical import validation and data-model gap analysis. Weeks 6–10: API client, webhook consumer, reconciliation job, monitoring. Weeks 11–14: security hardening (TLS, secrets management, DB encryption, audit logging, backup/restore drills) and a rehearsed upgrade. Then a staged rollout. Budget a recurring 1–2 days per month for upgrade triage regardless of path.

Operational Impact

Maintenance. The recurring cost is upgrade management, not runtime babysitting. Firefly ships frequently; each major can require manual migration steps and occasionally a config or environment-variable change. Adopt a policy of staying one minor behind latest, upgrading monthly in staging, and never skipping a major. Database migrations are the highest-risk operation — take a verified snapshot immediately before every upgrade and test the rollback path, because Laravel migrations are not reliably reversible.

Support. Community-only. There is no vendor, no paid support tier, and no security advisory SLA beyond what the maintainer chooses to publish. For a finance-adjacent system this means you need an internal owner who can read Laravel stack traces and PHP logs. Response to a critical CVE in a transitive Laravel dependency depends entirely on the upstream release cadence — factor that into your risk register and be prepared to patch a fork on your own clock.

Scaling. Adequate for the intended scale (tens to low hundreds of users, hundreds of thousands of transactions) on modest hardware. Constraints appear as: report generation and dashboard queries becoming slow on large transaction tables without index tuning and materialised summary tables; queue backlog if the worker is undersized during bulk imports; and the single-database-per-instance model making horizontal scale-out tenant-by-tenant expensive. There is no sharding story. Plan for read replicas at the database layer rather than application-level scaling.

Failure modes to instrument explicitly.

• Missed cron — recurring transactions and bill predictions silently stop being generated. Alert on scheduler heartbeat, not just on process liveness.
• Queue worker death — imports and webhooks stall with no user-visible error. Alert on queue depth and failed-job count.
• Exchange-rate provider outage — multi-currency balances and reports become wrong rather than unavailable, which is worse. Monitor rate freshness and fall back to manual rates.
• Webhook delivery failure — Firefly treats webhooks as fire-and-forget; duplicate and dropped deliveries are both possible. Consumer must be idempotent and reconcile nightly.
• Failed or partial migration — the highest-severity event. Requires restore-from-snapshot runbook, tested quarterly.
• Import duplication — re-running an import without dedupe creates phantom transactions that corrupt reconciliations. Enforce a hash-based dedupe key in the importer pipeline.
• Disk growth — attachments and the storage/ tree grow unbounded; monitor and set retention.

Ramp-up. Two distinct skill profiles. Operations (run stock containers, cron, backups, monitoring, upgrades): roughly 3–5 days for a competent platform engineer, provided the upgrade runbook exists. Engineering (API client, webhook consumer, reconciliation, eventual fork): 2–3 weeks for a Laravel-proficient developer to be productive in the codebase, longer to be safe in the domain model. Non-technical finance users need about half a day of onboarding to the accounts/budgets/rules mental model, and should be warned that Firefly's terminology (withdrawal/deposit/transfer, piggy banks) differs from mainstream accounting tools. Document the runbook before go-live, not after the first failed upgrade.