Filament Wallet Laravel Package

Technical Evaluation

Architecture fit This package is a thin Filament admin surface over bavix/laravel-wallet, not a wallet engine. It contributes four things: a plugin registration hook (FilamentWalletPlugin::make()), a WalletAction table action for crediting a balance, wallet/transaction list resources, and an install command that publishes Bavix migrations. All ledger semantics — balance arithmetic, transaction records, locking, atomicity — belong to Bavix. That boundary is the single most important fact for a TPM: the blast radius of this package failing or being abandoned is your admin UI, not your money. It is replaceable with a few hundred lines of Filament code against the same underlying library.

Fit is therefore narrow and legible. Good for Laravel 12/13 + Filament v5 panels that need an internal ops view of balances and a manual charge button. Poor for API-only products, non-Filament panels, or any flow where end users move their own money rather than admins.

Integration feasibility Low technical effort, moderate governance effort. Four steps: composer require tomatophp/filament-wallet, run filament-wallet:install, register the plugin in the panel provider, and add the Wallet interface plus HasWalletFloat trait to the target model. A Filament-competent developer measures this in hours, not weeks. The optional filament-account bridge adds a model publish step and ->useAccounts() on the plugin.

The real work is not integration, it is hardening. Authorization, dual control, idempotency, reason capture, and reconciliation are all absent from the README. Assume you build them.

Technical risk

Key questions

1. Is this on the critical path for revenue or reconciliation, or purely an ops convenience console? This single answer sets the entire risk posture.
2. Which exact version and branch do we pin, and who owns the upgrade decision?
3. What is our precision policy, and does HasWalletFloat satisfy it for every currency we touch?
4. What authorization, approval, and audit requirements apply to a manual credit in our organization?
5. Do we need multi-currency, refunds, holds, or negative balances — and does Bavix expose them through this UI at all?
6. Do we accept a single-maintainer upstream with no SLA, and have we budgeted for a fork?
7. Does the ops team need bulk operations, or is one-charge-at-a-time sufficient?

Integration Approach

Stack fit Good when the panel already runs Laravel 12/13 + Filament v5 + Livewire 3 and the team already consumes TomatoPHP packages (this plugin integrates with filament-plugins and filament-account). Neutral when the team is Filament-fluent but new to Bavix — the learning curve is Bavix's transaction model, not this package. Poor when the panel is on Filament v3, when balances must be exposed via API, or when the organization requires vendor support contracts.

Migration path

1. Spike (3–5 days). Stand up a throwaway panel with one model and a seeded dataset. Verify rounding behavior, what charge actually writes to the Bavix transaction table, and how balances render after concurrent operations.
2. Build-vs-adopt gate. If the spike surfaces gaps in precision, authorization, or audit, adopt the package as a reference implementation and write the action yourself directly against Bavix. You keep the UI patterns and drop the dependency risk for roughly a week of work.
3. If adopting: pin an exact version (no caret range), vendor or fork into an internal namespace, and register the plugin only in the ops panel — not in every panel in the application.
4. Wrap WalletAction in your own controls: policy checks, per-operator amount ceilings, mandatory reason field, structured audit record capturing actor and before/after balance, and a duplicate-submission guard on the form.
5. Reconcile. Ship a scheduled job comparing Bavix balances against the source of truth (payment provider, invoicing system) with alerting on drift, before anyone charges a real account.

Compatibility

Sequencing The spike and the build-vs-adopt decision must land before any sprint commitment — that decision gates everything downstream. Then: (1) install and model traits in a staging panel, (2) authorization and audit hardening, (3) reconciliation job and alerting, (4) production rollout to a small ops cohort, (5) broader access once audit data looks clean for a full cycle. Do not sequence payment-gateway integration ahead of reconciliation; you would have no way to detect drift.

Operational Impact

Maintenance Low code volume, two ongoing obligations: tracking the v5 and v4 branches separately, and tracking Bavix majors (v11 → v12 already happened, and v12 changed the transaction model with the TransactionType enum). Budget 2–5 engineer-days per year for version bumps plus a manual regression pass over charge and transaction flows. Forking adds rebase cost, but the codebase is thin enough that this stays small. CI badges cover style and tests; there is no evidence of concurrency or money-path testing, so every upgrade needs a human in the loop.

Support Community-only — GitHub issues, no SLA, no commercial backing. The single-maintainer pattern is the dominant support risk, and mitigation is contractual rather than technical: name an internal owner for the package, document a fallback plan to replace the UI layer, and set expectations with stakeholders to "we fix it ourselves." Realistically, first response on an upstream issue should be assumed to be days or never.

Scaling The package is an admin console, so its ceiling is operator throughput, not request volume. lazy() on the charge action means a round trip per interaction — fine for tens of charges a day, painful for bulk work. Any bulk credit, backfill, or data migration should bypass the UI entirely and call Bavix through queued jobs with idempotency keys. Watch the wallet and transaction list resources against large tables: confirm indexes on the underlying Bavix tables (wallet_id, created_at, uuid) before volumes grow, and add default date filters to the resources so ops does not scan full history.

Failure modes

• Double charge. A double-submitted modal or retried operator action credits twice. Bavix has transaction UUID support, but the package does not document using it for idempotency — enforce it yourself.
• Balance drift. No built-in reconciliation against the payment provider. Drift is silent until a customer complains.
• Rounding loss. Float-based balances accumulate error across many small transactions; HasWalletFloat may expose decimals without controlling storage precision.
• Unauthorized exposure. Registering the plugin panel-wide exposes wallet and transaction lists beyond the ops audience. Scope it to one panel and gate the resources.
• Silent install failure. filament-wallet:install must successfully publish and run Bavix migrations; a partially applied install leaves the UI functional-looking but the schema incomplete (a namespace bug in the install command was fixed only in v5.0.0).
• Cross-branch upgrade breakage. Moving a panel from Filament v4 to v5 means switching branches, not bumping a version — plan it as a migration, not an upgrade.
• Optional-integration surprise. If filament-account is present but the model traits are not attached, ->useAccounts() produces a broken experience rather than a clean error.
• Negative balances. Nothing in the UI prevents an over-debit or an over-credit; enforce business limits in your wrapper, not in the operator's judgment.

Ramp-up Engineer: 1–2 days to read the package, install it, and wire the action; 3–5 days for the spike including precision verification. Ops users: under an hour of training on the charge flow, plus a one-page runbook covering reason codes, approval thresholds, and what to do when a charge looks wrong. Support/finance: budget half a day to understand the reconciliation report and the drift alert. Total organizational ramp-up is under two engineer-weeks for the cautious path — small enough that the build-vs-adopt decision should be based on control requirements, not on effort.