Draft: Resolve "feat: Add Optional Category Tag Filtering to Peer Review Interface"

Description:

MR: Category-based Tag Filtering for Peer Review Page

This Merge Request adds category-based tag filtering to the Peer Review interface (/peer-review), significantly improving record discoverability without disrupting existing text-based search or workflows.

The feature is:

• Fully optional
• Built on existing backend APIs
• Non-breaking
• Modular and extensible

Problem Statement

The Peer Review page currently offers only text-based search. As the corpus grows, this creates friction:

• Reviewers must perform repeated manual searches to find category-specific records
• Discoverability of grouped/category-based content is limited
• Existing category-related backend APIs remain underutilised

Proposed Solution

Introduce intuitive category tag filtering:

• Fetch available categories from the backend
• Display them as clickable tags below/near the search bar
• Selecting a tag filters the feed to show only records in that category
• Clicking the same tag again clears the filter
• Category filter combines cleanly with existing text search

User Flow

1. Navigate to /peer-review
2. Categories load asynchronously (with loading & error states)
3. Tags appear below the search bar
4. Click a category tag → feed updates to show matching records
5. Click the active tag again → filter clears, full feed returns
6. Text search + category filter work together seamlessly

Filtering Logic

• Category filter applied only when a tag is selected
• Uses backend filtering when supported (category param in /records/search)
• Falls back to safe client-side filtering if needed
• No category selected → current global search/pagination behaviour unchanged

APIs Used

Endpoint	Purpose
GET /api/v1/categories/	Fetch list of available categories
GET /api/v1/records/search	Retrieve records (with optional category)

→ No new endpoints are introduced.

Scope

In Scope

• Category API integration & service/hook
• Clickable tag UI component in Peer Review
• Filtering logic (backend + fallback)
• Active/inactive tag visual states
• Responsive layout (desktop + mobile)
• Unit & integration tests
• Loading/error handling

Out of Scope

• Multi-category (AND/OR) selection
• Category creation/moderation
• Persisting filter in URL
• Backend API modifications

Roadmap / Implementation Phases

1. Phase 1 – Data Integration

   • Category API service
   • Reusable category data hook
   • Loading, error, empty states

2. Phase 2 – UI Integration

   • Category tag list component
   • Placement near the search bar
   • Active/inactive styling
   • Mobile responsiveness

3. Phase 3 – Filtering Logic

   • Wire category selection to record fetch
   • Support toggle-to-clear
   • Combine with text search
   • Preserve pagination

4. Phase 4 – Testing & Validation

   • Unit tests (hooks, services)
   • Integration tests (filter behaviour)
   • Manual testing (desktop + mobile)

5. Phase 5 – Documentation & Polish

   • Update feature docs
   • Add screenshots/GIF in MR
   • Final accessibility check

How to Test

1. Go to /peer-review
2. Confirm category tags load (no errors, graceful if API fails)
3. Click any category tag → feed should filter to that category
4. Click the same tag again → filter clears, full feed returns
5. Enter text search + active category → both filters apply
6. Refresh page → no persisted filter (as designed)

Acceptance Criteria

• Categories load successfully on page load
• Categories render as clickable tags near search bar
• Selecting a tag filters feed to matching records
• Re-clicking active tag clears the filter
• Text search continues to work normally (alone or combined)
• Feature is responsive on desktop and mobile
• Graceful degradation if category API fails

Benefits

• Dramatically better discoverability of category-grouped records
• Faster, more focused peer review experience
• Reduces repetitive manual searching
• Makes full use of existing backend category support
• Clean foundation for future multi-filter enhancements

Risks / Concerns

• Inconsistent backend category tagging → may return unexpected results (mitigated by graceful fallback)
• Category API failure → UI degrades silently to current behaviour
• No regression risk to core search/pagination

Labels: ~"feature" ~"peer-review" ~"ui" ~"filtering" ~"discoverability" ~"medium"
Weight / Priority: Medium
Reviewers: @username1 @username2 (please update)
Related Issues: #XYZ (if tracked)

Ready for review — looking forward to your feedback!
Thanks!