feat: Price Intelligence — marketplace trends and collection valuation

[SimplicityGuy]

Overview

Track historical marketplace pricing data from Discogs to surface value trends, price movements, and collection valuation insights. Collectors care deeply about the value trajectory of their vinyl — this feature turns raw marketplace stats into actionable intelligence.

Discogs exposes public pricing statistics (lowest, median, highest) for releases via their API. By periodically capturing and storing this data in PostgreSQL, we can build time-series trend analysis that no other Discogs tool provides.

Proposed Endpoints

API Endpoints (api/routers/market.py)

Endpoint	Description
GET /api/market/release/{id}/price	Current and historical pricing stats for a release
GET /api/market/artist/{id}/trends	Aggregate price trends across an artist's discography
GET /api/market/label/{id}/trends	Aggregate price trends across a label's catalog
GET /api/market/collection/summary	Total estimated value and breakdown for the authenticated user's collection
GET /api/market/collection/movers?period=30d	Biggest gainers and losers in the user's collection over a time period
GET /api/market/hot?genre={style}&period=7d	Trending releases by price movement across the marketplace

Data Model

New PostgreSQL tables:

• price_snapshots — (release_id, snapshot_date, lowest, median, highest, num_for_sale, currency)
• price_alerts — (user_id, release_id, condition, threshold, active)

Background Worker

A periodic task (daily or configurable) that:

1. Iterates releases in users' collections
2. Fetches current marketplace stats from the Discogs API
3. Stores snapshots in price_snapshots
4. Checks against price_alerts thresholds and flags triggered alerts

Must respect Discogs API rate limits (60 req/min for authenticated requests).

Explore UI — "Market" Pane

Add a Market pane to the Explore sidebar navigation.

Pane Layout

1. Collection Value Card — total estimated value (sum of medians), change over 30d, sparkline
2. Movers Table — sortable table of biggest gainers/losers with columns: release title, artist, current median, change (absolute + %), mini sparkline
3. Release Price Detail — clicking a release opens a Plotly.js chart showing price history (lowest/median/highest bands over time)
4. Price Alerts — set threshold alerts ("notify me if median drops below $X") with a small alert management UI
5. Hot Releases — trending releases by price movement, filterable by genre/style

UI Details

• Sparklines rendered inline using Plotly.js (already a dependency)
• Color-coded price changes: green for gains, red for losses
• Currency display respects user locale
• Empty state: prompt to sync collection first

Implementation Notes

• Price data fetching should be throttled and batched to respect Discogs rate limits
• Cache current prices in Redis (TTL 1h) to avoid redundant API calls
• Store historical data in PostgreSQL for time-series queries
• Complements Taste Fingerprint (feat: Taste Fingerprint — personal collection analytics and shareable taste card #120) — "your taste skews toward appreciating vinyl"
• Complements Export & Backup (feat: Export & Backup — collection data portability #98) — include valuation data in exports
• Complements Notifier (feat: Notifier Service — watchlists and alerts for new music data #86) — price alerts feed into notification system

Acceptance Criteria

• Price snapshot worker runs daily without exceeding rate limits
• Collection summary returns total value and per-release breakdown
• Movers endpoint returns top gainers/losers for configurable time periods
• Release price chart shows historical lowest/median/highest
• Price alerts can be created, listed, and deleted
• Explore UI "Market" pane displays all components
• ≥80% test coverage for API endpoints and worker logic

[SimplicityGuy]

Status Update — 2026-03-25

Not started. No implementation or design work has been merged to main for this feature.