Yaffa

Yaffa is a self-hosted personal finance web application built with PHP and Laravel, designed for privacy-conscious individuals who want complete control over their financial data without relying on cloud services or third parties. It focuses on long-term financial planning through detailed transaction tracking, multi-currency budgeting, and investment portfolio monitoring.

The application integrates with external services selectively: the free Frankfurter API provides automatic daily currency rate updates with no API key required, while AlphaVantage fetches investment prices and OpenAI or Gemini powers AI-driven transaction parsing from uploaded documents, emails, and Google Drive imports. Optional Tesseract OCR handles image-based receipt extraction.

Yaffa supports scheduled and recurring transactions that generate forecasted financial projections, transaction splitting across multiple categories for granular spending analysis, and account grouping for consolidated views across bank accounts and cash holdings. The project has an active release cadence, reaching v3.4.0 in June 2026, and maintains a public sandbox environment at sandbox.yaffa.cc for users to evaluate the app before self-hosting.

What You Get

• Multi-currency tracking with automatic rate updates - Maintain a default base currency for dashboards while recording transactions in any currency; daily exchange rates are fetched automatically via the free Frankfurter service with no API key or registration required.
• AI-powered document processing pipeline - Upload PDFs, images, text files, or plain-text emails and have OpenAI or Gemini extract payee, amount, date, and category details automatically; Tesseract OCR can be self-hosted for image-based receipts as an alternative to vision-capable AI models.
• Google Drive and email ingestion - Connect a Google Drive folder or a monitored mailbox so incoming documents and bank statement emails are automatically queued for AI processing without manual uploads.
• Investment portfolio tracking with live pricing - Record stock and fund purchases, then automatically pull current prices from AlphaVantage to calculate real-time gain and loss across your entire portfolio.
• Scheduled and recurring transactions with forecasting - Define income or expense recurrence rules using RRULE-compatible schedules; Yaffa projects future cashflow from these schedules and can auto-record them when they fall due.
• Transaction splitting and category learning - Split a single transaction across multiple spending categories; a built-in category learning service tracks payee-to-category patterns and pre-fills suggestions on future entries.

Common Use Cases

• Managing multi-currency household finances - A family with accounts in EUR, GBP, and USD records all transactions in their native currency while Yaffa converts everything to a single base currency for dashboard summaries and budget comparisons.
• Automating receipt capture with AI - A freelancer photographs paper receipts and forwards PDF invoices by email; Yaffa’s AI pipeline extracts the transaction details and queues them for a quick review before saving, cutting manual entry time dramatically.
• Tracking an investment portfolio without broker access - An investor records share purchases manually and lets AlphaVantage supply current prices, giving a consolidated gain/loss view across multiple brokerages in one private dashboard.
• Long-term savings forecasting - A user sets up monthly salary income and regular expense schedules so Yaffa can project a running account balance months into the future, helping plan large purchases or build an emergency fund.
• Auditing spending patterns after import - Someone migrating from a bank’s CSV export uses Yaffa’s import tooling to bulk-load historical transactions, then applies category splits and tags to analyze where money has been going over the past year.

Under The Hood

Architecture Yaffa is structured as a layered Laravel MVC application with a clear boundary between HTTP concerns and domain logic. Controllers are thin, delegating immediately to dedicated service classes — ProcessDocumentService, TransactionService, InvestmentService — each responsible for a single domain slice. An event-driven layer decouples AI ingestion from transaction persistence: events such as DocumentImported and AiDocumentProcessedEvent fire listeners that queue jobs asynchronously, ensuring the HTTP response path stays fast even when AI calls block. Policy classes and the ModelOwnedByUserTrait implement multi-tenancy at the model layer, guaranteeing that authorization and data isolation are enforced structurally rather than as ad-hoc if-checks scattered through controllers. Ziggy publishes named routes to the browser, and Laracasts/Utilities injects server-side translation data into the JavaScript runtime, eliminating redundant REST round-trips for UI state.

Tech Stack The backend runs PHP 8.4 on Laravel 12 with Sanctum for stateless API authentication, Telescope for request debugging, and Sentry for production error tracking. MySQL 8.0 is the primary database accessed through Eloquent ORM with comprehensive migrations. The frontend is built with Vue 3.5 compiled via Vite 8 and the Laravel Vite Plugin, using Bootstrap 5 for layout, DataTables for tabular views, and amCharts 4 with Chart.js for financial visualizations. AI orchestration goes through Prism PHP, which abstracts OpenAI and Gemini behind a unified structured-output interface. The Recurr library handles RRULE parsing for recurring transaction schedules, and beyondcode/laravel-mailbox enables direct email ingestion. The full development environment runs in Laravel Sail with MySQL, MailHog, and Selenium in Docker Compose.

Code Quality The test suite spans unit, feature, and browser layers with extensive coverage: feature tests validate API controller behavior, job logic, AI schema validation, and policy enforcement; unit tests cover services, helpers, and model traits; Laravel Dusk browser tests exercise critical UI workflows against a real Selenium instance. Laravel Pint enforces PSR-12 code style, Larastan provides static analysis at a high ruleset level, and PHPStan integration catches type errors before runtime. Custom exception classes — AiProviderFailureException, AiResponseParseException, InvalidAiResponseSchemaException — give precise, catchable failure modes throughout the AI pipeline rather than swallowing generic exceptions. The codebase is consistently typed with PHP 8.4 union types and readonly properties where applicable.

What Makes It Unique Yaffa’s defining differentiator is its multi-step, user-scoped AI document pipeline: each user can configure their own AI provider and key, the system builds context-aware prompts enriched with the user’s known payees and categories, and structured output is validated against a strict schema before any transaction is created. This means AI suggestions are personalized from the first use and improve continuously through the CategoryLearningService, which maintains per-user payee-to-category statistics. The Google Drive monitor job and mailbox listener create a near-zero-touch ingestion path where financial documents land in Yaffa automatically without any browser interaction. Combining self-hosted data sovereignty with optional AI capability at the user’s own API cost is an unusual position in the personal finance space.

Self-Hosting

Yaffa is released under the MIT License, which is one of the most permissive open-source licenses available. You can use it commercially, modify the source freely, redistribute it, and even incorporate it into proprietary products, as long as the original copyright notice is preserved. There are no copyleft requirements, so modifications do not need to be shared back. For a self-hosted personal finance application, this means there are no license checks, no feature gates, and no legal friction around deploying it for yourself or within a small organization.

Running Yaffa yourself requires a PHP 8.4+ web server environment with MySQL 8.0 or PostgreSQL, a queue worker process for background jobs, and optionally a mailbox listener process for email ingestion. The recommended setup uses Docker Compose with Laravel Sail, which bundles the application, database, MailHog for email testing, and Selenium for browser tests into a single compose file. For production, the project ships a Dockerfile and Caddyfile for a more hardened deployment, along with Deployer scripts for repeatable rollouts. You are responsible for database backups, SSL termination, queue monitoring, and applying upgrades — which, given the active release cadence (roughly one release per week in recent months), requires some operational discipline. The upgrade guide documents breaking changes between major versions.

There is no official managed or SaaS tier for Yaffa, so everything — uptime, scaling, data backups, and security patching — rests with you. A public sandbox at sandbox.yaffa.cc lets you evaluate the full application before committing to self-hosting, but that environment is wiped regularly and is not a substitute for your own instance. The trade-off is straightforward: in exchange for operational responsibility, you get a capable personal finance tool that stores nothing outside your own infrastructure and supports AI features using your own API keys without any subscription fees to the Yaffa project itself.