Nova Media Hub Laravel Package

Technical Evaluation

Architecture fit

• This is a Laravel Nova tool, not a standalone library. laravel/nova (commercial, per-site license) is a hard prerequisite. If we are not already on Nova, the evaluation ends here — we should not adopt Nova as a side effect of wanting a media library.
• It layers on spatie/laravel-medialibrary, so it does not introduce a wholly foreign persistence model; it adds an admin surface (browse, folders, search, upload, crop) plus a Nova field for attaching existing media to any resource. That is genuinely the expensive part to hand-roll — realistically one to three sprints of undifferentiated internal tooling.
• The architecturally significant consequence is a product stance, not a technical one: moving from per-record uploads to a single shared, reusable media pool. That buys editor reuse (one hero across ten pages) but creates referential questions we do not currently have — what happens when an asset still in use is deleted, and who owns the broken reference.
• Clean split is available and should be enforced: the package owns upload/browse/crop/selection; our application owns delivery — URL resolution, responsive markup, CDN base path, cache headers — behind a single accessor. That accessor is the exit door.

Integration feasibility

• Install path is short and well understood: composer require, publish provider config, migrate, storage:link if public disk, register the tool in NovaServiceProvider::tools(), add the field to a resource.
• Realistic effort: ~0.5–1 engineering day for a spike on a branch, 1–2 days to first production resource including storage config, authorization review, and docs.
• Gate check before any estimation: open the target tag's composer.json require block and confirm the Nova major, PHP floor, and Laravel range. If our Nova major is not listed, we are evaluating a fork, not a dependency.
• Verify whether the release tag ships compiled dist/ assets. If not, CI needs a deliberate build step inside vendor/, which is fragile and will not survive composer install.

Technical risk

Key questions for the team

1. Are we on Nova today, and which major? Is the license current?
2. Do we already have a media owner (Spatie directly, bespoke upload fields)? If yes, is this a full migration or a bounded new-resource scope?
3. Which disks per environment — local, S3, public vs private — and is a CDN in front?
4. Do we need per-tenant isolation? Nova's authorization is resource/model-level and will not scope folders per tenant for us.
5. What is our written abandonment threshold (e.g. no Nova-compatible release across two Nova majors) before we need it?
6. Do we have queue capacity and image extensions on every worker node?
7. Who is the named engineer able to read and patch the source if upstream stalls?

Integration Approach

Stack fit

• Fits cleanly if the stack is Laravel + Nova + (optionally) Spatie Medialibrary. Pairs naturally with Nova Page Manager from the same vendor — shared library plus field matches a page-builder workflow.
• Does not fit if: we are on Filament (use that ecosystem instead), we need enterprise DAM capability (rights, approvals, AI tagging, lifecycle governance), or we need transformations at CDN scale (Cloudinary/imgix/Cloudflare Images is the better architectural bet).

Migration path

• Decide the single owner of media records before the first commit. Two options only: migrate fully to this package, or confine it to a new resource type and document the boundary. Do not let two media models coexist indefinitely — orphan cleanup, deletion semantics, and backfill all become ambiguous.
• Keep blob paths out of our schema. Store the media ID, resolve path and URL at runtime; writing media/2024/06/foo.jpg into our columns welds us to the package's path convention and turns rollback into a file migration.
• Backfill is the one irreversible step. Ship it as an idempotent Artisan command (media:import-legacy), run in staging with record-count and URL-resolution assertions, then production. Keep legacy upload fields read-only for at least one release cycle as a fallback.

Compatibility

• Pin the version. Add "review nova-media-hub changelog" to the checklist for every Nova major bump.
• Check the release tag for pre-built assets before committing to a CI shape.
• Wrap package access behind a thin MediaService / trait (attachMedia(), heroUrl(), mediaInUse()). One hour of work converts a future fork-and-own decision from a refactor into a swap.
• Standardize conversion names early (thumb, card, hero, og) in config, referenced via constants or an enum. A per-feature free-for-all is expensive to unwind later.

Sequencing

1. Gate check — Nova license and major confirmed against the tag's composer.json. No code.
2. Spike (~0.5 day) — one hero image on a throwaway resource; upload → attach → persist → resolve URL on a public page; test local and S3. Output is a written go/no-go, not a demo.
3. Hardening — publish and review config/nova-media-hub.php (disk, path prefix, accepted types, max size, conversions), wrapper layer, conversion vocabulary, Storage::fake() feature test asserting URL resolution through our accessor.
4. First real resource — field added to a low-risk model, authorization review, config:clear/optimize:clear runbook step.
5. Backfill — staging then production, legacy fields read-only.
6. Docs + rollout — editors briefed, runbook published, KPI baseline captured.

Operational Impact

Maintenance

• MIT license, no support contract. Our cost is pinning discipline plus one engineer who can read and patch the source.
• Pre-agree and record an abandonment threshold now. With 46 stars and 0 dependents, single-maintainer risk is the dominant long-term cost, and the decision to fork should be a trigger, not a debate.
• Ongoing housekeeping: scheduled orphan-file cleanup command, and a delete guard for "is this media in use?" Never assume cascade behavior — verify it.

Support

• Editors get browse/search/crop self-service; that is the measurable win — asset-request ticket volume should fall after rollout. Baseline it before launch.
• Permission granularity is Nova's, not a DAM's. Internal trusted editors only. No approval workflows, rights management, or asset governance.
• Package documentation is thin relative to its surface area; the runbook should point engineers at src/, the published config, and the migrations as sources of truth.
• Business logic (ordering, alt text, captions, credits) belongs in our columns or a pivot we control — not in the field.

Scaling

• Image conversions run on our compute. Memory and CPU headroom on web and queue workers is a prerequisite, not a nice-to-have. Synchronous conversions on a 20MB hero will visibly stall the Nova UI; confirm sync vs queued behavior in the spike.
• Storage grows monotonically without orphan cleanup. Add the command on day one.
• This is not an image-delivery platform. Once variant count or traffic grows past what local conversions and a CDN cache can carry, the exit path is a managed image service — which is why the accessor wrapper matters.

Failure modes to pre-write into the runbook

• Uploads rejected (413 / silent failure) — almost always client_max_body_size, upload_max_filesize, post_max_size, or a Livewire limit, not the package. Check network tab, then PHP config on every environment including workers.
• Conversions silently missing — GD/ImageMagick absent on a queue worker; jobs fail long after upload looked successful.
• Deleting in-use media — broken references on live pages; mitigate with an in-use guard.
• Orphaned files — asset lingers after record deletion; mitigate with scheduled cleanup.
• Expired signed URLs — private disk + cached HTML; decide deliberately (public bucket + CDN, or signed route through the app).
• Stale config cache — "the disk setting isn't taking effect" is very often a cached config; config:clear / optimize:clear is the first diagnostic.
• Nova major upgrade breaks the tool — admin downtime risk on the maintainer's schedule; plan the pin review into upgrade work.
• Missing compiled assets — if dist/ is not in the tag, composer install in CI produces a broken Nova UI.

Ramp-up

• Engineers: ~1 day to productive (install, config, field wiring, accessor pattern) plus the spike.
• Editors: minimal — the browse/upload/crop UI is the point.
• TPM: the artifacts to hold at kickoff are the go/no-go memo from the spike, the pinned version and abandonment threshold, the conversion vocabulary, the ownership boundary decision, and the delete-safety rule. Those five documents are what keep this from becoming an unowned dependency eighteen months out.