Nova Workflow Laravel Package

Technical Evaluation

Architecture fit. cammac/nova-workflow is a Laravel Nova resource tool, not a standalone workflow engine. It is designed to attach workflow state and transition controls to Nova resources — i.e., workflow logic lives at the admin-UI layer and is coupled to Nova's internal tool/resource conventions. That is an acceptable fit for back-office approval flows (editorial review, order status, ticket triage) where the primary actor is an internal operator working in Nova. It is a poor fit if workflow is core domain logic that must also be driven from APIs, queues, webhooks, or customer-facing surfaces, because the engine and the presentation layer are not clearly separable and Nova is closed-source.

Integration feasibility. Feasible only inside an existing Laravel + Nova estate, and only after version alignment is confirmed. Nova is a paid, closed-source dependency with its own major-version cadence; the package must be checked against our pinned PHP, Laravel, and Nova majors, and against any package that already owns model state. A one-day sandbox spike in a throwaway Nova app is enough to establish whether tool registration, migrations, and transition endpoints behave as documented.

Technical risk. Elevated for the following reasons:

• Validation gap. 35 stars and 0 dependents means essentially no downstream production signal. There is no evidence of a user base that would surface regressions before we do.
• Bus factor of one. Single-maintainer, low-activity package; abandonware risk is the default assumption, not the tail case.
• Closed-source coupling. Nova's internals change across majors; a tool that hooks resource menus and detail views is exactly the kind of integration that breaks silently on upgrade.
• Unknown enforcement boundary. The critical question is whether transitions are authorized and validated server-side (policies, form requests, transactions) or merely hidden in the UI. UI-only gating is a security defect, not a feature gap.
• MIT license is permissive enough to fork and vendor, which materially reduces the downside — but only if we are prepared to own the fork.

Key questions to resolve before committing:

1. What are the exact composer.json constraints for PHP, Laravel, and Nova, and when was the last commit/release?
2. Is state persisted in a dedicated table, a JSON column, or a column on the model? Is there an immutable transition history/audit log?
3. Are transitions wrapped in DB transactions with row-level locking, or is concurrent-transition safety unaddressed?
4. Is transition authorization delegated to Laravel policies/gates, or is it presentation-only?
5. Does the package ship tests, and do they run in CI?
6. Can the state machine be invoked outside Nova (service class, facade), or is it only reachable through the tool?
7. Is there a documented upgrade path across Nova majors, and a security disclosure channel?

Integration Approach

Stack fit. Adopt only if we are already committed to Laravel + Nova and the workflow scope is genuinely administrative. It does not fit API-first, headless, or multi-tenant-SaaS-with-external-actors architectures. Scope test: if the requirement is a linear set of 3–5 states with one approver, the package likely covers it; if we need parallel branches, guard conditions, SLA timers, delegation, or escalation, we will outgrow it within a quarter and should not start there.

Migration path (recommended, in preference order):

1. Sandbox spike — install in a disposable Nova app, model one real workflow end to end, and record what breaks. Output: a go/no-go memo with the version matrix.
2. Fork and vendor — if we proceed, fork under our namespace, pin to a Composer VCS/path repository, add CI (lint + PHPUnit), and add the missing audit/authorization pieces ourselves. Treat upstream as a reference implementation, not a dependency.
3. Thin-adapter refactor — if the spike shows state logic is entangled with the Nova tool, extract the state machine into an application service and reduce the package to UI only. This is the highest-value change and the one that de-risks Nova upgrades.
4. Fallback — use a mature engine (symfony/workflow or spatie/laravel-model-states) and build a small custom Nova field/tool for transition controls. For most teams this is the lower-total-risk option: a maintained engine plus ~1–2 weeks of Nova UI work buys version independence and testability.

Compatibility. Verify PHP minor, Laravel major, and Nova major jointly — these three constrain each other. Check published migration and config filenames for table/config-key collisions with our schema. Critically, ensure only one source of truth for state: if a model already has a status column driven by observers or another package, this package will create state drift, and that must be resolved before, not after, rollout.

Sequencing.

• Week 1: version/feature audit, sandbox spike, alternative comparison (fork vs. engine+UI) with rough effort estimates.
• Week 2: decision gate — adopt-fork, adopt-as-is, or build-on-engine. Default to fork if adopting.
• Week 3: hardening if adopting — CI, authorization, transaction/locking, audit log.
• Week 4: pilot on one low-risk internal resource with a documented rollback (feature flag + state table snapshot).

Operational Impact

Maintenance. Assume in-house ownership from day one. Budget roughly 2–4 engineer-days per quarter for dependency hygiene and Nova upgrade tracking, plus a spike whenever Nova ships a major. If we do not fork, budget reactive firefighting instead — that is the worse trade.

Support. Community-only: GitHub issues, no SLA, no published security policy, no maintainer redundancy. Escalation path is "we fix it." This must be stated explicitly to whoever owns the workflow feature, because a workflow outage blocks operational throughput, not just a nice-to-have screen.

Scaling. Two concerns:

• Query behavior. Workflow state rendered on Nova index/list views is a classic N+1 source if state is loaded per-row. Confirm eager-loading and ensure supporting indexes on the state column and any polymorphic/foreign keys.
• Concurrency. Approval flows have real concurrent actors. Without transactional transitions and row locks, two approvers can apply conflicting transitions. Verify, and add locking in the fork if absent.

Failure modes to design against:

• Nova major upgrade breaks tool registration or resource rendering — mitigate with a pinned lockfile and a staging upgrade rehearsal.
• Transition succeeds in the UI but fails to persist (or vice versa) — mitigate with server-side validation and an explicit error surface.
• Unauthorized transition via direct request to the tool endpoint — mitigate with policy checks on the server, never UI-only hiding.
• State drift between model column and workflow table after manual DB edits — mitigate with a single source of truth and a reconciliation command.
• Abandonware: upstream goes quiet mid-incident — mitigated entirely by the fork.

Ramp-up. One to two days for a Laravel developer already fluent in Nova; roughly a week for a new hire who must also learn Nova's paid-license setup, tool registration, and resource conventions. Because Nova familiarity is the real prerequisite and Nova knowledge is not transferable to other stacks, document the workflow's state model and transition rules independently of the package — that artifact survives any later engine swap.