Nova Health Laravel Package

Technical Evaluation

Architecture fit. Nova Health is a presentation layer, not a health-check engine. It registers into Nova's tool registry, renders a dashboard inside the admin panel, and surfaces the results of whatever probes it ships or wraps. That shape is favorable for a TPM: it is purely additive, it sits entirely off the application request path, it introduces no migrations and no data model, and removal is composer remove plus deleting one line from NovaServiceProvider::tools(). The binding constraint is that it has no standalone value. It is a widget inside Laravel Nova, a commercial first-party product with a per-site license. If Nova is already licensed and daily-driven by ops or support, this is nearly free. If Nova is not load-bearing, the economics invert — you would be buying an admin panel to host a health card.

Integration feasibility. Installation is two steps (Composer require, register the tool) plus publishing a config file. There are no queues, no scheduled jobs, no schema changes, and no external service dependencies introduced by the package itself. A competent Laravel engineer can have it rendering in staging inside a day, including the authorization gate. The real work is not installation — it is the four reconnaissance questions below, all of which are answerable by reading src/ for fifteen minutes.

Technical risk. Ranked by severity:

1. Authorization defaults. Community Nova tools frequently default canSee() to "any authenticated Nova user." Health output leaks DSN shapes, disk paths, queue depths, and service reachability. Treat a permissive default as an information-disclosure finding until proven otherwise in code — not in the README.
2. Silent-pass on timeout. If a probe throws or exceeds its timeout and the card renders green, you have converted "we don't know" into "we checked and it's fine." That is worse than no dashboard. Verify the failure rendering by deliberately breaking a check in staging.
3. Single-node blindness. Health is a per-process property. Behind a load balancer the panel truthfully reports whichever node served the request. During a partial outage this produces a green dashboard and red customers.
4. Supply chain. 13 stars, zero dependents, single maintainer, last release February 2025. This is an unhardened artifact. Acceptable for internal-only, gated tooling; unacceptable as a dependency of anything customer-facing.
5. Nova upgrade coupling. A compiled Vue bundle built against an older Nova/Vue can break silently on a Nova major bump — Nova itself stays up, so nothing alerts. This is a checklist item, not a blocker.

Key questions. These must be answered before the pilot is scoped, not after:

• What Laravel, PHP, and Nova version ranges are declared in composer.json? Is the Nova constraint a range or a pin? A pin means fork-and-forget — decide that now.
• Are the checks self-contained, or does the package wrap spatie/laravel-health / hit the /up route? This determines whether we now have two sources of truth.
• What does canSee() / authorize() return by default, and where is it declared?
• Do checks run synchronously on page load, or are results cached? What are the HTTP timeouts on network-bound checks?
• Who is the named internal owner if the maintainer disappears? MIT makes forking trivial, but only if one engineer has read the Nova tool internals while it is still a thought experiment.

Integration Approach

Stack fit. Laravel + Nova only, and effectively Nova 4/5 era. Fit is binary: if the org standardizes on Nova and has an ops or support role that already lives in that panel, the tool slots in cleanly. If the team is migrating off Nova, or non-Nova users need health visibility, stop here — a standalone integration is the better investment.

Migration path. There is no migration. No tables, no backfill, no data to move, no cutover window. The adoption path is: install in a non-critical Nova environment → gate it → break a check on purpose → confirm red renders correctly and timeouts fail closed → then promote to production behind the gate. Reversal is equally cheap: composer remove, delete the Nova::tools entry, clean up published config and compiled assets. That reversibility — not the feature set — is the primary argument for trialing rather than building.

Compatibility. Treat the package's composer.json as the only compatibility contract that exists. Pin the exact version in our composer.json and treat bumps as deliberate events tied to Nova major upgrades, not as routine composer update drift. Specifically: run composer show stepanenko3/nova-health --all and read the declared framework/Nova/PHP ranges before the pilot is approved; if the bundle looks stale relative to our Nova version, budget for rebuilding from source with Nova's frontend dev tooling, which is a real cost and a real skill dependency. Where possible, do not reimplement checks in the Nova tool — point it at the same underlying checks as our existing /up endpoint or spatie/laravel-health so the dashboard and the alerting path never disagree.

