# UMM UX Flows — Implemented & Tested

**Last verified:** 2026-04-22 (deployed build, backend healthy)

## Navigation

| Route | Page | Nav Label |
|-------|------|-----------|
| `/` | Dashboard | Dashboard |
| `/library` | Library | Library |
| `/library/:type/:id` | Media Detail | (via Library click) |
| `/discover` | Discover | Discover |
| `/calendar` | Calendar | Calendar |
| `/queue` | Download Queue | Queue |
| `/search` | Search Indexers | Search |
| `/activity` | Activity | Activity |
| `/requests` | Requests | Requests |
| `/blocklist` | Blocklist | Blocklist |
| `/settings` | Settings | Settings |

---

## Page-by-Page Flows

### Dashboard (`/`)

**API:** `GET /api/dashboard` (200 OK)

- 8 stat cards: Movies, TV Series, Music, Books, Active Downloads, Missing, Upgrades Available, Total Storage
- Auto-fetches on mount
- Skeleton loading while fetching
- Error banner with retry on failure

### Library (`/library`)

**API:** `GET /api/media?page=1&page_size=50` (200 OK)

- Search input with 300ms debounce
- Type filter: All, Movie, Series, Music, Book, Audiobook, Podcast, Photo, Other
- Status filter: All, Available, Unavailable, Downloading, Failed
- Paginated table (50 per page)
- Each row: Title (click → detail), Type, Status badge, Quality, Monitor toggle
- Monitor toggle: optimistic update, rollback on error with toast
- Empty state messages for no results vs empty library

### Media Detail (`/library/:type/:id`)

**API:** `GET /api/media/:type/:id/detail` (200 OK)

5 tabs (4 for non-series):

**Overview tab:**
- Poster image (or letter placeholder)
- Title, year, original title
- Status badge, monitored indicator
- TMDB rating, genres
- Quality profile name
- Current quality / desired quality
- Synopsis text

**Search tab:**
- Auto-searches indexers for media title
- Results via `ReleaseSearchResults` component
- Sortable by quality, size, seeders, age

**Files tab:**
- File table: name, quality, size, source, codec, subtitles
- Per-file subtitle badges (language code, SDH, Forced, source)
- "Search" button per file → subtitle search modal
- "Download" button per subtitle result
- "Extract All Subtitles" button (extracts embedded subs)

**Episodes tab (series only):**
- Episodes grouped by season
- Columns: episode #, title, status, monitored, has file, quality

**History tab:**
- Timeline with color-coded badges: Grab, Import, Download, Failed, Upgrade, Blocked, Error
- Relative timestamps (Xm ago, Xh ago, Xd ago)

**Header actions:**
- "Refresh Metadata" button → `POST /api/media/:type/:id/refresh-metadata`
- "Delete" button → confirmation modal → `DELETE /api/media/:type/:id` → redirect to Library

### Discover (`/discover`)

**API:** `GET /api/discover/trending?type=movie&page=1` (401 — requires API key auth)
**API:** `GET /api/discover/popular?type=movie&page=1` (401 — requires API key auth)

- Trending / Popular tab toggle
- Movie / Series type filter
- Poster grid with hover overlay (title, year, rating, "Add to Library" button)
- Green checkmark badge for items already in library
- "Add to Library" → `POST /api/discover/add` → toast feedback
- Paginated (prev/next, up to page 10)

**Note:** Requires API key authentication. Frontend does not currently send API keys, so this flow will 401 in production.

### Calendar (`/calendar`)

**API:** `GET /api/calendar?month=2026-04` (200 OK)

- Monthly grid (6 rows × 7 cols)
- Navigation: prev/next month, "Today" button
- Events color-coded by type: movie (indigo), series (emerald), music (amber), audiobook (rose), podcast (violet)
- Click event → navigate to media detail
- "Today" date highlighted with indigo ring
- "+N more" for days with >3 events

### Download Queue (`/queue`)

**API:** `GET /api/queue` (200 OK)

