Yaffa Laravel Package

Technical Evaluation

YAFFA is a Laravel monolith (self-hosted personal-finance app), not a drop-in library. "Integration" means deploying the app and consuming its /api/v1 surface plus the UI — so the evaluation is about adopting a fast-moving, single-tenant application as a dependency. v4.1.0 lands three weeks after the 4.0.0 major and is a stabilisation release: no /api/v1 contract changes, no new migration of the 4.0 severity class, but it does carry three items that matter to us — an observability removal, a dependency-driven AI capability change, and a schema move for import profiles.

Architecture fit

• Standard Laravel conventions (artisan commands, .env config, queue/scheduler, Blade + Vue front end) — familiar to any Laravel team, low conceptual overhead.
• Single-tenant-per-instance design; no multi-tenancy, no SSO, no webhook/event egress. Any enterprise integration is polling the REST API or reading the database. Unchanged in 4.1.
• v4.0's RFC 5545 rrule column for schedules and budgets remains the right architectural direction: recurrence logic converges on one model and third-party RRULE tooling becomes applicable. 4.1 does not disturb it.
• Scoped API tokens + TOTP 2FA (4.0) is still the single most integration-relevant feature; 4.1 adds nothing to the machine-to-machine story, so our token-based integration design stands.
• New in 4.1: preferred import profile moves from account_entities to accounts. This is a data-model correction (the preference belongs to the account, not the entity) but it means another schema/data migration and a possible change in how that field surfaces in exports or UI state. Treat any read of the old location as at-risk.

Integration feasibility

