Nova Metrics Laravel Package

Technical Evaluation

Architecture fit

• Targets a real, well-defined gap rather than inventing a new layer. Nova applies resource filters to index/detail requests, but metric cards (Value, Trend, Partition, Progress) resolve their own query inside calculate(NovaRequest $request). Filter state is not threaded through automatically, so a dashboard card and the table directly beneath it can legitimately disagree — the "numbers don't match" complaint is a product defect, not a user misunderstanding.
• The shape suits a TPM-led pilot: additive, small, and composable via a trait or base metric class rather than a Nova fork. Blast radius is one dashboard, and the exit ramp is credible.
• Best fit is Eloquent-backed metrics with simple, deterministic predicates users already trust on index pages — owner, region, stage, team, status, environment, tenant, date range.
• Poor fit: warehouse- or third-party-API-backed metrics, raw SQL not expressed as an Eloquent builder, and cached/precomputed aggregates where "apply a filter" has no clean semantic.
• Structural caveat to state plainly to stakeholders: Nova is closed-source and commercial. Correctness depends on non-public behaviour, so compatibility must be proven empirically against the installed version, not inferred from public source.

Integration feasibility

• Composer-installable, MIT, negligible transitive weight. Install is a half-day; the compatibility determination is the actual work.
• Audit before composer require: declared Nova major, Laravel, and PHP constraints in composer.json; whether a CI matrix proves the declared Nova version; whether a pre-built JS asset ships (a PHP-only package is materially safer than an unversioned front-end bundle you inherit at upgrade time); and total LOC — under ~500 lines makes fork-and-own a 1–2 day job and changes the entire risk calculus.
• Determine the core mechanism: does it re-evaluate Filter::apply($request, $query) server-side per request, or accept opaque filter state from the client? Server-side is auditable; client-supplied state is a tampering surface and a potential cross-tenant leak.

Technical risk

• Highest severity — authorization parity. A metric that silently ignores an owner or tenant filter is a cross-tenant data exposure, not a cosmetic bug. canSee() and user-dependent options() behave differently in a metric request context than on an index request and must be verified with two users of different scopes returning different numbers.
• Cache leakage. Any caching must key on both the resolved filter payload and the authenticated user ID. A tenant- or owner-scoped metric sharing a cache entry across users is the single worst failure mode available here.
• Silent filter divergence. Metric and resource index must resolve from the same filter classes, not hand-copied where clauses. Divergence reproduces exactly the bug the package was installed to fix, with extra steps.
• State does not reliably travel. Nova persists index filter selection in browser storage per resource; a dashboard card is a different render context. Verify what actually arrives in the metric request, including whether defaults apply on first load.
• Date/timezone drift. DateFilter ranges computed against a different request context can be off by a day at boundaries.
• Maturity. 27 stars, zero dependents, single-maintainer signal. You are the QA department. Upstream breakage will surface during your Nova upgrade with no committed fix timeline.

Key questions to answer before committing

1. Which Nova major are we on, and does the package's CI prove it? Nova 4 → 5 moved to Vue 3 and Nova.booting; card packages historically break across that line.
2. Does the diff stay under ~500 LOC — i.e. is forking cheaper than adopting?
3. Is filter application server-side and auditable?
4. Do options() queries now run once per card on every dashboard load, and what does that cost?
5. What is the measured query cost of a Trend card with an expensive whereHas filter (one query per bucket)?

Integration Approach

Stack fit

• Laravel + Nova shop only. This value dies with the platform — do not consider it if a Nova exit is on the roadmap, and do not let it become a dependency of anything outside the admin panel.
• Internal admin surface only. Not customer-facing, not financial reporting without additional controls.

Migration path

• No data migration and no schema change; this is a read-path change. Rollback is a deploy revert, so a failed pilot costs one deploy rather than a rollback procedure. Say this explicitly when seeking approval — it is the cheapest possible risk profile for a feature bet.
• Do not migrate existing custom dashboard queries in the same release. Land the package behind one card, prove parity, then retire hand-rolled equivalents card by card.

Compatibility

• Pin an exact version — composer require square1/nova-metrics:x.y.z. No caret ranges on a zero-dependent package.
• Record the Nova version validated against in the PR description, not merely the lockfile. Lockfiles drift; PR descriptions are the institutional memory.
• Wrap immediately in an internal App\Nova\Metrics\FilterAwareMetric base class. Every concrete metric extends that. Swapping to a fork or first-party code then touches one file, not every dashboard.

Sequencing

1. Day 0 audit (half a day). Read composer.json, confirm pre-built assets, count LOC, identify the filter-application mechanism. Cancel here if the mechanism is client-supplied state.
2. Pin and install against a named, validated Nova version.
3. Single pilot card. One Value card, one resource, one simple filter (status or owner) that users already apply on that index page.
4. Build the parity harness before adding a second card. Assert filtered metric value == filtered index count == hand-written query with identical constraints, across no-filter, single-filter, and multi-filter cases. If it fails, stop — a metric that renders but silently ignores a filter is worse than a broken dashboard because it looks trustworthy.
5. Label filtered cards in the UI. A number that changes with filter state must say so, or someone screenshots it in a business review and argues about which number is right.
6. Instrument and measure the signals defined up front, then decide on expansion.

Define success before rollout. Installation is not success. Pick the signals now: fewer "numbers don't match" tickets, actual usage of filtered cards, reduced time-to-answer in ops/sales reviews, whether stakeholders stop exporting to spreadsheets.

Operational Impact

Maintenance

• Assign an internal owner on day one. Mitigate the single-maintainer risk by assuming the fork is the realistic end state if the pilot succeeds, not a contingency.
• Add "verify metric cards" to the permanent Nova upgrade checklist. This is non-negotiable — the package is coupled to closed-source internals, so breakage arrives with your upgrade, not before it.
• Single-source filter definitions from TicketResource::filters() so metric and index cannot drift apart over time.

Support

• MIT, community-only, no SLA, no security artifacts, no guaranteed version tracking. Acceptable for internal admin tooling; disqualifying for anything customer-facing or audited.
• Team capability requirement: someone must be comfortable reading package source and Nova internals. If that person does not exist, the fork-and-own exit ramp is not real and the adoption decision is unsound.

Scaling

• Trend metrics issue one query per bucket. That is ~30 queries for a cheap column predicate — fine. With a whereHas filter it becomes 30 correlated subqueries and a slow dashboard. If a filter is expensive, use a Value card or precompute.
• options() runs on every metric request, once per card. Heavy options() queries now execute on every dashboard load. Measure this before adding cards beyond the pilot.
• Caching, if introduced, must key on filter payload + user ID. Treat any cache addition here as a security change requiring review, not a performance tweak.

Failure modes and mitigations

Ramp-up

• Engineering: half a day to install and audit, 1–2 days for the pilot card plus parity harness, 1–2 days to fork if the LOC count is low. Budget the fork explicitly rather than treating it as free insurance.
• Debugging guidance for the team: log the final SQL, not the result. DB::listen() or ->dd() on the builder during a spike; diff the metric's query with bindings against the index query with bindings. That divergence explains most wrong numbers faster than reading package source.
• Stakeholder ramp-up: this is a pilot of a dependency with a fork-and-own exit ramp, not a platform commitment. Scope it to one admin area, measure whether filtered metrics are actually used, and revisit make-vs-buy only if it spreads. Do not extend the promise to analytics parity, cross-resource reporting, or warehouse-grade BI — those are a different product and Nova metrics plus filters is the wrong layer.