Yaffa Laravel Package

Product Decisions This Supports

• Build vs. buy for budgeting/finance surfaces. v4 promotes budgets to a standalone Budget entity with a combined Schedules and Budgets report, budget-vs-actual drill-down, inflation-adjusted forecasting, and dashboard widgets. v4.1.0 extends the reporting surface with dedicated payee and category show pages, i.e. entity-level drill-down rather than only aggregate reports. That is a modeled domain you would otherwise have to design and build — a concrete input to "do we build our own budget module or adopt this."
• Self-host vs. SaaS for internal finance tooling. The container generates and persists its own APP_KEY on first boot, and HTTPS ships as a Caddy Compose profile with a configurable APP_PORT. "One command to a working, TLS-terminated instance" changes the hosting-cost side of the buy-vs-run comparison against per-seat subscriptions.
• Recurrence-heavy roadmap bets. Recurrence is a single RFC 5545 rrule column, with ordinal weekday patterns ("first Wednesday of every month"), "N days before month end," and "last business day of month." If your roadmap includes subscriptions, payroll-like schedules, or reminders, this is a standards-based engine rather than a bespoke frequency/interval model.
• Money correctness as a release gate. Exact decimal arithmetic via ext-bcmath removes rounding drift in split totals, investment values, and monthly summaries, and over-precise input is rejected instead of silently rounded. Use this to decide whether the numbers are trustworthy enough to show users, auditors, or downstream systems.
• Ecosystem / integration commitment. Scoped personal API tokens (read/write/settings) plus optional TOTP 2FA with recovery codes make it defensible to expose an API to customers or internal automation. v4.1.0 continues the security hygiene story (axios upgraded for a disclosed vulnerability, package.json vulnerability fixes) without changing the API contract — which is the pattern you want from a dependency you expose.
• Data governance for AI features. Per-user, opt-in retention that deletes old finalized AI documents and reminds on unfinalized ones remains the gate for whether AI document ingestion passes privacy review. Two v4.1.0 data points refine that decision: duplicate detection for AI documents was fixed (ingestion is now less likely to double-count a re-uploaded receipt), and retired OpenAI models (gpt-4o, gpt-4o-mini) were deprecated in the codebase — the AI surface tracks a third-party model lifecycle, so treat model IDs as an operational dependency with a refresh cadence, not a fixed capability.
• Operational observability is now yours to own. v4.1.0 removed sentry/sentry-laravel. If your run-cost model assumed built-in error tracking, add APM/log aggregation to the self-host column — this is a real (if small) shift in the run-vs-buy arithmetic.
• Upgrade scheduling as a planning constraint. The 3.x → 4.x data migrations cannot be rolled back with migrate:rollback. That forces a freeze window, a rehearsed migration, and a backup policy onto the roadmap — plan it as a project, not a dependency bump. v4.1.0 is a routine minor with no announced breaking changes, so it is a low-friction follow-on once you are on 4.x; the v4 cutover remains the expensive step.
• Explicitly not supported: multi-tenant SaaS billing, double-entry general ledger or payroll compliance, and anything requiring a vendor SLA. Don't scope those onto this.

Confidence note: this assessment is derived from the v4.0.0 and v4.1.0 release notes only — there is no usage data, and no hands-on evaluation of v4.1.0 behavior, behind it.

When to Consider This Package

Consider it when:

• You are building or operating a Laravel application and need expense, budget, account, and investment tracking as a self-hosted capability — or you are evaluating self-hosted finance tooling for a small organization or team.
• You are on, or can move to, Laravel 13 and can install ext-bcmath; your team is comfortable operating PHP + Vue and is willing to run its own error tracking, now that the bundled Sentry integration is gone.
• Recurrence fidelity matters (ordinal weekdays, month-end and business-day rules) and you want an RFC 5545 model rather than a custom schema.
• You want a credible API surface: scoped tokens, 2FA, and predictable JSON contracts. v4.1.0 adds no API-breaking changes, so an app already integrated against 4.0 can take this release with normal regression testing.
• Payee- and category-level analysis is on your roadmap — v4.1.0's show pages give you a starting point for per-merchant and per-category spend views.
• You can absorb a major-version migration with irreversible data changes — upgrade to the latest 3.x first, run php artisan app:check:budget-migration, back up the database, and follow UPGRADE.md.