- Tabs: All, Downloading, Pending, Failed, Imported, History
- Auto-refresh every 5 seconds
- Per-item: release title, status badge, download client, quality, size
- Progress bar for downloading items
- Error message display for failed items
- Actions: Cancel (with confirmation modal), Retry, Retry All Failed, Clear Completed
- "Check for Completed Downloads" → `POST /api/imports/trigger`
- Import History tab with pagination (`GET /api/imports/history`)

### Search Indexers (`/search`)

**API:** `GET /api/releases/search?query=...` (500 — "no enabled indexers available" when none configured)

- Free-text search across all enabled indexers
- Sortable columns: Quality, Title, Size, Indexer, Seeders, Age
- "Select & Grab" button per result → opens media selector modal
  - Modal: debounced library search
  - Select media item → `POST /api/releases/grab` → toast
- Empty state for no query, no results, loading skeleton

**Note:** Returns 500 when no indexers are configured. This is expected behavior.

### Activity (`/activity`)

**API:** `GET /api/activity?page=1&page_size=50` (200 OK)

- Paginated event log (50 per page)
- Type filter dropdown: All, Grabs, Imports, Downloads, Failures, Upgrades, Safety Blocks, Errors
- Color-coded badges: Grab (blue), Import/Download (green), Failed/Error (red), Upgrade (purple), Blocked (orange)
- Relative timestamps

### Requests (`/requests`)

**API:** `GET /api/requests?page=1&page_size=20` (401 — requires API key auth)

- Filter tabs: All, Pending, Approved, Fulfilled, Rejected
- "+ New Request" modal:
  - Title (required), Type (7 options), Year, Quality Profile dropdown, Root Folder dropdown
  - Submit → `POST /api/requests`
- Per-request card: title, year, status badge, requester, time ago, quality profile, root folder
- Actions for pending: Approve (green) → `PUT /api/requests/:id/approve`, Reject (red, with confirmation) → `PUT /api/requests/:id/reject`
- Withdraw link for pending/approved → `DELETE /api/requests/:id`

**Note:** Requires API key authentication. Frontend does not currently send API keys.

### Blocklist (`/blocklist`)

**API:** `GET /api/blocklist?page=1&page_size=50` (200 OK)

- Paginated table (50 per page)
- Checkboxes for bulk selection (select all toggle)
- Per-row: release title, indexer, quality, reason, date, delete button
- Bulk "Delete Selected" → `DELETE /api/blocklist/:id` per item
- "Clear Expired" → `DELETE /api/blocklist/expired`
- "Clear All" → confirmation modal → `DELETE /api/blocklist`

### Settings (`/settings`)

8 sections in 2-column grid layout:

#### Notifications
**API:** `GET /api/notifications/channels` (200 OK)

- List channels with enable/disable dot, name, type badge (webhook/telegram), config preview
- Inline edit: name, URL/bot token/chat ID, event type checkboxes (8 types), save/cancel/test/delete
- Add channel: name, type selector, URL or bot token + chat ID, event type checkboxes
- Test button → `POST /api/notifications/channels/:id/test`

#### Indexers
**API:** `GET /api/indexers` (200 OK)

- List with enable/disable dot, name, implementation badge (torznab/newznab/cardigann), URL
- Inline edit: name, URL, API key (masked), enable toggle, save/cancel/test/delete
- Add indexer: name, implementation selector (Newznab, Torznab, Cardigann)
  - Cardigann: YAML textarea, validate button → `POST /api/indexers/validate-cardigann`, settings fields from definition
- Test → `POST /api/indexers/:id/test`

#### Download Clients
**API:** `GET /api/download-clients` (200 OK)

- List with enable/disable dot, name, implementation, URL
- Inline edit: name, URL, API key, category, priority, enable toggle, save/cancel/test/delete
- Add: name, implementation (SABnzbd, qBittorrent), URL, API key
- Test → `POST /api/download-clients/:id/test`

#### Quality Profiles
**API:** `GET /api/quality-profiles` (200 OK)

- List with name, media type badges
- Inline edit: name, cutoff quality, allowed qualities (comma-sep), save/cancel/delete
- Add: name, media types (comma-sep), cutoff quality, allowed qualities

#### Root Folders
**API:** `GET /api/root-folders` (200 OK)