Sequencing. Recommended order, each step gated on the prior:

1. Reconnaissance (½ day): read composer.json and src/; answer the five key questions in writing.
2. Authorization gate (same PR as install): define a viewHealth gate restricted to an ops role; override canSee() to use it. Never ship the install and the gate separately.
3. Staging install and red-state verification (1 day): break a check deliberately (stop the queue worker, point a check at a dead Redis port), screenshot the failure state, confirm timeout maps to fail rather than pass.
4. Check hygiene pass: cache anything network-bound (Cache::remember with ~60s TTL) so N ops viewers × refresh rate does not become N probes per minute; scope custom checks to services whose failure actually changes how we triage.
5. Pilot (one cycle): production deploy, gated, with a written success metric agreed before launch.
6. Decision point: expand, fork, or drop. Do not let the pilot drift into a default.

Explicitly out of scope for every step: wiring this into deploy gates or CI. Post-deploy smoke checks belong in curl -f https://app.test/up in the pipeline. Nova Health is for humans triaging; it should never be able to block a rollback.

Operational Impact

Maintenance. Low in absolute terms, but concentrated on one person. The package has a bus factor of one and a February 2025 last release. Our maintenance burden is three things: a pinned version in composer.json, a "does the health page render" line item on the Nova upgrade checklist, and a written fork procedure naming one engineer comfortable with Nova tool internals. The upgrade checklist item is the one that will actually bite if skipped — a broken panel stays silent because Nova stays up.

Support. No vendor support channel; the issue tracker is low-traffic and unproven across Nova majors. Internal support burden is modest but front-loaded: whoever owns it must be able to explain that a blank panel likely means a Vue/asset problem (blank with HTTP 200) or an uncaught check exception (blank with 500, look in storage/logs/laravel.log), and that neither necessarily means the application is down. Debugging path: php artisan route:list | grep -i health, hit the endpoint with an authenticated session, watch the network tab. Document that once and support can self-serve.

Scaling. Two distinct limits. First, per-request cost: if checks run synchronously on page load, cost scales with viewers × refresh rate, not with traffic. Five ops people refreshing during an incident multiply outbound probes fivefold. The 60-second cache wrapper is not an optimization, it is a correctness requirement for network-bound checks. Second, fleet coverage: the panel does not scale across nodes. Behind a load balancer it samples exactly one process. This does not degrade gracefully — it degrades misleadingly, reporting green on the node that answered while other nodes fail. Keep the external prober as the source of truth and treat this as one sample.

Failure modes. Ranked by how badly they mislead:

• Fail-open timeouts — probe errors render as pass. Highest severity; verify in staging before trusting the panel at all.
• Partial-fleet green — panel reports the serving node while the fleet is degraded. Mitigation is procedural: never treat this as fleet status.
• Alert fatigue via red-everything — a non-critical custom check (a marketing API, say) failing paints the panel red. Operators learn to ignore red, which destroys the tool's only value. Scope custom checks ruthlessly.
• Silent breakage on Nova upgrade — panel renders broken but Nova stays up, so nothing alerts.
• Information disclosure — permissive default authorization exposing DSN shapes and paths to any Nova user.

Ramp-up. Near-zero for consumers. Ops and support need one sentence of framing: the upside is a single screen in the tool they already use for customer workflows instead of asking an engineer to run commands; the caveats are that it samples one server, it does not alert, and if the screen goes blank that means Nova is broken, not necessarily the app. Engineering ramp-up is roughly one day plus the recon half-day, plus a real but unquantified cost if the compiled assets ever need rebuilding from source. No training program, no runbook beyond the fork procedure and the blank-panel triage note.

TPM recommendation. Approve as a time-boxed, gated pilot for in-panel operational visibility — one cycle, one non-critical Nova environment, named success metric (reduced triage time, fewer ad hoc php artisan checks, or faster post-deploy confidence) agreed up front. Record the risk acceptance explicitly: zero dependents and a single maintainer, tolerated only because the surface is internal, gated, and reversible. Do not standardize. Expand only if the pilot hits its metric and a named owner accepts upgrade-time maintenance; otherwise invoke the fork-or-drop decision rather than letting the pilot become a de facto default.