Tomato Invoices Module Laravel Package

Product Decisions This Supports

• Build vs. buy for internal invoicing. If the product already runs Laravel + Filament (especially the TomatoPHP module stack), this is a credible shortcut for invoice CRUD — numbering, customers, line items, taxes, statuses, PDF output — instead of an internal build. MIT license keeps legal friction low.
• Roadmap sequencing and MVP scoping. It lets us ship an admin-facing billing surface (finance ops, agency client invoicing, order→invoice flows) in an early release without committing engineering to a bespoke invoicing engine. The real "billing platform" investment can be deferred until demand is proven.
• Scope boundary definition. This is invoicing records and admin UI, not a payments or revenue platform. It complements — does not replace — Stripe/Paddle/Cashier-style checkout, subscriptions, dunning, and tax filing. That boundary needs to be stated to sales and finance before any customer-facing promise is made.
• Ecosystem standardization. Adopting it consolidates on TomatoPHP conventions (shared auth, panels, UX, model naming), reducing per-module design and maintenance cost across the admin suite. That's a portfolio-level argument, not a single-feature one.
• Make-vs-contribute (strategic dependency call). A young, single-maintainer module forces an explicit choice: (a) depend and upstream fixes, (b) fork, or (c) wrap it behind an internal abstraction so it can be swapped. PM should own this decision and its exit plan rather than letting it default to "we installed it, so we depend on it."
• Evidence quality as an input, not a footnote. 0 stars, 0 dependents, a v1.0.0 whose release notes are changelog-link-only, and a last release of March 2024 mean there is no public proof of production use. Treat it as a time-boxed accelerator, not a strategic bet.
• Differentiation input if invoicing is customer-facing. The module's gaps — multi-currency, localization (Arabic/English), compliance-grade numbering and immutability — become the build list and the basis for pricing/packaging decisions.

When to Consider This Package

Consider it when:

• The stack is Laravel + Filament, ideally already using TomatoPHP modules, so the UI and conventions fit rather than fight.
• The need is admin/finance-side invoice management — drafts, proformas, internal records, order-to-invoice admin flows — not consumer checkout, proration, dunning, or tax filing.
• Timeline pressure is real: billing screens are needed in weeks, and the consuming workflow is internal enough to tolerate rough edges during a pilot.
• The team can own a v1.0.0, single-maintainer OSS dependency — pin the exact version, fork the migrations, and absorb a takeover if the maintainer goes quiet.
• Requirements for multi-currency, multi-tenancy, and localization are modest or can be verified and extended cheaply.
• We accept that PDF generation and invoice numbering will need hardening (queued rendering, DB-level sequencing) regardless of what ships in the box.

Look elsewhere when:

• We need a proven billing platform — Stripe Invoicing, Laravel Cashier, Invoice Ninja, or Crater offer far deeper billing, tax, and payment coverage.
• We have compliance obligations — e-invoicing/ZATCA, VAT audit trails, GoBD/legal archival, guaranteed PDF fidelity — that require vendor SLAs, audit evidence, and retention guarantees.
• We are not on Filament/TomatoPHP; the integration benefit largely evaporates and only the models/migrations are reusable — in which case take the schema and skip the package.
• The flow is revenue-critical from day one, or finance/audit stakeholders require gapless numbering, immutability of issued invoices, and legal retention out of the box.
• Release hygiene matters to us: the tag shipped with changelog-only notes, so feature set, migration path, test coverage, and security posture must be validated by engineering before adoption, not assumed from the README.

Decision gate before committing: a short spike with explicit exit criteria (a persisted invoice with line items and a produced PDF), a schema diff, a license/dependency-tree check, and a maintainer-health review. If those fail, the fallback is the schema-as-spec plus a buy decision.

How to Pitch It (Stakeholders)

To executives: This is a low-cost accelerator for internal invoicing screens if we're already on Laravel + Filament — it can remove weeks of admin UI work from an MVP, at zero license cost. It is not a billing platform and does not replace payment processing, subscriptions, or tax compliance. The project is young: first stable release, essentially one maintainer, no adoption signal, and thin public documentation. The recommendation is therefore a time-boxed pilot in a non-revenue-critical flow (drafts and proformas), with a pre-agreed option to fork or replace. Upside: speed and ecosystem fit. Downside: dependency risk and compliance work we will own either way.

To engineering: A TomatoPHP module providing invoice models/migrations and Filament resources for the admin panel. Before adoption, review the schema, tax/currency handling, the PDF dependency and whether rendering is queued, the migration and upgrade path, test coverage, license, and security-reporting channel. Pin the version, fork the published migrations at install time so upstream schema edits can't silently alter our financial tables, wrap the module behind an internal service boundary (e.g. BillingService) so application code never calls the package models directly, add our own authorization policies, and solve invoice numbering at the database level. Budget a small spike to confirm it fits our tenancy and localization needs.

To finance/accounting: This is a records-and-admin-UI layer, not a compliant ledger. It will not encode our jurisdictional numbering, tax, retention, or audit-trail rules — we will build and harden those. Finance should review the model of record before any real customer invoicing, and sign off that the pilot stays on drafts/proformas until those requirements are demonstrably met.

The ask: Approve a short spike plus a hardening budget, or defer to a buy decision — framed as "a cheap, reversible experiment with a defined exit," not as our billing strategy.