mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 17:51:08 -05:00
dcf890a55c
- Added EntitySuggestionManager.vue to manage entity suggestions and authentication. - Created EntitySuggestionModal.vue for displaying suggestions and adding new entities. - Integrated AuthManager for user authentication within the suggestion modal. - Enhanced signal handling in start-servers.sh for graceful shutdown of servers. - Improved server startup script to ensure proper cleanup and responsiveness to termination signals. - Added documentation for signal handling fixes and usage instructions.
140 lines
4.1 KiB
Markdown
140 lines
4.1 KiB
Markdown
# ThrillWiki Trending & New Content System Architecture
|
||
|
||
## System Overview
|
||
|
||
This document outlines the architecture for implementing real trending and new content functionality to replace the current mock data implementation on the ThrillWiki home page.
|
||
|
||
## Current State Analysis
|
||
|
||
### Frontend Structure (Vue 3 + TypeScript)
|
||
- **Home.vue** expects specific data formats:
|
||
- **Trending Content**: `{id, name, location, category, rating, rank, views, views_change, slug}`
|
||
- **New Content**: `{id, name, location, category, date_added, slug}`
|
||
- **Tabs Supported**:
|
||
- Trending: Rides, Parks, Reviews
|
||
- New: Recently Added, Newly Opened, Upcoming
|
||
|
||
### Backend Infrastructure
|
||
- **Django REST Framework** with comprehensive ViewSets
|
||
- **pghistory** already tracking model changes
|
||
- **Existing endpoints** for recent changes, openings, closures
|
||
- **Models**: Park and Ride with ratings, status, dates
|
||
|
||
## Proposed Architecture
|
||
|
||
### 1. Data Flow Architecture
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[User Views Page] --> B[View Tracking Middleware]
|
||
B --> C[PageView Model]
|
||
|
||
D[Trending Calculation Job] --> E[Trending Algorithm]
|
||
E --> F[Cache Layer]
|
||
|
||
G[Frontend Request] --> H[API Endpoints]
|
||
H --> F
|
||
F --> I[Serialized Response]
|
||
I --> J[Frontend Display]
|
||
|
||
K[Management Command] --> D
|
||
L[Celery/Cron Schedule] --> K
|
||
```
|
||
|
||
### 2. Database Schema Design
|
||
|
||
#### PageView Model
|
||
```python
|
||
class PageView(models.Model):
|
||
content_type = models.ForeignKey(ContentType)
|
||
object_id = models.PositiveIntegerField()
|
||
content_object = GenericForeignKey('content_type', 'object_id')
|
||
|
||
user_session = models.CharField(max_length=40)
|
||
ip_address = models.GenericIPAddressField()
|
||
user_agent = models.TextField()
|
||
timestamp = models.DateTimeField(auto_now_add=True)
|
||
|
||
class Meta:
|
||
indexes = [
|
||
models.Index(fields=['content_type', 'object_id', 'timestamp']),
|
||
models.Index(fields=['timestamp']),
|
||
]
|
||
```
|
||
|
||
### 3. Trending Algorithm
|
||
|
||
#### Calculation Components
|
||
- **View Count Weight**: Recent page views (configurable time window)
|
||
- **Rating Weight**: Average rating from Park/Ride models
|
||
- **Recency Boost**: Recently added/updated content bonus
|
||
- **Category Balancing**: Ensure diverse content across categories
|
||
|
||
#### Formula
|
||
```
|
||
Trending Score = (View Score × 0.4) + (Rating Score × 0.3) + (Recency Score × 0.2) + (Engagement Score × 0.1)
|
||
```
|
||
|
||
### 4. API Endpoints Design
|
||
|
||
#### Trending Endpoint
|
||
```
|
||
GET /api/v1/trending/?tab={rides|parks|reviews}&limit=6
|
||
```
|
||
|
||
#### New Content Endpoint
|
||
```
|
||
GET /api/v1/new-content/?tab={recently-added|newly-opened|upcoming}&limit=4
|
||
```
|
||
|
||
### 5. Caching Strategy
|
||
|
||
#### Cache Keys
|
||
- `trending_rides_6h`: Trending rides cache (6 hour TTL)
|
||
- `trending_parks_6h`: Trending parks cache (6 hour TTL)
|
||
- `new_content_24h`: New content cache (24 hour TTL)
|
||
|
||
#### Cache Invalidation
|
||
- Manual refresh via management command
|
||
- Automatic refresh on schedule
|
||
- Cache warming during low-traffic periods
|
||
|
||
### 6. Performance Considerations
|
||
|
||
#### View Tracking Optimization
|
||
- Async middleware for non-blocking view tracking
|
||
- Batch insert for high-volume periods
|
||
- IP-based rate limiting to prevent spam
|
||
|
||
#### Database Optimization
|
||
- Proper indexing on PageView model
|
||
- Aggregate tables for trending calculations
|
||
- Periodic cleanup of old PageView records
|
||
|
||
## Implementation Plan
|
||
|
||
The implementation follows the todo list with these key phases:
|
||
|
||
1. **Database Layer**: PageView model and migrations
|
||
2. **Algorithm Design**: Trending calculation logic
|
||
3. **API Layer**: New endpoints and serializers
|
||
4. **Tracking System**: Middleware for view capture
|
||
5. **Caching Layer**: Performance optimization
|
||
6. **Automation**: Management commands and scheduling
|
||
7. **Frontend Integration**: Replace mock data
|
||
8. **Testing & Monitoring**: Comprehensive coverage
|
||
|
||
## Security & Privacy
|
||
|
||
- Anonymous view tracking (no personal data)
|
||
- Session-based rate limiting
|
||
- User agent validation
|
||
- IP address anonymization options
|
||
|
||
## Monitoring & Analytics
|
||
|
||
- View tracking success rates
|
||
- Trending calculation performance
|
||
- Cache hit/miss ratios
|
||
- API response times
|
||
- Algorithm effectiveness metrics |