modbison/docs/planning/discovery.md

# Discovery — Browse, Search & Home — Plan

> **Status:** Planned
> **Owner:** Platform team
> **Feature ID:** `discovery`
> **Godot version:** 4.6.2 stable
> **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis

## 1. Overview

This document breaks the **Discovery** feature into user stories and
right-sized implementation tasks. The feature delivers:

- **Home / discover page** — a default listing of experiences a player lands on.
- **Search** — find worlds by name and by tag.
- **Categories** — a single category per world plus free-form tags, with
  filtering.
- **Simple sorting** — newest, most-played, and trending. Trending starts as a
  basic **recent-activity heuristic** (weighted recent visits); no real
  recommendation model for MVP.

Without this, nothing else built (experiences, creator content) is actually
reachable by a real user. Discovery is the front door.

## 2. Why this matters

The platform's value is *reachable* content. Worlds and creator assets already
exist in the data model (`World`, `Asset`), but there is currently:

- **No public listing** of worlds (`/api/worlds` requires auth and returns only
  PUBLIC worlds or your own worlds, ordered by `created_at` only).
- **No search** by name or tag.
- **No category/tag metadata** on worlds at all.
- **No play-count or recency signal** to power "most-played" or "trending".
- **No client UI** for browsing.

Discovery closes that gap with a small, dependency-free metadata layer plus a
read-optimized listing endpoint.

## 3. Existing constraints (do not re-build)

- **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in
  `app/dependencies.py`. Discovery **listing** must work both for anonymous
  visitors and authenticated users, so it needs an *optional* auth dependency
  (not `CurrentUser`, which returns 401).
- **DB:** async SQLAlchemy + Alembic; migration head is `0002_add_date_of_birth_to_users`.
- **Models:** `World` (id, name, description, owner_id, visibility, created_at,
  updated_at). `User`, `Asset` (owner_id, is_public) exist. No tags/categories/
  play-count fields yet.
- **Routers:** `worlds.py` already owns CRUD under `/api/worlds`. Discovery adds
  a new read-focused router rather than overloading it.
- **Redis:** configured (`REDIS_URL`) but unused; **not required** for discovery
  MVP (Postgres queries are sufficient at this scale).
- **Client:** Godot 4.6.2, minimal `main_menu.gd`; no networking client, no
  discovery UI.

## 4. Key design decisions

| Concern | Decision |
|---|---|
| Listing transport | REST (`GET /api/discovery/worlds`) — no WebSocket needed for browse |
| Anonymous browsing | Listing/read endpoints accept **optional** auth; visibility filtering treats anonymous users as "PUBLIC only" |
| Categories | Single `category` string column on `worlds` (indexed). Free-form for MVP; a distinct-categories list is derived with a `SELECT DISTINCT` |
| Tags | PostgreSQL `ARRAY(String)` column on `worlds` with a GIN index for `@>` tag containment search |
| Play count | `play_count` integer (default 0) on `worlds`, incremented atomically on visit |
| Recency signal | `last_played_at` timestamp on `worlds` + append-only `world_visits` table for the trending heuristic |
| Trending (MVP) | Weighted score over recent visits: `sum(decay_weight(age))` over the last N days, no ML |
| Sorting | `newest` (created_at desc), `most_played` (play_count desc), `trending` (score desc) |
| Pagination | `skip`/`limit` (limit capped at 100), consistent with existing routers |
| Visibility | Discovery only surfaces `PUBLIC` worlds; never leaks private/friends_only worlds |

## 5. User stories

### US-1 Home / discover feed
As a player, I can open a home/discover page and see a default list of
experiences without searching.

**Acceptance criteria**
- Returns PUBLIC worlds only, newest-first by default.
- Paginated with a stable total count.
- Works anonymously and authenticated.
- Each result includes id, name, description, category, tags, owner, play_count,
  and created_at.

### US-2 Search
As a player, I can search experiences by name and by tag.

**Acceptance criteria**
- Case-insensitive substring search on `name`.
- Tag search matches worlds containing *any* of the requested tags.
- Search combines with category filter and sort.

### US-3 Categories & sorting
As a player, I can filter by category and sort by newest, most-played, or
trending.

**Acceptance criteria**
- `category` filter matches exactly (case-insensitive).
- Distinct category list is available for UI dropdowns.
- `newest`, `most_played`, and `trending` sorts are supported.
- `most_played` uses `play_count`; `trending` uses the recent-visits heuristic.

### US-4 Visit tracking
As a player, opening a world records a visit so counts and trending stay fresh.

**Acceptance criteria**
- `POST /api/worlds/{id}/visit` increments `play_count` and updates
  `last_played_at`.
- Appends a `world_visits` row (world_id, user_id or anonymous marker,
  visited_at).
- Idempotent per request; rate-limitable later.

### US-5 Godot client
As a player, I can browse, search, filter, and sort experiences from the game UI.

**Acceptance criteria**
- An HTTP API client handles the discovery endpoints (JWT + anonymous).
- A discover/home screen lists experiences with search, category filter, and
  sort controls.
- Results render name, category, tags, play count, and description.

## 6. Task breakdown

Right-sized to 1–3 files / one coherent piece of functionality each.

| # | Task | Story | Depends on |
|---|------|-------|-----------|
| 1 | World discovery metadata + visits model & Alembic migration | US-2, US-3, US-4 | — |
| 2 | World visit tracking endpoint (play count + last played + visit log) | US-4 | 1 |
| 3 | Browse + search endpoint (name/tag/category, newest + most-played) | US-1, US-2, US-3 | 1, 2 |
| 4 | Trending sort (recent-activity heuristic over `world_visits`) | US-3 | 3 |
| 5 | Godot discovery API client (HTTP + optional JWT) | US-5 | 3 |
| 6 | Godot discover/home UI (feed, search, category filter, sort) | US-5 | 4, 5 |

## 7. Phasing

- **Phase 1 (data + core read API):** tasks 1–3 (metadata, visit tracking,
  browse/search).
- **Phase 2 (trending):** task 4 — the only non-trivial query; isolated so it
  can be tuned without touching the browse surface.
- **Phase 3 (client):** tasks 5–6, each landing after its backend dependency.

## 8. Out of scope for this feature

- Real recommendation models / personalization (collaborative filtering, ML).
- Full-text search (Postgres FTS); MVP uses ILIKE substring match.
- Faceted search with multiple simultaneous category/tag AND-semantics.
- Featured/editorial curation and admin-curated carousels.
- Search result relevance scoring beyond the three explicit sorts.
- Analytics dashboards; `world_visits` is append-only signal, not a BI surface.