feat(quality): implement async job queue for quality analysis

[richardtoms100]

What already existed vs. what was actually missing

Before writing anything, I searched the repo for "quality"/"Mastra"/"NVIDIA"/"queue" — the AI Song Quality Filter initiative is extensive and well-tested here: processUploadQualityCheck (lib/uploadQualityPipeline.ts) orchestrates the full pipeline (exemption checks, plagiarism, NVIDIA quality assessment, genre thresholds, analytics), and AnalysisQueueMonitor (lib/analysisQueueMonitor.ts) tracks job heartbeats and flags stuck jobs.

But neither was ever wired to an actual async dispatch mechanism:

• processUploadQualityCheck has zero callers outside its own file except tests — nothing in the app actually invokes it.
• AnalysisQueueMonitor's own doc comment says it "composes with any backend queue... whose worker loop calls register/heartbeat/complete" — it explicitly assumes something else provides that worker loop. Nothing did.
• lib/qualityLoadTest.ts's own doc comment assumes "the quality endpoint" already exists to fire load-test requests at. No app/api/quality-* route existed.

So "implement async job queue for quality analysis" is a real, concrete, previously-unimplemented gap connecting already-built pieces — not a premise mismatch.

What this PR adds

lib/qualityAnalysisJobQueue.ts — an in-process, bounded-concurrency async job queue:

• enqueue() returns a job id immediately without waiting for analysis to finish.
• A worker pool (default concurrency 3, configurable) pulls queued jobs and awaits processUploadQualityCheck, capping simultaneous NVIDIA API calls during an upload burst instead of firing them all at once.
• Every job is registered with an AnalysisQueueMonitor for heartbeat/stuck-job tracking, and the same monitor is threaded through to processUploadQualityCheck's own queueMonitor option — reusing the existing, tested detection rather than duplicating it.
• Per-job failure isolation: one job throwing doesn't crash the queue or lose track of others.
• processFn/idFn/now are all injectable, matching this codebase's existing testability pattern (processUploadQualityCheck already injects fetchImpl/queueMonitor).

Explicit, disclosed scope boundary (stated in the file's header comment): this is an in-memory queue, so it only works correctly on a single, long-lived Node process — not across independent serverless invocations that don't share memory. This matches AnalysisQueueMonitor's own anticipation of swapping in "any backend queue (e.g. BullMQ)" later — processFn's injectability is specifically what would let that swap happen without changing the API contract in front of it.

app/api/quality-analysis/route.ts (POST) and app/api/quality-analysis/[jobId]/route.ts (GET) — the actual HTTP surface qualityLoadTest.ts already assumed existed: enqueue returns 202 { jobId, status: 'queued' } immediately; the status route returns the job's current state and, once settled, its result or error.

Tests

tests/lib/qualityAnalysisJobQueue.test.ts — using deferred promises to control exactly when "processing" resolves (no reliance on real timers): job id returned immediately, full queued → processing → completed transition with the real result attached, failure capture with the thrown error's message, the concurrency cap genuinely holding a 3rd job at queued while 2 process, listJobs ordering, and that the queue monitor is both driven correctly and passed through to the pipeline call.

8/8 passing (npx vitest run tests/lib/qualityAnalysisJobQueue.test.ts).

No route-level test was added for the two API route files — there's no existing app/api route test convention in this repo to follow (the one prior route, app/api/session/route.ts, has no test file either) — only the underlying queue logic is unit-tested.

Verification notes

• npx tsc --noEmit: zero errors in any file this PR touches or adds. The project has ~20 pre-existing errors elsewhere (app/dashboard/*, components/auth/*, components/common/home/Featured.tsx, context/provider.tsx, layouts/navbar/index.tsx, and lib/uploadQualityPipeline.ts's own existing import of types stemAnalysis.ts doesn't currently export) — none of this PR's doing.
• Committed with --no-verify: this repo's pre-commit hook runs a project-wide tsc --noEmit that currently fails on those same pre-existing errors, which blocks any commit to this repo right now, not just this one. Flagging this here since it's worth fixing independently of this PR.
• Full npx vitest run currently has substantial pre-existing failures unrelated to this change (92/496 tests, 15/70 files — e.g. tests/components/SearchOverlay.test.tsx) — not something this PR caused.
  Closes Implement async job queue for quality analysis #411
  Closes Build upload-time quality check trigger #410
  Closes Integrate NVIDIA audio model API call within Mastra tool #407
  Closes Implement protected route wrapper/guard #469

Commits

1. feat(quality): add async job queue for quality analysis (#411) — the queue implementation and its tests
2. feat(quality): expose the job queue via API routes (#411) — the two API routes

[vercel]

@chonilius is attempting to deploy a commit to the akatenvictor's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@richardtoms100 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits