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.

backend/apps/rides/models/__init__.py

@@ -8,9 +8,10 @@ The Company model is aliased as Manufacturer to clarify its role as ride manufac
 while maintaining backward compatibility through the Company alias.
 """
 
-from .rides import Ride, RideModel, RollerCoasterStats, Categories
+from .rides import Ride, RideModel, RollerCoasterStats, Categories, CATEGORY_CHOICES
 from .location import RideLocation
 from .reviews import RideReview
+from .rankings import RideRanking, RidePairComparison, RankingSnapshot
 
 __all__ = [
     # Primary models
@@ -19,6 +20,10 @@ __all__ = [
     "RollerCoasterStats",
     "RideLocation",
     "RideReview",
+    # Rankings
+    "RideRanking",
+    "RidePairComparison",
+    "RankingSnapshot",
     # Shared constants
     "Categories",
 ]

backend/apps/rides/models/rankings.py

@@ -0,0 +1,212 @@
+"""
+Models for ride ranking system using Internet Roller Coaster Poll algorithm.
+
+This system calculates rankings based on pairwise comparisons between rides,
+where each ride is compared to every other ride to determine which one
+more riders preferred.
+"""
+
+from django.db import models
+from django.utils import timezone
+from django.core.validators import MinValueValidator, MaxValueValidator
+import pghistory
+
+
+@pghistory.track()
+class RideRanking(models.Model):
+    """
+    Stores calculated rankings for rides using the Internet Roller Coaster Poll algorithm.
+
+    Rankings are recalculated daily based on user reviews/ratings.
+    Each ride's rank is determined by its winning percentage in pairwise comparisons.
+    """
+
+    ride = models.OneToOneField(
+        "rides.Ride", on_delete=models.CASCADE, related_name="ranking"
+    )
+
+    # Core ranking metrics
+    rank = models.PositiveIntegerField(
+        db_index=True, help_text="Overall rank position (1 = best)"
+    )
+    wins = models.PositiveIntegerField(
+        default=0, help_text="Number of rides this ride beats in pairwise comparisons"
+    )
+    losses = models.PositiveIntegerField(
+        default=0,
+        help_text="Number of rides that beat this ride in pairwise comparisons",
+    )
+    ties = models.PositiveIntegerField(
+        default=0,
+        help_text="Number of rides with equal preference in pairwise comparisons",
+    )
+    winning_percentage = models.DecimalField(
+        max_digits=5,
+        decimal_places=4,
+        validators=[MinValueValidator(0), MaxValueValidator(1)],
+        db_index=True,
+        help_text="Win percentage where ties count as 0.5",
+    )
+
+    # Additional metrics
+    mutual_riders_count = models.PositiveIntegerField(
+        default=0, help_text="Total number of users who have rated this ride"
+    )
+    comparison_count = models.PositiveIntegerField(
+        default=0, help_text="Number of other rides this was compared against"
+    )
+    average_rating = models.DecimalField(
+        max_digits=3,
+        decimal_places=2,
+        null=True,
+        blank=True,
+        validators=[MinValueValidator(1), MaxValueValidator(10)],
+        help_text="Average rating from all users who have rated this ride",
+    )
+
+    # Metadata
+    last_calculated = models.DateTimeField(
+        default=timezone.now, help_text="When this ranking was last calculated"
+    )
+    calculation_version = models.CharField(
+        max_length=10, default="1.0", help_text="Algorithm version used for calculation"
+    )
+
+    class Meta:
+        ordering = ["rank"]
+        indexes = [
+            models.Index(fields=["rank"]),
+            models.Index(fields=["winning_percentage", "-mutual_riders_count"]),
+            models.Index(fields=["ride", "last_calculated"]),
+        ]
+        constraints = [
+            models.CheckConstraint(
+                name="rideranking_winning_percentage_range",
+                check=models.Q(winning_percentage__gte=0)
+                & models.Q(winning_percentage__lte=1),
+                violation_error_message="Winning percentage must be between 0 and 1",
+            ),
+            models.CheckConstraint(
+                name="rideranking_average_rating_range",
+                check=models.Q(average_rating__isnull=True)
+                | (models.Q(average_rating__gte=1) & models.Q(average_rating__lte=10)),
+                violation_error_message="Average rating must be between 1 and 10",
+            ),
+        ]
+
+    def __str__(self):
+        return f"#{self.rank} - {self.ride.name} ({self.winning_percentage:.1%})"
+
+    @property
+    def total_comparisons(self):
+        """Total number of pairwise comparisons (wins + losses + ties)."""
+        return self.wins + self.losses + self.ties
+
+
+@pghistory.track()
+class RidePairComparison(models.Model):
+    """
+    Caches pairwise comparison results between two rides.
+
+    This model stores the results of comparing two rides based on mutual riders
+    (users who have rated both rides). It's used to speed up ranking calculations.
+    """
+
+    ride_a = models.ForeignKey(
+        "rides.Ride", on_delete=models.CASCADE, related_name="comparisons_as_a"
+    )
+    ride_b = models.ForeignKey(
+        "rides.Ride", on_delete=models.CASCADE, related_name="comparisons_as_b"
+    )
+
+    # Comparison results
+    ride_a_wins = models.PositiveIntegerField(
+        default=0, help_text="Number of mutual riders who rated ride_a higher"
+    )
+    ride_b_wins = models.PositiveIntegerField(
+        default=0, help_text="Number of mutual riders who rated ride_b higher"
+    )
+    ties = models.PositiveIntegerField(
+        default=0, help_text="Number of mutual riders who rated both rides equally"
+    )
+
+    # Metrics
+    mutual_riders_count = models.PositiveIntegerField(
+        default=0, help_text="Total number of users who have rated both rides"
+    )
+    ride_a_avg_rating = models.DecimalField(
+        max_digits=3,
+        decimal_places=2,
+        null=True,
+        blank=True,
+        help_text="Average rating of ride_a from mutual riders",
+    )
+    ride_b_avg_rating = models.DecimalField(
+        max_digits=3,
+        decimal_places=2,
+        null=True,
+        blank=True,
+        help_text="Average rating of ride_b from mutual riders",
+    )
+
+    # Metadata
+    last_calculated = models.DateTimeField(
+        auto_now=True, help_text="When this comparison was last calculated"
+    )
+
+    class Meta:
+        unique_together = [["ride_a", "ride_b"]]
+        indexes = [
+            models.Index(fields=["ride_a", "ride_b"]),
+            models.Index(fields=["last_calculated"]),
+        ]
+
+    def __str__(self):
+        winner = "TIE"
+        if self.ride_a_wins > self.ride_b_wins:
+            winner = self.ride_a.name
+        elif self.ride_b_wins > self.ride_a_wins:
+            winner = self.ride_b.name
+        return f"{self.ride_a.name} vs {self.ride_b.name} - Winner: {winner}"
+
+    @property
+    def winner(self):
+        """Returns the winning ride or None for a tie."""
+        if self.ride_a_wins > self.ride_b_wins:
+            return self.ride_a
+        elif self.ride_b_wins > self.ride_a_wins:
+            return self.ride_b
+        return None
+
+    @property
+    def is_tie(self):
+        """Returns True if the comparison resulted in a tie."""
+        return self.ride_a_wins == self.ride_b_wins
+
+
+class RankingSnapshot(models.Model):
+    """
+    Stores historical snapshots of rankings for tracking changes over time.
+
+    This allows us to show ranking trends and movements.
+    """
+
+    ride = models.ForeignKey(
+        "rides.Ride", on_delete=models.CASCADE, related_name="ranking_history"
+    )
+    rank = models.PositiveIntegerField()
+    winning_percentage = models.DecimalField(max_digits=5, decimal_places=4)
+    snapshot_date = models.DateField(
+        db_index=True, help_text="Date when this ranking snapshot was taken"
+    )
+
+    class Meta:
+        unique_together = [["ride", "snapshot_date"]]
+        ordering = ["-snapshot_date", "rank"]
+        indexes = [
+            models.Index(fields=["snapshot_date", "rank"]),
+            models.Index(fields=["ride", "-snapshot_date"]),
+        ]
+
+    def __str__(self):
+        return f"{self.ride.name} - Rank #{self.rank} on {self.snapshot_date}"

backend/apps/rides/models/rides.py

@@ -1,6 +1,7 @@
 from django.db import models
 from django.utils.text import slugify
 from django.contrib.contenttypes.fields import GenericRelation
+from django.db.models import Avg
 from apps.core.models import TrackedModel
 from .company import Company
 import pghistory
@@ -56,7 +57,11 @@ class RideModel(TrackedModel):
 
 @pghistory.track()
 class Ride(TrackedModel):
-    """Model for individual ride installations at parks"""
+    """Model for individual ride installations at parks
+
+    Note: The average_rating field is denormalized and refreshed by background
+    jobs. Use selectors or annotations for real-time calculations if needed.
+    """
 
     STATUS_CHOICES = [
         ("", "Select status"),