holy-flavor-rater/dashboard-redesign.md

# Dashboard Redesign — Audit & Plan

Scope: the authenticated user dashboard (`frontend/src/pages/Dashboard.tsx`, backend
`GET /api/users/dashboard/` in `backend-rs/src/routes/users.rs:1311`). Goal: cleaner,
more intuitive, more robust UX, plus algorithmic recommendations ("tasters like you
also liked X").

Data scale (current, `backend/db.sqlite3`): **13 users · 219 flavors · 331 ratings ·
~25 ratings/user**. Sparse and small — everything fits in memory; recommendations can
be computed in-process per request. No Redis/precompute needed yet.

---

## Part 1 — Audit of the current dashboard

### Architecture / code quality
- **A1. 1039-line monolith.** `Dashboard.tsx` is one component holding the profile
  header, stats, two tabs, two filter toolbars, two card lists, and inline
  rating-edit + reply editors. Nothing is extracted, nothing is unit-testable in
  isolation.
- **A2. Duplicated rating-edit/reply logic.** The edit-score, edit-comment, reply
  submit, delete-reply handlers (`Dashboard.tsx:148-185`) re-implement what
  `FlavorDetail.tsx` already does. Same bug surface in two places (the Q1 notif-menu
  dedup pattern applies here too).
- **A3. ColorThief on every load.** `Dashboard.tsx:109-146` fetches the avatar as a
  CORS `Image`, runs `colorthief.getPalette(...,10)` on the main thread, and derives
  HSL just to tint a decorative header gradient. Extra dependency, main-thread work,
  CORS dependency — all for cosmetics. Already skipped on mobile (`isXs`).

### Backend / performance
- **A4. Loads every unrated flavor, every hit.** The dashboard handler builds
  `missing_flavors` from *all* flavors the user hasn't rated (~200 rows), with
  per-flavor aggregate rollups, on every dashboard request
  (`users.rs:1340-1378`). No pagination. (P1 already trimmed the *per-rating* payload
  here via `include_ratings=false`, but the row count itself is unbounded.)
- **A5. All filter/sort is client-side** over the full arrays (`Dashboard.tsx:187-237`).
  Fine at 200 items; breaks down as the catalog grows and blocks server-side
  pagination.

### UX / product
- **A6. Thin stats.** Only two numbers surfaced: `rated_count`, `missing_count`
  (`Dashboard.tsx:405-408`). No average score the user gives, no rating distribution,
  no favorite category, no recent-activity sense.
- **A7. "Explore" is an undifferentiated dump.** Tab 2 is the full unrated list sorted
  by community or circle average. No curation, no "for you", overwhelming, no
  pagination, no recommendations.
- **A8. Flat two-tab IA** (My Reviews / Explore New). No personalized landing; the
  user's *taste* is never reflected back to them.
- **A9. Rough edges.** `"Please login to view dashboard."` is a hardcoded,
  untranslated string (`Dashboard.tsx:255`); several toast messages are hardcoded
  English (`'Failed to update review'`, etc.) instead of i18n keys.
- **A10. No recommendations exist** anywhere in the product today.

---

## Part 2 — Recommendation engine (the headline feature)

"Users with the same taste also like X" = **user-based collaborative filtering (CF)**,
with a popularity/quality fallback for cold-start users.

### Algorithm (user-based CF)
1. Load the full rating matrix (331 cells — trivial) into memory: `user → {flavor: score}`.
2. For the target user `u`, compute similarity to every other user `v` over their
   **co-rated** flavors using **Pearson correlation** (mean-centred, so it cancels out
   the fact that some users rate high and some low).
3. **Min-overlap guard:** ignore any `v` sharing fewer than ~3 co-rated flavors —
   correlation over 1–2 points is noise. Apply **significance weighting**
   `sim *= min(overlap, K)/K` (K≈5) to down-weight thin overlaps.
4. For each candidate flavor `f` the target hasn't rated, predict:
   `pred(u,f) = mean_u + Σ_v sim(u,v)·(r_vf − mean_v) / Σ |sim(u,v)|`
   over neighbours `v` who rated `f`. Require ≥2 contributing neighbours for confidence.
5. Rank candidates by `pred`, return top-N with metadata: `predicted_score`,
   `contributing_neighbours` (the "based on N tasters like you" count), and the
   neighbour usernames (optional, for "because Alice & Bob loved it").

### Cold-start fallback (user with < ~5 ratings, or no confident neighbours)
Rank unrated flavors by a **Bayesian average** to stop a single 10/10 from topping the
chart: `score = (C·m + Σr) / (C + n)` where `m` = global mean score, `n` = that
flavor's rating count, `C` ≈ 5 (confidence prior). Optionally bias toward categories the
user has already engaged with.

### Why in-process, on-demand
At 13 users / 331 ratings the whole computation is sub-millisecond. Compute it inside
the recommendations endpoint; add a short per-user cache only if profiling says so.
If the dataset grows orders of magnitude, promote it to a **background job**
(`src/jobs/` already exists) that precomputes per-user recommendations into a table on a
schedule — the engine code stays the same, only the trigger changes.

### Optional companion: item-based CF
Flavor↔flavor cosine over rating vectors powers "people who liked *this* flavor also
liked…" — useful on `FlavorDetail` too, not just the dashboard. Separate, later phase.

---

## Part 3 — Phased implementation plan

Each phase is independently shippable and verified (`tsc` + ESLint + vitest on the
frontend; `cargo fmt`/`clippy`/`test` on the backend).

### Phase 0 — Decompose (no behaviour change) — ✅ DONE
Split the 1039-line `Dashboard.tsx` (now ~115 lines, thin orchestrator) into
`src/pages/dashboard/`:
- `DashboardHeader.tsx` — action bar + profile + stats.
- `MyReviewsTab.tsx` — filter toolbar + list; owns its filter/sort/category state.
- `MyReviewCard.tsx` — one own-review card; **owns its own** edit/reply/expand state
  + mutation calls (replaces the Dashboard-level state maps keyed by rating id).
- `ExploreTab.tsx` — filter toolbar + grid; owns its own filter state.
- `usePalette.ts` — the ColorThief effect, isolated (deleted in Phase 3).

Also fixed A9's hardcoded login string → `t('dashboard.loginRequired')` (EN+DE).
`tsc` clean, ESLint 0 errors (1 pre-existing setState-in-effect warning in the
soon-to-be-deleted `usePalette`), 27 tests pass, `vite build` clean.

**Deviation from original plan:** did *not* force a single shared `ReviewCard`
across Dashboard + `FlavorDetail`. On inspection the two cards are structurally
different — the dashboard card is flavor-centric (one user, many flavors), the
detail card is user-centric (one flavor, many users). Unifying would over-couple two
genuinely different layouts. The cross-file A2 dedup is reduced to a possible future
extraction of just the shared reply-thread atom, tracked but not forced.

### Phase 1 — Enrich the backend payload — ✅ DONE (stats); payload-slim deferred
- Added a **`stats` block** to `DashboardOut` (`dto.rs`): `average_score`,
  `score_distribution` (1–10 histogram, always all 10 keys), `favorite_category`
  (`{name, slug, count}`, deterministic tie-break by slug), `ratings_this_month`
  (current UTC month), `category_count`. Computed in the `dashboard` handler
  (`users.rs`) by a pure `dashboard_stats()` helper over the already-loaded ratings —
  **no new queries**. 3 unit tests (empty / aggregate / tie-break). `cargo fmt` +
  `clippy` clean, 23 backend tests pass.
- Frontend: extended `DashboardData` with `DashboardStats`/`FavoriteCategory`;
  `DashboardHeader` now shows Avg Score + This Month tiles and a "Top category" line
  (i18n EN+DE). `tsc` + ESLint (0 errors) clean, 27 tests, build clean.

**Sequencing change (deliberate):** the planned payload slim — dropping the
all-unrated `missing_flavors` dump (A4) — is **deferred to Phase 3**, where the
Explore tab that still consumes it is removed. Dropping it now would break a live UI
mid-refactor. Phase 1 stayed purely additive.

### Phase 2 — Recommendations engine — ✅ DONE
- New pure module `backend-rs/src/recommend.rs` (no DB → unit-testable): user-based CF
  with Pearson similarity (mean-centred), `MIN_OVERLAP=3`, significance weighting
  `min(overlap,5)/5`, positive-correlation-only neighbours, `MIN_NEIGHBOURS=2`,
  prediction clamped to 1–10. Cold start (`<5` own ratings, or no confident CF
  candidates) → Bayesian-popularity fallback (`C=5`). Deterministic ordering (score →
  neighbours → id). 3 unit tests: cold-start, CF-finds-shared-pick (with opposite-taste
  decoy filtered), exclude-already-rated + limit.
- New endpoint `GET /api/users/recommendations/` (`users.rs`) → `Vec<RecommendationOut>`
  (`dto.rs`): card fields + `predicted_score`, `contributing_neighbours`, `reason`
  (`"cf"`/`"popular"`). **Count only — no neighbour names** (locked decision). Loads
  the full rating matrix once, scores in-process, resolves ids via `build_flavors`
  (`include_ratings=false`). `cargo fmt`/`clippy` clean, 26 backend tests pass.
- Frontend plumbing: `Recommendation` type + `useRecommendations()` query hook
  (key `recommendations`, 5 min staleTime) + `queryKeys.recommendations()`. UI wiring
  is Phase 3. `tsc` + ESLint (0 errors) clean, 27 tests pass.

### Phase 3 — UI redesign ("For You" first) — ✅ DONE
- **Backend payload slim (the deferred A4):** `DashboardOut` no longer ships
  `missing_flavors` (the full unrated `Vec<FlavorOut>` with per-flavor aggregates).
  The handler now computes `missing_count` from flavor ids alone — no `build_flavors`
  pass over ~200 rows, no extra category/rating/user queries. `cargo fmt`/`clippy`
  clean, 26 backend tests pass.
- **Frontend IA:** removed the two-tab layout. Dashboard is now a single page —
  `DashboardHeader` (hero stats) → `RecommendationsSection` ("Tasters like you
  loved", count-only reason chips, skeleton while loading, hidden when empty) → "My
  Reviews" list. Deleted `ExploreTab.tsx`.
- **Dropped ColorThief from the dashboard (A3):** `DashboardHeader` uses a
  theme-derived gradient; deleted `usePalette.ts`. (The npm dep stays — `PublicProfile`
  still uses ColorThief; that's out of dashboard scope.)
- New components: `RecommendationCard.tsx` (image + predicted-score badge + reason
  chip), `RecommendationsSection.tsx` (wraps `useRecommendations`).
- i18n EN+DE: `recHeading`, `recReasonCf`, `recReasonPopular`, `predictedForYou` (plus
  the earlier `loginRequired`/`avgScore`/`thisMonth`/`favoriteCategory`).
- `tsc` + ESLint (0 warnings — the old `usePalette` setState-in-effect warning is gone
  with the file), 27 tests, `vite build` clean.

**Scope note:** the plan's separate "curated rows" (top community / newest) are
covered by the recommendation engine's popularity fallback — a cold or
rated-everything user still gets popularity-ranked picks in the same carousel — so a
distinct curated row was not added. Browsing the full catalog now lives on the main
flavor list, as decided. Leftover unused i18n keys from the old Explore tab
(`searchMissing`, `communityRating`, `circleRating`, `allRated`, `exploreNew`) were
left in place (harmless); can be swept later.

### Phase 4 — Item-based "similar flavors" — ✅ DONE
- **Engine:** added `similar_flavors()` to `backend-rs/src/recommend.rs` — **adjusted
  cosine** over the rating matrix (each user's scores mean-centred to cancel rater
  bias), positive-correlation-only, `MIN_CORATERS=2`, deterministic ordering
  (similarity → co-raters → id). Returns `SimilarFlavor { flavor_id, similarity,
  co_raters }`. 3 unit tests (co-liked / min-coraters guard / unknown target).
- **Endpoint:** `GET /api/flavors/{id}/similar/` (`routes/flavors.rs`, `SIMILAR_LIMIT=8`)
  → `Vec<SimilarFlavorOut>` (`dto.rs`: card fields + `similarity` + `co_raters`).
  404 if the flavor doesn't exist; **empty list** (not 404) when too few co-ratings to
  compute. Loads the matrix once, resolves ids via `build_flavors` (no nested
  ratings/replies). `cargo fmt`/`clippy` clean, **29 backend tests pass**.
- **Frontend:** `SimilarFlavor` type + `queryKeys.similarFlavors(id)` +
  `useSimilarFlavors()` hook (public, 5 min staleTime). New
  `pages/flavors/components/SimilarFlavorsSection.tsx` — "People who liked this also
  liked" grid (compact cards: image + avg-rating badge + status + "N rated both"
  chip), skeleton while loading, **hidden when empty**. Wired into `FlavorDetail.tsx`
  below the ratings grid. i18n EN+DE (`similarHeading`, `similarCoRaters`,
  `similarTooltip`). `tsc` + ESLint (0 warnings), 27 tests, `vite build` clean.

**Deferred (not built):** promoting recommendations to a scheduled precompute job —
unnecessary at current scale (sub-ms in-process); the engine code is unchanged when
that day comes, only the trigger moves. Tracked, not done.

---

## Resolved decisions (user)
- **Recommendation reason = count only.** Show "N tasters like you loved this"; do not
  name neighbours (no privacy exposure). The endpoint still returns
  `contributing_neighbours` as a number; neighbour usernames are not surfaced.
- **Drop ColorThief.** The avatar-derived header gradient is replaced by a
  theme-derived gradient — removes the dependency and the main-thread work (A3). No
  Web Worker needed.
- **Collapse "Explore".** The dashboard no longer hosts a full browsable unrated
  catalog. Dashboard = "For You" (recommendations) + curated rows + My Reviews.
  General browsing lives on the main flavor list. This drops the all-unrated-flavors
  load (A4) entirely from the dashboard payload — a large simplification.

### Plan adjustments from these decisions
- **Phase 1** no longer needs a paginated "browse unrated" view in the dashboard; it
  just adds the stats block and the bounded curated rows. The `missing_flavors` dump
  is removed from the dashboard response outright.
- **Phase 2** endpoint shape: `[{ ...flavor fields, predicted_score,
  contributing_neighbours, reason_key }]` — no neighbour usernames.
- **Phase 3** IA becomes: hero stats → "Tasters like you loved…" carousel → curated
  rows → My Reviews. The second tab ("Explore New") is removed.