Save workspace changes

.deploy/artwork-evolution-release/docs/Discover/today-downloads.md

@@ -0,0 +1,63 @@
+# Today Downloads
+
+## Route
+
+- URL: `GET /downloads/today`
+- Controller: `App\Http\Controllers\User\TodayDownloadsController::index()`
+
+## Important scope note
+
+This page is not inside `/discover/*`, but it is included here because it is discovery-adjacent and was requested together with the Discover surfaces.
+
+## What the page reads
+
+This page does not use Meilisearch.
+It is a direct MySQL query over the download event log.
+
+## Query logic
+
+The controller:
+
+1. Takes today's date
+2. Reads `artwork_downloads`
+3. Filters rows to `whereDate(created_at, today)`
+4. Groups by `artwork_id`
+5. Orders by `COUNT(*) DESC`
+6. Eager-loads each artwork and related user/category data
+
+Effectively:
+
+```text
+SELECT artwork_id, COUNT(*) AS num_downloads
+FROM artwork_downloads
+WHERE DATE(created_at) = today
+GROUP BY artwork_id
+ORDER BY num_downloads DESC
+```
+
+Only artworks that are currently public and published are allowed through `whereHas('artwork', ...)`.
+
+## Data sources
+
+- primary source: `artwork_downloads`
+- supporting source: `artworks`, `users`, `user_profiles`, `categories`
+
+Unlike `Most Downloaded`, this page does not trust the aggregate `artwork_stats.downloads` counter for ranking.
+It re-counts today's actual events.
+
+## Cache behavior
+
+- no dedicated application cache in the controller
+
+The page is as fresh as the underlying event log.
+
+## Background jobs and schedules
+
+No page-specific cron is needed because it reads the raw event log directly.
+
+The only prerequisite is that downloads are being recorded correctly by the download endpoint.
+
+## Notes
+
+- This page is often the more operationally trustworthy answer to "what is being downloaded right now?"
+- Because it counts raw rows, it is less sensitive to delayed aggregate-counter flushes than `Most Downloaded`.