Filament Wallet Laravel Package

Product Decisions This Supports

• Build vs. buy for an internal balance console. If your roadmap needs an ops-facing "view and adjust a customer's balance" screen — not a full payments or ledger system — this package collapses what would be several days of Filament resource and action work into an install command plus a plugin registration. That reframes the decision from "do we build a wallet?" to "do we build an admin UI over Bavix?" — and the answer here is usually that a thin UI is cheap either way, so the package's value is speed, not capability.
• Feature sequencing. It unlocks the visible half of a balance feature (wallet list, transaction list, charge action) quickly, which is useful for demoing a workflow to stakeholders or unblocking an ops team while the harder half — authorization, approval, audit, reconciliation — is still being designed. Use it to de-risk the shape of the feature before committing engineering to the parts that actually carry risk.
• Scope negotiation with stakeholders. When someone asks for "a wallet in the admin panel," this package is a concrete, low-cost way to ship that request and an honest basis for saying what it does not include. It makes the gap between "operator can credit an account" and "money moves safely" demonstrable rather than theoretical.
• Adjacent product bets. For products built on Filament accounts (subscriptions, credits, prepaid balances, loyalty points, usage allowances), this is a plausible reference implementation. Worth a spike to see whether Bavix's model fits your domain before designing your own ledger.
• Explicitly not supported: consumer-facing balance UI, API-driven balance movement, multi-currency display logic, refunds and holds workflows, or anything requiring dual approval. If a roadmap item needs those, this package is a starting point, not a solution — plan the additional work before you promise the feature.
• Roadmap risk register item. Two live maintenance branches (v5 for Filament v5/Laravel 12–13, v4 for Filament v4) and a single maintainer mean every Filament upgrade carries a small but real dependency question. Worth tracking as a named line item, not a background assumption.

When to Consider This Package

Adopt it when:

• Your stack is Laravel 12/13 + Filament v5 + Livewire 3 on the admin panel, and you're comfortable with the TomatoPHP/Filament plugin ecosystem.
• The need is an internal ops console — support or finance staff looking up a balance and issuing a manual adjustment — not a customer-facing wallet.
• You've already chosen, or are willing to choose, bavix/laravel-wallet as the ledger layer. This package is a UI over Bavix; adopting it means adopting Bavix too.
• The team is Filament-fluent and can absorb a spike to verify precision and transaction semantics.
• You're pre-product-market-fit or building an internal tool where speed matters more than vendor support, and you can accept community-only maintenance.

Look elsewhere — or build the thin UI yourself — when:

• Balances touch revenue, reconciliation, or regulated money movement. The package documents no authorization model, no approval workflow, no reason codes, and no idempotency guard on its charge action. That's not a defect to patch later; it's a missing product requirement you must own.
• Precision policy matters and HasWalletFloat doesn't satisfy it. A prior release explicitly moved integer to float — confirm how minor units are stored before committing to currency. If it's true float, treat it as a blocker and plan a migration to integer minor units.
• Your panel is on Filament v3 (unsupported), or you need balances exposed via API or headless surfaces.
• You require a vendor contract, SLA, or meaningful production track record. 38 stars and zero dependents means you'd be an early adopter discovering edge cases yourself.
• You need bulk operations, backfills, or high-volume credits — bypass the UI and call the ledger directly via queued jobs.

Decision gate: run a 3–5 day spike first. If it reveals gaps in authorization, audit, or precision, adopt the package's UI patterns as reference and implement the action yourself against Bavix directly. You keep the design work and drop the dependency risk for a marginal amount of extra effort.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed admin-panel component that lets our operations team view account balances and issue manual credits without custom development. It sits on top of an established ledger library, so our exposure is an internal admin screen — not our money, not our customer-facing product. Cost is measured in days, not sprints. The trade-off is that it's community-maintained with no support contract and a single maintainer, so we'd own the code by policy. My recommendation is a short spike to validate it against our precision and audit requirements, then a deliberate decision to adopt-as-is, or to build the same screen ourselves using it as a blueprint.

To engineering: Four-step integration — composer require, filament-wallet:install, register FilamentWalletPlugin::make(), and add Wallet + HasWalletFloat to the target model. All ledger semantics stay in Bavix; this package is action and resource glue with no schema of its own. Expect the integration to be trivial and the hardening to be the work: policy checks on the charge action, an amount ceiling, a mandatory reason field, an audit record with actor and before/after balance, and a duplicate-submission guard. Pin an exact version, register the plugin only in the ops panel, and treat the double-submitted-charge and balance-drift failure modes as ours to design against.

What to ask before approval:

1. Is this on the critical path for revenue or reconciliation, or purely an ops convenience?
2. Which exact version and branch do we pin, and who owns upgrades?
3. Does the product need multi-currency, refunds, holds, or negative balances — and does the ledger support them?
4. What is our precision policy, and does HasWalletFloat meet it?
5. What authorization and approval requirements apply to a manual charge?
6. Do we accept a single-maintainer upstream, and have we budgeted for a fork?

Framing to avoid: presenting this as "we get wallets for free." It delivers a console, not a wallet product. The honest pitch is speed on the visible surface plus a decision framework for the parts that carry real risk.