• API contract changes from 4.0 remain the gating item and are unchanged in 4.1: money/quantity fields are decimal strings in /api/v1/* responses, and GET /api/v1/transactions/scheduled-items no longer accepts type=budget|budget_only|both|any. Silent-breaking for typed clients. 4.1 buys us nothing here — the client work is identical.
• Report endpoints remain unaffected; the 4.1 fixes (monthly breakdown layout, related-AI-document layout) are presentation-layer, confirming the blast radius stays bounded to transaction/account/investment payloads.
• ext-bcmath + Laravel 13 remain prerequisites from 4.0. 4.1's composer update and npm install do not relax them; they add churn on top.
• 4.1 removes sentry/sentry-laravel. If our deployment model assumed the app ships its own error reporting, that assumption is now void and we must supply APM/error capture at the platform layer (container logs → our aggregator, or an SDK we inject).
• 4.1 deprecates retired OpenAI models (gpt-4o, gpt-4o-mini). AI document extraction is therefore coupled to a configurable, still-supported model. This converts an "internal feature" into a config-managed external dependency with its own lifecycle and cost profile.
• UI dependency swap (Select2 → Tom Select) is a DOM/behaviour change. Any Playwright/Selenium script, bookmarklet, or reverse-proxy-injected customisation targeting Select2 markup will break. New Pest 5 browser tests are a genuine regression-safety improvement but do not cover our automation.

Technical risk

• Still highest, still unmitigated: the 4.0 irreversible data migration. Budget-only transactions are converted to Budget rows and deleted from transactions; migrate:rollback cannot restore them. 4.1 does not change this. Anyone upgrading 3.x → 4.1 in one hop inherits the full risk in a single window.
• Pivot-table deduplication and key/index changes remain destructive, in-migration, and non-reversible. 4.1 adds a second (smaller, additive-looking) migration for the import-profile move; verify it backfills before dropping the old column rather than discarding existing preferences.
• Laravel 13's CACHE_PREFIX, REDIS_PREFIX, and SESSION_COOKIE defaults still log every user out and can orphan cache entries if unpinned. composer update in 4.1 makes it more likely, not less, that a loose constraint drifts onto a newer framework patch.
• ext-bcmath + exact decimal arithmetic still changes rounding behaviour by design — totals may differ by cents. Finance stakeholders notice before engineers do.
• New: observability regression. Dropping Sentry means a class of production failures becomes invisible unless we already have log aggregation and alerting. For a finance app, silent background-job failures (imports, AI extraction, recurring-schedule generation) are the worst failure mode.
• New: AI feature degradation risk. A model deprecation that lands as a chore is easy to skip; if any pipeline or prompt config still names gpt-4o/gpt-4o-mini, extraction fails or silently falls back. Treat as an unverified assumption until tested.
• Improved: axios bumped 1.18.1 → 1.20.0 for security, package.json vulnerability reduction, plus the 4.0 XSS fix, TOTP + recovery codes, scoped tokens, and removal of unmaintained roach-php. Supply-chain posture is materially better than 3.x.
• Still absent: any reCAPTCHA replacement. Registration abuse mitigation remains ours to build.

Key questions

1. Do we run YAFFA as an end-user app, or only as an API-backed data store? That determines whether the Tom Select swap and show-page changes matter at all.
2. Which of our consumers parse money/quantity fields as numbers, and can we enumerate them before cutover?
3. Does anything downstream depend on budget-flagged rows in transactions, or on the type= filter for scheduled items? (Unchanged from 4.0 — still open.)
4. What is our real transaction/pivot volume, and can the 4.0 migrations complete inside a maintenance window?
5. Who owns error tracking now that Sentry is removed — do we have log aggregation and alerting on queue/job failures before we take 4.1?
6. Which OpenAI model is configured in our .env, and is it overridable without a code change? What is the fallback when extraction fails?
7. Does anything reference account_entities.preferred_import_profile — exports, BI queries, saved reports, or our own scripts — and does the 4.1 migration preserve values?
8. Do we have UI automation or injected JS targeting Select2 markup?
9. Is registration exposed publicly, and what now replaces reCAPTCHA (rate limiting, invite-only, WAF)?
10. Do we run more than one instance against shared Redis/memcached?
11. Is TOTP sufficient for our access-control posture, or does the absence of SSO/SAML disqualify this for the finance-adjacent use case?
12. What is the rollback story when migrations are one-way — restore-from-backup only, and what is the RTO?

Integration Approach

Stack fit

• Excellent fit for a Laravel shop: PHP 8.x runtime, MySQL/Postgres, Redis, queue worker, scheduler. No exotic services. 4.1 keeps this true while removing Sentry — one fewer PHP dependency, one more platform responsibility.
• Poor fit if the surrounding estate is SSO-first or expects event streaming; YAFFA remains an island reached over REST.
• Prefer API-token access over UI automation for any system-to-system flow; treat the UI as the human surface only. This is now more important, not less, given the Select2 → Tom Select swap.
• Add a platform-side observability layer (structured log shipping + alerting on failed jobs) since the app no longer ships with one. This is a prerequisite, not a follow-up.

Migration path

1. If still on 3.x, land on latest 3.x first, then go straight to 4.1.x — do not stage through 4.0.x. 4.1 is the stabilised target and avoids re-testing the UI swap twice.
2. If already on 4.0.x, 4.1 is a routine minor: image rebuild + composer update + npm install, plus the import-profile migration. Still rehearse on staging — the migration is small but not necessarily reversible.
3. Run php artisan app:check:budget-migration in production read-only to size the 4.0 budget-transaction conversion.
4. Take a verified, restorable database backup and confirm a test restore. This is the only rollback.
5. Rehearse the full chain on a production-shaped staging copy, including pivot dedup, index changes, and the accounts column move; measure wall-clock time.
6. Cut over API consumers in the same change window as the server upgrade, or version-gate behind a proxy.

Compatibility

• Pin CACHE_PREFIX, REDIS_PREFIX, and SESSION_COOKIE in .env before upgrading to preserve sessions and cache namespace.
• Rebuild the PHP image with ext-bcmath; pin framework constraints tightly so 4.1's composer update cannot drift us onto an untested Laravel 13 patch.
• Replace the removed Sentry integration with our own error/log pipeline and verify a synthetic failed job raises an alert before go-live.
• Re-point AI document extraction to a currently supported model via config; dry-run against a sample document set and compare extraction quality and token cost to the retired gpt-4o baseline.
• Re-apply Caddy customisations as the https Compose profile; add APP_PORT handling to deployment scripts.
• Audit importers/scripts for over-precise money input — v4 rejects rather than silently rounds.
• Re-baseline any UI automation against Tom Select; drop Select2-specific selectors.

Sequencing

1. Runtime/image changes (bcmath, Laravel 13, PHP baseline, no Sentry) → 2. .env prefix pinning + OpenAI model re-point → 3. staging rehearsal of migrations (budget conversion, pivot dedup, import-profile move) → 4. API client updates to string decimals and the removed type filter → 5. observability cutover and alert test → 6. production migration window → 7. verify reports, budget-vs-actual, reconciliation, and AI extraction → 8. roll out scoped API tokens and TOTP, retire shared credentials → 9. backfill the reCAPTCHA replacement and AI-document retention policy as follow-ups.

Operational Impact

Maintenance

• Cadence is confirmed aggressive: a major at 4.0.0, a dependency-and-schema release at 4.1.0 three weeks later. Treat upgrades as a standing project, not a patch routine; the 4.1 composer update and npm install commits mean minor releases also carry dependency churn we must validate.
• Laravel 13 + PHPUnit 13 keep the project on a supported framework — a long-term win, but it pins us to Laravel's release treadmill.
• Two new recurring duties: (a) tracking OpenAI model lifecycle ourselves, since deprecations arrive as chores and silently degrade extraction; (b) owning error tracking we previously inherited.
• Removing unmaintained roach-php and the Sentry SDK both reduce third-party surface; the Sentry removal trades supply-chain risk for operational blindness, which is a net loss unless we backfill.
• Added Pest 5 browser tests are a real maintenance asset — they buy regression confidence for the UI churn we are now seeing each release.

Support

• New security surface to support: TOTP enrolment, recovery-code distribution and reset, API token lifecycle. Expect first-month helpdesk load.
• reCAPTCHA removal still shifts abuse mitigation to us — rate limiting, invite-only registration, or edge WAF before go-live.
• New support theme: an AI extraction endpoint that fails without a clear user-facing message, because the configured model was retired upstream. Needs an error state users can act on, and a documented model-swap runbook.
• Behaviour change to support (carried from 4.0): deleting an AI document no longer deletes its transaction. Document it, update runbooks.
• Possible data-support issue (4.1): if the import-profile migration does not fully backfill, users' preferred profiles reset and imports behave differently. Check pre-migration.
• Irreversible 4.0 migrations mean support cannot "just roll back" — first-line response is restore-from-backup, which raises the severity of any post-upgrade data complaint.

Scaling

• Perf work stays aligned with growth: pivot keys, dropped redundant indexes, cached number/date formatters, virtual scrolling.
• bcmath exact decimal arithmetic is slower per operation than native floats; benchmark the heaviest report rather than assuming a net win from the formatter caching.
• Migration index rebuilds remain the real scaling hazard on multi-million-row tables.
• Single-tenant design caps horizontal scale at one instance per user/team; shared Redis requires prefix pinning.
• Sentry removal changes scale behaviour: without centralised error capture, per-instance log volume becomes the only signal — size log retention and storage accordingly, and ensure aggregation scales with instance count.

Failure modes

• Silent total mismatch post-upgrade: intentional rounding change means previously reconciled totals differ. Detect via parallel-run reconciliation, not error logs.
• Truncated history: budget-flagged transactions deleted in 4.0; saved reports, exports, or BI over transactions return different numbers with no error.
• Broken API consumers: decimal strings coerced to 0 or truncated, or scheduled-items requests failing on the removed type param. Loud in typed clients, silent in loose ones.
• Undetected production failure now that Sentry is gone — a failing import or schedule job produces no alert. This is the defining new risk of 4.1.
• Silent AI extraction failure after upstream model retirement: features appear enabled but return empty or erroring results.
• Reset import preferences from the account_entities → accounts move if backfill is incomplete.
• Broken UI automation or injected JS after Select2 → Tom Select.
• Mass session loss / cache collisions from unpinned Laravel 13 prefixes.
• Failed/partial migration with no rollback — pivot dedup or budget conversion error mid-run leaves a mixed state.
• Reverse proxy outage after the Caddy profile change.
• Spam/abuse surge on public registration.

Ramp-up

• Engineering: low-to-moderate — 3–5 days for a Laravel-fluent engineer to cover the upgrade guide, .env pinning, image rebuild, and staging rehearsal; add 2–3 days per API consumer for the bcmath/decimal-string changes; add 1 day for the 4.1 items (observability backfill, OpenAI model re-point, import-profile verification).
• Operations: 1–2 days — Compose profile/APP_PORT changes, APP_KEY auto-generation behaviour, backup/restore drill, plus 1 day for the new logging/alerting pipeline replacing Sentry.
• Product/support: 1–1.5 days — TOTP and token workflows, AI-document retention settings, changed delete semantics, and the new AI-extraction failure state.
• Finance/reporting stakeholders: 0.5 day — agreeing that post-upgrade totals may shift by cents and that this is correct.
• Net effect versus 4.0: roughly +2 days of platform and configuration work, offset by landing one stabilised release instead of two upgrade cycles.