- List with path, media type, free space
- Inline edit: path, media type (delete + re-create pattern), save/cancel/delete
- Add: path, media type

#### Tags
**API:** `GET /api/tags` (200 OK — fixed)

- List with name, color swatch
- Inline edit: name, color, save/cancel/delete
- Add: name, color (hex)

#### Tasks
**API:** `GET /api/workers` (401 — requires API key auth, different from `/api/tasks`)

- Scheduled tasks list with name, cron expression, enabled toggle, last run, next run
- Enable/disable toggle per task

**Note:** Frontend calls `/api/tasks` but router registers `/api/workers`. May result in 404.

#### Metadata
**API:** `POST /api/media/refresh-all` (200 OK, no auth required)

- Description text about refresh scope
- "Refresh All Metadata" button → confirmation modal → POST
- Loading state while refreshing

---

## Shared Components

| Component | Used By | Purpose |
|-----------|---------|---------|
| `Toast` | All pages | Success/error feedback (top-right, auto-dismiss) |
| `ConfirmModal` | Queue, Blocklist, Media Detail, Settings, Requests | Confirmation for destructive/batch actions |
| `Pagination` | Library, Queue, Activity, Blocklist, Requests | Page navigation with total/pages display |
| `StatusBadge` | Library, Queue, Media Detail, Requests | Color-coded status labels |
| `ErrorBanner` | All pages | Error display with retry button |
| `Loading` | Dashboard, Queue, Activity, Blocklist, Settings | Skeleton/spinner loading states |
| `ReleaseSearchResults` | Media Detail, Search | Release result table with grab actions |

---

## API Test Results (2026-04-22)

### Working (200 OK)

| Endpoint | Status | Notes |
|----------|--------|-------|
| `GET /health/live` | 200 | `{"status":"alive"}` |
| `GET /api/dashboard` | 200 | Stats returned, all zeros (empty DB) |
| `GET /api/media` | 200 | Paginated, empty |
| `GET /api/queue` | 200 | Empty |
| `GET /api/blocklist` | 200 | Paginated, empty |
| `GET /api/activity` | 200 | Paginated, empty |
| `GET /api/indexers` | 200 | Empty |
| `GET /api/download-clients` | 200 | Empty |
| `GET /api/quality-profiles` | 200 | Empty |
| `GET /api/root-folders` | 200 | Empty |
| `GET /api/tags` | 200 | Empty (fixed: removed `created_at` column ref) |
| `GET /api/notifications/channels` | 200 | Empty |
| `GET /api/calendar` | 200 | Empty events |
| `GET /api/search` | 200 | Empty results |
| `GET /api/imports/history` | 200 | Empty |
| `POST /api/media/refresh-all` | 200 | Triggers refresh |

### Auth-Required (401 Unauthorized)

| Endpoint | Notes |
|----------|-------|
| `GET /api/requests` | API key auth middleware |
| `GET /api/discover/trending` | API key auth middleware |
| `GET /api/discover/popular` | API key auth middleware |
| `GET /api/workers` | API key auth middleware |

**Root cause:** Frontend `client.ts` does not send `X-API-Key` header or `api_key` query param. These flows (Requests, Discover, Tasks) will 401 in production unless auth is configured or the frontend is updated to pass API keys.

### Expected Errors (500)

| Endpoint | Error | Cause |
|----------|-------|-------|
| `GET /api/releases/search` | "no enabled indexers available" | No indexers configured yet |

---

## Known Issues

1. **Auth-protected endpoints unreachable from frontend** — Requests, Discover, and Tasks pages will show errors because the API client doesn't pass API keys. The `newAPIKeyAuth` middleware requires `X-API-Key` header or `api_key` query param.

2. **Tasks page route mismatch** — Frontend calls `/api/tasks` but router registers workers at `/api/workers`. Needs alignment.

3. **No indexers configured** — Release search (used by Search page and Media Detail Search tab) returns 500. Expected until indexers are added via Settings.

4. **Frontend CORS** — CORS is configured to allow `cfg.FrontendURL` only. Requests from other origins will be rejected.