mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 06:31:09 -05:00
feat: Implement Entity Suggestion Manager and Modal components
- 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.
This commit is contained in:
140
docs/trending-system-architecture.md
Normal file
140
docs/trending-system-architecture.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user