# M015: Social Proof, Freshness Signals & Admin UX

**Gathered:** 2026-04-03
**Status:** Ready for planning

## Project Description

Chrysopedia is a music production knowledge base with 20 technique pages, 43 source videos, and 7 creators. This milestone adds social proof and freshness signals to the public site, plus a UX improvement for admin navigation.

## Why This Milestone

The site has content but lacks signals that communicate activity, freshness, and community engagement. Users can't tell when content was last updated, how much content exists, or what other people are searching for. These signals build credibility and guide discovery.

## User-Visible Outcome

### When this milestone is complete, the user can:

- See when each creator last had content added on the Creators browse page
- See a subtle "last updated" date on recently-added homepage cards
- See aggregate stats (article count, creator count) on the homepage in a scorecard-style block
- See what search terms are popular/trending on the homepage
- (Admin) Hover over the Admin dropdown on desktop to open it without clicking

### Entry point / environment

- Entry point: http://ub01:8096
- Environment: Docker Compose on ub01, browser
- Live dependencies involved: PostgreSQL, Redis (for search query caching)

## Completion Class

- Contract complete means: Frontend builds, API endpoints return correct data, search logging confirmed via DB query
- Integration complete means: All features visible on live ub01:8096 site
- Operational complete means: none (no new services)

## Final Integrated Acceptance

To call this milestone complete, we must prove:

- Homepage shows stats scorecard with real counts, trending searches with real terms, and recently-added cards with date tags
- Creators browse page shows last-updated per creator
- Admin dropdown opens on hover (desktop) and tap (mobile)
- search_log table in PostgreSQL has rows from real searches
- Popular searches endpoint returns cached results from Redis

## Risks and Unknowns

- Search query logging must not slow down the search response path — write should be async/non-blocking
- Popular searches cache TTL needs to be short enough to feel "realtime" but long enough to avoid DB load — 5-10 min TTL

## Existing Codebase / Prior Art

- `backend/routers/search.py` — Current search endpoint, needs logging hook added
- `backend/models.py` — All models, need new SearchLog model
- `frontend/src/pages/Home.tsx` — Homepage with recently-added section, popular topics, featured technique
- `frontend/src/pages/CreatorsBrowse.tsx` — Creators list page
- `frontend/src/components/AdminDropdown.tsx` — Click-to-open dropdown, needs hover behavior
- `frontend/src/App.css` — All styles, admin-dropdown styles exist

> See `.gsd/DECISIONS.md` for all architectural and pattern decisions.

## Relevant Requirements

- R033 — Creator Last Updated Date
- R034 — Homepage Stats Scorecard
- R035 — Popular Search Terms Display
- R036 — Admin Dropdown Hover on Desktop

## Scope

### In Scope

- Search query logging to PostgreSQL (search_log table)
- Redis-cached popular searches endpoint
- Creator "last updated" derived from latest technique page created_at
- Homepage stats scorecard block
- Homepage trending searches block
- "Last updated" subtle date on recently-added homepage cards
- Admin dropdown hover on desktop, tap on mobile

### Out of Scope / Non-Goals

- Search analytics dashboard (just the raw logging + public display)
- Zero-result search tracking display (data will exist but no UI for it)
- User accounts or personalization

## Technical Constraints

- PostgreSQL search_log INSERT must be non-blocking (don't slow search responses)
- Redis cache TTL 5-10 minutes for popular searches
- Stats scorecard should use existing API data where possible (avoid new endpoints if a simple aggregate query works)
- Admin dropdown hover must not break mobile touch targets (44x44px minimum)

## Integration Points

- PostgreSQL — New search_log table via Alembic migration
- Redis — Cache key for popular searches (chrysopedia:popular_searches)
- Existing search endpoint — Add logging hook
- Existing creators endpoint — Add last_technique_at field
- Homepage — New sections (stats, trending)

## Open Questions

- None — scope is clear and user confirmed approach