Look elsewhere when:

• You need a Composer-installable library to require into an existing app. This is a full application you fork and operate, not a drop-in package.
• You need vendor support, an SLA, SOC 2 / ISO attestations, or accounting-grade ledgers.
• You need multi-tenancy or per-tenant billing out of the box.
• You have API consumers pinned to v3 semantics. Money and quantity fields in /api/v1/* are now decimal strings, not JSON numbers, and GET /api/v1/transactions/scheduled-items no longer accepts type=budget|budget_only|both|any. Both are silent-breakage risks for typed clients.
• You depend on built-in error/exception telemetry. Sentry support was removed in 4.1.0; budget for a replacement or accept log-only observability.
• You need to pin a specific OpenAI model for AI document extraction and cannot absorb model-deprecation churn.
• You cannot tolerate downtime, irreversible migrations, or single-maintainer concentration risk.
• Your auth flow depends on reCAPTCHA — it is removed, and RECAPTCHA_* variables are no longer read.

How to Pitch It (Stakeholders)

For executives. This is a mature, self-hosted personal-finance and budgeting application on Laravel, not a paid subscription product. The commercial case is cost avoidance and data ownership: no per-seat fees, your financial data stays on infrastructure you control, and v4 made deployment genuinely cheap — docker compose up -d yields a working instance with a generated APP_KEY, and TLS is a Compose profile flag. The security posture also crossed a credibility threshold at 4.0: scoped API tokens, optional TOTP two-factor with recovery codes, and an XSS fix. v4.1.0 is a maintenance-and-polish release: it keeps the dependency stack patched (including a security upgrade to axios), adds payee and category drill-down pages, and tightens the AI document pipeline, with no breaking changes announced. Two caveats for the risk slide. First, the maintainer removed Sentry error tracking, so monitoring is now your responsibility. Second, the AI features are tied to third-party model IDs, and retired OpenAI models had to be deprecated in this release — capability does not decay, but the plumbing under it does. The core counterargument is unchanged: adopting this means forking and operating an application, not adding a dependency. Recommendation: pilot on a non-critical instance, and treat the 4.x upgrade as a small, well-defined project rather than a background chore.

For engineering. Stack is Laravel 13 and PHPUnit 13, with exact decimal arithmetic via ext-bcmath and RFC 5545 rrule recurrence replacing the old frequency/interval/count/end_date columns. Frontend is Vue with a cached formatter layer plus virtual scrolling on account history. From the 4.0 breaking set, the items to plan around remain: the transactions.budget flag is gone and budget-only rows are converted into Budget records and deleted from transactions; API money fields are decimal strings; the scheduled-items type filter is removed; reCAPTCHA is dropped; deleting an AI document no longer cascades to its transaction. Laravel 13 also changes default CACHE_PREFIX, REDIS_PREFIX, and SESSION_COOKIE — pin them in .env or you will silently invalidate existing cache and sessions. Sequence the cutover: latest 3.x → app:check:budget-migration → backup → 4.x, with no rollback path.

What 4.1.0 asks of you. No announced breaking changes, so this is a normal minor upgrade, but verify four things on a staging copy first: (1) sentry/sentry-laravel was removed — drop any Sentry DSN config and confirm your replacement error path; (2) the preferred import profile moved from account_entities to accounts, so check import defaults and anything reading that column directly; (3) Select2 was replaced with Tom Select, so re-test import/settings forms and any UI customizations layered on Select2; (4) AI extraction now depends on a currently supported OpenAI model — review configured model IDs, since gpt-4o and gpt-4o-mini are deprecated. Also in this release: composer/npm updates including axios 1.18.1 → 1.20.0, a Vue component refactor for data flow, Pest 5 browser tests added, and fixes to AI duplicate detection, related-AI-document layout, the monthly breakdown report layout, and payee/category preference validation. The test investment is a mild positive signal against single-maintainer risk; the Sentry removal is a mild negative for operability.