Tomato Flutter Laravel Package

Product Decisions This Supports

• Whether to ship a mobile client at all — and how cheaply. Tomato Flutter supplies the Laravel-side scaffolding a Flutter app needs (API routes, token auth wiring, resource/DTO shapes, media endpoints, and Dart stubs to generate from). That reframes "build a mobile app" from a new-backend programme into a scoping exercise on the backend we already own. The decision it unlocks is not "Flutter vs. native," it is "can we afford a first mobile release this quarter."
• Build vs. buy on the API/glue layer. The reusable value here is the boring middle: consistent JSON envelopes, auth plumbing, pagination conventions, generated client code. Hand-writing and then maintaining that against a shifting schema is weeks of engineering plus permanent drift. Buying it (at the price of a dependency review) is the cheaper call for a first release.
• Roadmap sequencing inside an existing TomatoPHP estate. If the backend already runs TomatoPHP admin/CMS packages, mobile becomes a phase-2 deliverable on the same models, permissions, and auth — no parallel data layer, no second source of truth for user identity. This is the strongest argument for adoption and the one worth verifying first.
• API contract ownership — a product decision, not an engineering one. Once generation produces client-facing endpoints, those endpoints are the contract with the mobile app. Someone must own breaking changes, versioning, and deprecation windows. The package will happily regenerate a changed response shape with nobody noticing; deciding who signs off on that is our job, and it should be decided before the first store submission.
• Vendor risk as an explicit portfolio bet. Five stars, zero dependents, single-maintainer ecosystem, no release since November 2023, and a README that still reads "your package description will go here." That is not automatically disqualifying for an accelerant, but it must be a stated bet with a named exit path, not something inherited by default from an engineering spike.
• Release governance. v1.0.8's entire changelog is a GitHub compare link. For a code-generation package, a patch bump can still change emitted Dart. The implication for planning is concrete: every bump carries a regression check we own, so budget a small recurring cost rather than assuming "patch = free."

When to Consider This Package

Consider it when:

• We already run Laravel and have committed (or are strongly leaning) to Flutter. If the client technology is undecided, the value proposition collapses — this package does not help a React Native or web decision.
• We are inside the TomatoPHP ecosystem, or willing to adopt its conventions for models, auth, and resources.
• Speed to a first shippable mobile build outranks long-term API-surface stability.
• The mobile surface is genuinely small at first: login, list, show, create on one or two resources — not a ten-screen app with offline sync.
• One engineer can own the integration end to end, and we can live with a pinned 1.0.x dependency where even patch releases get a smoke test.
• We want the option value of a cheap spike before committing headcount to mobile.

Look elsewhere when:

• The backend is GraphQL, or we intend to serve several heterogeneous clients from an OpenAPI-first contract we control.
• We need a commercial SLA, security-review artifacts, or documented maintenance guarantees. This is community-maintained with a thin release history.
• We operate somewhere that documented change history and dependency provenance are audit requirements — the missing changelogs are disqualifying there, full stop.
• The mobile surface is large and long-lived. At that scale, versioned, contract-tested, hand-rolled endpoints usually win on total cost.
• We already have a mature API Resources layer and don't want a second serialization source of truth.
• Compatibility with our Laravel/PHP version is unverified. A composer require that resolves is not proof the generators run on our runtime — and nothing has shipped since late 2023.

Adoption preconditions I'd set: pin to 1.0.8; run a one-sprint spike against our auth and one real resource (including token refresh, logout, 401 handling, and a file upload); confirm maintainer responsiveness on issues; and record an exit-cost estimate — roughly how many endpoints we'd hand-write to walk away — so the buy-vs-build call stays reversible on paper, not just in someone's head.

How to Pitch It (Stakeholders)

For executives: We already have a Laravel backend and no mobile client. Tomato Flutter is an open-source package that supplies the backend plumbing a Flutter app needs — API endpoints, authentication, media handling, and generated client code — so a mobile app becomes an assembly job rather than a from-scratch backend project. Expected effect: a shorter path to a first release and no duplicated business logic between web and mobile. The cost is a community-maintained, single-maintainer dependency with minimal adoption, no documented changelog, and no release since late 2023. Recommendation: adopt it behind a pinned version and a defined exit path, as an accelerant for the first release — not as a permanent architectural commitment. Decision requested: approve a one-sprint spike and, contingent on it, a scoped first mobile release.

For engineering (what to validate before we commit):

• Integration against our models, not the demo: one resource end to end, including token refresh, logout, 401 handling, and file upload.
• Whether it duplicates or conflicts with our existing API Resources, Sanctum setup, and /api/* route prefix — and what CORS/stateful-domain config a device on the LAN actually needs.
• That generation runs as a reproducible build step (scripted, ideally CI-checked for drift), with generated Dart either committed or gitignored-but-consistent — never hand-edited.
• That auth/token logic lives in a Dart file we own, imported by generated code, so regeneration doesn't wipe it.
• That customizations go through published stubs in our own path, not vendor patches or in-place edits that vendor:publish --force will silently overwrite.
• Real effort estimate for the exit path, so the risk we're accepting has a number attached.