> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# UJ-M-006: Browse and Filter Events

> Member discovers upcoming events through browsing, searching, and filtering

## Journey Overview

| Attribute      | Value                                        |
| -------------- | -------------------------------------------- |
| **Journey ID** | UJ-M-006                                     |
| **Actor**      | Member (or public visitor for public events) |
| **Goal**       | Find relevant events to attend               |
| **Trigger**    | Member navigates to Events section           |
| **Outcome**    | Member finds events of interest              |

## Preconditions

* Events exist in the system
* For member-only events: User is authenticated
* Events are published and not past

## Journey Flow

```mermaid theme={null}
flowchart TD
    A[Navigate to Events] --> B[View event listing]
    B --> C{Apply filters?}
    C -->|Yes| D[Select filter criteria]
    C -->|No| E[Browse all events]
    D --> F[View filtered results]
    E --> F
    F --> G{Change view?}
    G -->|List| H[List view]
    G -->|Calendar| I[Calendar view]
    G -->|Map| J[Map view]
    H --> K[Click event]
    I --> K
    J --> K
    K --> L[View event details]
```

## Detailed Steps

<Steps>
  <Step title="Access Events Section">
    Member clicks "Events" in navigation:

    **Default View:**

    * Upcoming events (next 30 days first)
    * Card or list layout
    * Pagination or infinite scroll
    * Total event count displayed
  </Step>

  <Step title="Browse Event Cards">
    Each event card displays:

    | Element        | Description                      |
    | -------------- | -------------------------------- |
    | Featured Image | Event banner/thumbnail           |
    | Title          | Event name                       |
    | Date & Time    | Start date, time, timezone       |
    | Location       | Venue name or "Online"           |
    | Category       | Event type badge                 |
    | Price          | "Free" or starting price         |
    | CPD Points     | Points available (if applicable) |
    | Spots Left     | Capacity indicator               |
  </Step>

  <Step title="Search Events">
    Member uses search bar:

    **Search Fields:**

    * Event title
    * Description
    * Speaker names
    * Venue name
    * Keywords/tags

    **Search Behavior:**

    * Real-time filtering (debounced)
    * Highlights matching terms
    * "No results" with suggestions
  </Step>

  <Step title="Apply Filters">
    Available filter options:

    **Date Range:**

    * Today
    * This week
    * This month
    * Custom range picker

    **Event Type:**

    * Live (in-person)
    * Online (virtual)
    * Webinar
    * Hybrid

    **Category:**

    * Professional Development
    * Networking
    * Conference
    * Workshop
    * Social
    * (Organization-defined categories)

    **Location:**

    * City/Region filter
    * "Near me" (with geolocation)
    * State/Country

    **Price:**

    * Free events only
    * Paid events only
    * Price range slider

    **CPD:**

    * Events with CPD points
    * Specific CPD category

    **Other:**

    * Member-only events
    * Available spots (not sold out)
    * My registered events
  </Step>

  <Step title="Change View Mode">
    Member can switch between views:

    <Tabs>
      <Tab title="List View">
        * Chronological list
        * More events per page
        * Quick scan of details
        * Best for: finding specific dates
      </Tab>

      <Tab title="Card/Grid View">
        * Visual cards with images
        * 3-4 per row
        * Engaging presentation
        * Best for: browsing/discovery
      </Tab>

      <Tab title="Calendar View">
        * Monthly calendar layout
        * Events on date cells
        * Week/month toggle
        * Best for: planning attendance
      </Tab>

      <Tab title="Map View (if enabled)">
        * Geographic view for live events
        * Markers on map
        * List alongside map
        * Best for: finding local events
      </Tab>
    </Tabs>
  </Step>

  <Step title="Sort Results">
    Sorting options:

    | Sort             | Description              |
    | ---------------- | ------------------------ |
    | Date (soonest)   | Default - upcoming first |
    | Date (latest)    | Future events first      |
    | Price (low-high) | Cheapest first           |
    | Price (high-low) | Premium first            |
    | Popularity       | Most registrations       |
    | Recently added   | Newest listings          |
  </Step>

  <Step title="Click to View Details">
    Member clicks event card to view full details.

    → Proceeds to [UJ-M-007: View Event Details](/member/journeys/view-event-details)
  </Step>
</Steps>

## Event Status Indicators

| Status              | Display                | Action                      |
| ------------------- | ---------------------- | --------------------------- |
| Open                | "Register Now"         | Can register                |
| Almost Full         | "Only X spots left"    | Urgency indicator           |
| Sold Out            | "Sold Out" badge       | Waitlist option             |
| Registration Closed | "Registration Closed"  | View only                   |
| Cancelled           | "Cancelled" badge      | Not displayed by default    |
| Past                | Moved to "Past Events" | View recording if available |

## Personalization

Events may be personalized based on:

* Member's interest categories
* Past event attendance
* Geographic location
* Membership tier
* Followed speakers/topics

**Personalized Sections:**

* "Recommended for You"
* "Based on Your Interests"
* "Popular in Your Area"

## Mobile Experience

<Tabs>
  <Tab title="Mobile Optimizations">
    * Swipeable event cards
    * Bottom sheet filters
    * Calendar view adapted for mobile
    * Pull-to-refresh
    * Floating "Filter" button
  </Tab>

  <Tab title="Native Features">
    * Add to phone calendar
    * Share via native share sheet
    * Maps integration for directions
    * Push notifications for reminders
  </Tab>
</Tabs>

## Related Entities

* [`Event`](/entities/core/event)
* [`Event Category`](/entities/core/event-category)
* [`Event Type`](/entities/core/event-type)
* [`Interest Category`](/entities/core/interest-category)

## Related Journeys

* [UJ-M-007](/member/journeys/view-event-details)
* [UJ-M-008](/member/journeys/purchase-event-ticket)
* [UJ-M-032](/member/journeys/add-to-calendar)

## Acceptance Criteria

### Frontend

* [ ] Event listing with card/list toggle
* [ ] Search bar with real-time filtering
* [ ] Filter panel with all criteria
* [ ] Calendar view with month navigation
* [ ] Map view for live events (optional)
* [ ] Sort dropdown
* [ ] Pagination or infinite scroll
* [ ] Loading skeletons during fetch
* [ ] Empty state for no results
* [ ] Mobile-responsive design

### Backend

* [ ] `GET /api/events` - List events with filters
* [ ] Query params: `?type=`, `?category=`, `?date_from=`, `?date_to=`
* [ ] Query params: `?search=`, `?sort=`, `?page=`, `?limit=`
* [ ] Query params: `?lat=`, `?lng=`, `?radius=` (for location)
* [ ] Includes: registration count, spots remaining

### Permissions

* [ ] Public events visible to all
* [ ] Member-only events require authentication
* [ ] Draft/unpublished events hidden

### Business Rules

* [ ] Past events moved to separate section
* [ ] Cancelled events excluded from listing
* [ ] Sold out events show waitlist option
* [ ] Events ordered by date (soonest first) by default

### Error Handling

* [ ] Search with no results shows suggestions
* [ ] Filter combinations that yield zero results handled gracefully
* [ ] Offline mode shows cached events