Firefly III

Firefly III is a fully‑self‑hosted financial management platform that implements double‑entry bookkeeping and multi‑currency support. From a developer’s perspective, it is essentially a data‑centric web service exposing a rich JSON REST API that can be consumed by native apps, scripts, or other services. Transactions are stored in a relational database with an audit trail that records every change, making it suitable for applications where financial integrity and traceability are paramount.

Technical Stack & Architecture

• Backend: PHP 8.x running on the Symfony framework (v5+). Symfony’s dependency injection, event dispatcher, and modular bundle system provide a clean separation of concerns.
• Database: PostgreSQL (primary) or MySQL/MariaDB. The schema follows standard accounting tables (accounts, transactions, categories, budgets) and is fully versioned via Doctrine migrations.
• API: A token‑based OAuth2 implementation powered by Symfony Security. Endpoints are RESTful, return JSON, and support pagination, filtering, and field selection.
• Frontend: Vue.js (2.x) with Vuetify for the admin UI. The SPA communicates with the API via Axios, enabling a clear boundary between presentation and business logic.
• Background Jobs: Symfony Messenger with Redis or Doctrine transport, used for import jobs, rule processing, and scheduled reports.

The application follows a clean‑architecture approach: domain services (e.g., rule engine, currency conversion) are isolated from infrastructure adapters. This makes unit testing straightforward and allows developers to replace components (e.g., swap Redis for RabbitMQ) with minimal friction.

Core Capabilities & Developer APIs

• Transaction Management: CRUD operations for debits, credits, and transfers. Supports multi‑currency amounts with real‑time exchange rate lookup via external services.
• Rule Engine: Declarative rules written in JSON or YAML that trigger on transaction import. Rules can create categories, tags, or even generate new transactions.
• Reporting: Pre‑built endpoints expose aggregated data (expenses per category, budget variance). Custom reports can be defined via SQL views or API calls.
• Importers: The “Data Importer” component accepts CSV, QIF, OFX, and JSON. It is extensible via PHP plugins that can parse proprietary bank formats.
• Webhooks & Events: Subscribers can listen to TransactionCreated, RuleApplied, etc., and trigger external actions. The webhook system supports HTTPS callbacks with signature verification.

Deployment & Infrastructure

• Containerization: Official Docker images (PHP, Nginx, PostgreSQL) are available on Docker Hub. Compose files include optional Redis and Celery workers.
• Scalability: Horizontal scaling is achieved by separating the API, worker, and database layers. The API can be load‑balanced behind Nginx/HAProxy; workers can run in parallel to process imports and rule evaluations.
• Self‑Hosting Requirements: A LAMP/LEMP stack with PHP 8+, Composer, and a PostgreSQL database. SSL termination is recommended for API security.
• Backup & Restore: Built‑in cron jobs can dump the database and export attachments. The API also supports a /backup endpoint for full snapshots.

Integration & Extensibility

• Plugin System: Symfony bundles can be added to extend functionality (e.g., new importers, custom reports). The plugin API exposes hooks for events and UI panels.
• External Authentication: OAuth2, LDAP, or SAML can be configured via Symfony security providers.
• Custom UI: The Vue.js front‑end is modular; developers can replace or augment components without touching the API.

Developer Experience

• Documentation: Comprehensive Swagger/OpenAPI spec, code comments, and a dedicated dev guide. The API reference includes example payloads.
• Community & Support: Active GitHub repository with issue tracking, a Discord channel for real‑time help, and frequent releases.
• Testing: PHPUnit tests cover 90%+ of the codebase. CI pipelines run on GitHub Actions.

Use Cases

• Personal Finance Dashboards: Embed the API into a mobile app to provide real‑time budgeting and transaction history.
• Enterprise Expense Management: Use the rule engine to automate categorization of corporate cards and generate audit reports.
• Financial Analytics Platforms: Consume the reporting endpoints to build custom BI dashboards or integrate with tools like Grafana.
• Banking APIs: Expose Firefly’s data layer to third‑party fintech services via secure OAuth scopes.

Advantages for Developers

• Open Source & MIT License: No licensing fees, full control over data and code.
• High Performance: Symfony’s HTTP cache, Doctrine ORM with query caching, and Redis workers keep response times low even under heavy import loads.
• Flexibility: The modular architecture allows swapping out components (e.g., replacing PostgreSQL with CockroachDB) without rewriting business logic.
• Security: Built‑in OAuth2, CSRF protection, and strict input validation reduce the attack surface.

Firefly III thus offers a robust, extensible foundation for any developer looking to build or integrate sophisticated financial tooling while maintaining full ownership of the data and infrastructure.