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:
pacnpal
2025-08-25 10:46:54 -04:00
parent 937eee19e4
commit dcf890a55c
61 changed files with 10328 additions and 740 deletions

View 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