Filament Balance Header Laravel Package

Product Decisions This Supports

• Admin UX feature bets (internal tooling). This package lets us test a specific bet cheaply: should account/credit balance be visible in the persistent admin chrome, or is it fine buried in a settings or billing page? Shipping it to internal ops/support users for a sprint is a lower-cost experiment than designing a billing surface we may not need.
• Build vs. buy — leaning "buy," but only as a shortcut. The capability is small enough to reimplement in-house in roughly a day using Filament render hooks. Adopting is justified by time-to-value, not by strategic dependency; treat it as a replaceable commodity, not platform infrastructure.
• Roadmap sequencing for metered/credit products. For products that meter usage (credits, tokens, prepaid wallets, seats), a header-level balance readout is a cheap complement to a real billing/usage page — a convenience surface, never a substitute. It should not displace a billing dashboard on the roadmap, and it should not be sold internally as "billing."
• Use cases that justify it: internal ops panels where support agents need balance context while working a ticket; credits/fintech-flavored SaaS admin views; early-stage products where a full billing admin UI is not yet funded.
• Use cases that do not justify it: anything customer-facing; requirements involving audit trails, reconciliation, PCI/regulatory scoping, or multi-entity / multi-currency balance logic. This package renders a value; it does not model one.
• What it explicitly does not decide for us: the correctness, provenance, or formatting policy of the balance number. That remains our product and engineering responsibility.

When to Consider This Package

Adopt when:

• We are already running Filament panels — outside that ecosystem the package has no value.
• The requirement is genuinely a display concern: fetch a balance, show it in the topbar, done.
• We want a sub-day win and are comfortable with a single-maintainer, v1.x dependency whose blast radius is small and whose removal cost is near zero.
• We can pin an exact version and review diffs before any upgrade.

Look elsewhere (or build in-house) when:

• We are not on Filament, or we are on a Filament major version the package does not explicitly support — verify compatibility before committing.
• The requirement is billing logic (ledger, reconciliation, dunning, currency handling) rather than presentation. This package will not carry that weight.
• We need accessibility, localization, or theming guarantees beyond what a small community component documents.
• Our org requires active maintenance signals — multiple maintainers, a substantive changelog, a security policy, or an SLA. Note the maintenance signal here is weak: the latest release, v1.0.3 (2024-01-19), carries a bare compare link with no described changes, and the repo has negligible community traction. That is not disqualifying at this size, but it means we cannot rely on upstream responsiveness.
• We are in a regulated or financial-display context where every number shown must be traceable to an audited source.

How to Pitch It (Stakeholders)

For executives (one paragraph): We are evaluating a small, free, MIT-licensed add-on for our Laravel admin panel that displays an account balance in the panel header, so support and operations staff see it without navigating away from the task at hand. Cost is effectively zero and risk is low: it is a thin display component we can remove or rebuild in about a day. The tradeoff is that it is an early-version (1.0.x), single-maintainer package with a sparse changelog — appropriate for an internal convenience feature, not a foundation for billing logic. Recommendation: pilot it in the internal admin only, pin the version, keep it off any customer-facing or regulated surface, and record it as a replaceable, non-strategic dependency.

For engineering (bullets):

• Latest release is v1.0.3, a patch-level bump from v1.0.2. The release note is only a diff link — no features, fixes, or deprecations described. Review the actual diff before bumping; do not assume patch semantics on a single-maintainer project.
• No breaking changes are signaled, but v1.x with a sparse changelog means we should pin an exact version in composer.json and gate upgrades behind a diff review.
• Scope is presentation only: a Filament header render hook plus a data source for the balance value. We own the correctness of the number — the package renders whatever we hand it, so source, caching, and formatting policy are ours to define.
• Exit cost is trivial: worst case we reimplement the equivalent header widget in-house. Document it as a replaceable dependency in our architecture notes so it does not quietly become load-bearing.
• Before rollout beyond a pilot, confirm Filament major-version compatibility and check the package's test coverage and issue activity — with zero stars and a single maintainer, upstream support is a courtesy, not a commitment.