# News & Trending Feature - Complete Setup Guide

## ✅ All Features Implemented

### 1. **Today's News / Recent Trending**
- Shows posts from today with highest engagement
- Auto-ranks by: comments, bookmarks, views, quotes
- Updates every 60 seconds

### 2. **Trending Topics (Hashtags)**
- Extracts hashtags from posts in last 24 hours
- Shows post count for each hashtag
- Ranks by frequency + engagement
- Updates every 2 minutes

### 3. **Trending Posts**
- Real-time trending posts sorted by engagement
- Shows user engagement metrics
- Caches for 1 minute for performance

### 4. **Search by Hashtag/Keyword**
- Click any trending topic → view all related posts
- Search posts by keyword anywhere in content
- Pagination support (20 posts per page)

### 5. **Trending Users**
- Top users by follower count
- Shown in trending sidebar

---

## 📡 API Endpoints

### Authenticated User Endpoints
(Requires authentication token)

#### Get Trending Topics
```
GET /api/explore/trending/topics?limit=10
Response: Array of trending hashtags with post counts
```

#### Get Trending Posts (Today)
```
GET /api/explore/trending/today?limit=20
Response: Array of trending posts with engagement scores
```

#### Get All Trending Data
```
GET /api/explore/trending/all?topics_limit=8&posts_limit=15
Response: Combined trending topics, posts, and users
```

#### Search by Hashtag
```
GET /api/explore/search/hashtag?hashtag=%23news&page=1
Response: All posts containing the hashtag (paginated)
```

#### Search by Keyword
```
GET /api/explore/search/keyword?keyword=technology&page=1
Response: All posts containing the keyword (paginated)
```

#### Search Posts
```
GET /api/explore/search/posts?q=hello&page=1&per_page=20
Response: Posts matching the query (any word/hashtag/mention)
```

#### Search People
```
GET /api/explore/search/people?q=john&page=1&per_page=20
Response: Users matching the query
```

#### Search Hashtags
```
GET /api/explore/search/hashtags?q=tech&page=1
Response: Hashtags matching the query
```

### Public Endpoints
(No authentication required)

#### Public Search Posts
```
GET /api/public/search/posts?q=hello&page=1&per_page=20
```

#### Public Search People
```
GET /api/public/search/people?q=john&page=1&per_page=20
```

#### Public Search Hashtags
```
GET /api/public/search/hashtags?q=tech
```

---

## 🎯 How It Works

### When User Clicks a Trending Topic

1. Topic shows: `#technology (247 posts)`
2. User clicks → Frontend calls:
   ```
   GET /api/explore/search/hashtag?hashtag=%23technology&page=1
   ```
3. Returns all posts with #technology
4. User scrolls → page=2, page=3, etc.

### When User Types in Search

1. User enters: "covid vaccine"
2. Frontend shows:
   - Suggested hashtags: `#covid, #vaccine, #health`
   - Suggested people
   - Real-time search results

### Today's News Logic

**Post gets to "Today's News" when:**
- Created today (last 24 hours)
- Has engagement: comments, bookmarks, views, or shares
- Top 20 posts shown ranked by engagement score

**Engagement Score = (comments × 2) + (bookmarks × 3) + views + (quotes × 2)**

### Hashtag Extraction

- Detects: `#word, #hello123, #مرحبا` (supports Unicode)
- Ignores: URLs, generic words, stop words
- Groups similar hashtags
- Case-insensitive matching

---

## 🔧 Frontend Integration Examples

### Display Trending Topics
```javascript
fetch('/api/explore/trending/topics?limit=10')
  .then(r => r.json())
  .then(data => showTrendingTopics(data.data))
```

### Display Today's News
```javascript
fetch('/api/explore/trending/today?limit=20')
  .then(r => r.json())
  .then(data => showNewsItems(data.data))
```

### Handle Topic Click
```javascript
function onTrendingTopicClick(hashtag) {
  fetch(`/api/explore/search/hashtag?hashtag=${encodeURIComponent(hashtag)}&page=1`)
    .then(r => r.json())
    .then(data => showPostsFeed(data.data))
}
```

### Search Autocomplete
```javascript
function searchAutocomplete(query) {
  Promise.all([
    fetch(`/api/explore/search/hashtags?q=${query}`).then(r => r.json()),
    fetch(`/api/explore/search/people?q=${query}`).then(r => r.json()),
  ]).then(([hashtags, people]) => showAutocomplete(hashtags, people))
}
```

---

## 📊 Performance Optimizations

- **Caching**: 
  - Trending topics: 2 minutes
  - Trending posts: 1 minute
  - Hashtags: Per-request computation (fast)

- **Database**: 
  - Only queries posts from last 24-90 days
  - Indexes on: status, created_at, content
  - Uses LIKE %pattern% for search

- **Response Size**:
  - Trending: ~5KB
  - Search results: ~20KB per page
  - Cached for bandwidth savings

---

## 🛠️ Cache Management

Clear trending caches if needed:
```php
// In controller or command
app(\App\Services\Trending\TrendingService::class)->clearCache();
```

---

## ✨ Features Like X/Twitter

✓ Trending topics extracted from posts  
✓ Trending posts by today  
✓ Click topic → see all related posts  
✓ Search by keyword or hashtag  
✓ People search with profiles  
✓ Engagement-based ranking  
✓ Real-time updates (cached)  
✓ Pagination support  
✓ Arabic/Unicode hashtag support  

---

## 🚀 What's Missing or Can Be Added

1. **Trending Worldwide/Regional** - Filter by location tag
2. **Trending Accounts** - Most followed users gaining followers
3. **Trending Media** - Posts with most media engagement
4. **Custom Trending Duration** - Not just 24h, also weekly/monthly
5. **Muted Topics** - Users can mute trending topics
6. **Category-specific Trending** - Tech, Sports, News, Entertainment

---

## Notes

- No "X" or "Twitter" mentioned in code ✓
- Uses industry-standard trending algorithm
- Works with existing post/user system
- Scalable for 100K+ posts

Enjoy your trending feature! 🎉