Feature: Pluggable Music Provider Layer with Track Normalization

Summary

Introduce a pluggable music provider layer that normalizes track metadata and lets Moodify support Deezer today while preparing for additional music providers or fallback search sources later.

Problem / Opportunity

Moodify currently relies on Deezer's public Search API and opens tracks in Deezer's web player. The code and documentation note a previous migration away from Spotify search constraints. That makes provider dependence a meaningful product and architecture risk: recommendation quality, previews, artwork, deep links, availability, and metadata shape all depend on a single external source.

A provider abstraction would make the recommender more resilient and easier to extend without forcing UI components to understand every provider-specific response format.

Proposed Feature

Create a normalized provider contract for music search and recommendation results:

• Define a canonical Track shape used by backend, Modal inference, web, and mobile.
• Implement Deezer as the first provider behind the contract.
• Add provider metadata such as provider name, provider track id, preview availability, external URL, artwork URL, duration, and confidence/fallback source.
• Support provider capability flags so the UI can handle missing previews, missing artwork, or provider-specific deep links cleanly.
• Add configuration for provider priority and fallback behavior.
• Update tests and fixtures to use normalized track data rather than raw provider response assumptions.

Scope

• Shared track normalization schema and documentation.
• Deezer provider adapter in the recommendation/inference layer.
• Backend/OpenAPI response schema updates if needed.
• Web/mobile UI updates for provider labels and capability-aware actions.
• Test fixtures for normalized tracks, missing previews, missing artwork, and fallback source metadata.

Acceptance Criteria

• Recommendation responses use a documented canonical Track shape across web and mobile.
• Deezer search results are transformed through a dedicated provider adapter rather than spread across UI or service code.
• Track cards can render provider-aware states for preview available, preview unavailable, artwork unavailable, and external-link unavailable.
• Provider identity and provider track id are preserved for history, feedback, and future deduplication.
• Provider priority/fallback behavior is configurable without changing UI code.
• Existing Deezer functionality continues to work after normalization.
• Tests cover Deezer normalization, missing fields, provider capability flags, and backward-compatible client rendering.

Non-Goals

• Immediately adding paid Spotify or Apple Music integrations.
• Implementing full music playback inside Moodify.
• Migrating historical user data in this first issue unless required for compatibility.
• Building a recommendation algorithm rewrite.

Dependencies / Risks

• Historical saved recommendations may not have provider ids, so the UI should tolerate legacy records.
• Provider-specific rate limits and result quality vary; fallback behavior should be observable.
• The canonical schema should be versioned or kept backward compatible to avoid breaking mobile releases.

Open Questions

• Should normalized track ids be provider-prefixed strings, separate provider/id fields, or both?
• Which additional provider or fallback source should be used first after Deezer?
• Should provider capability metadata live on each track or in a separate response-level provider block?