Rating & Voting System
Relevant source files
The following files were used as context for generating this wiki page:
- app/Livewire/Voting/RatingVoting.php
- app/Actions/Rating/VoteRatingOptionAction.php
- app/Support/Rating/RatingVoteDistribution.php
- app/Models/RatingVote.php
- app/Filament/Resources/RatingGroups/RelationManagers/OptionsRelationManager.php
- database/seeders/DemoFillSeeder.php
- tests/Feature/Database/RatingVotesTableTest.php
The Rating & Voting System in RateGuru is a configurable architecture designed to facilitate community-driven feedback on posted content. It allows for multi-dimensional evaluation of posts through rating groups (e.g., "Source", "Category") and their respective options.
The system ensures data integrity by enforcing a strict "one vote per user, post, and group" policy. It supports real-time UI updates using Livewire and provides administrative tools via Filament for managing rating configurations and archiving historical options while preserving vote data.
Sources: tests/Feature/Docs/RatingDocsTest.php:11, tests/Feature/Database/RatingVotesTableTest.php:26-30
System Architecture
The architecture is built on a decoupled structure where business logic is encapsulated in Actions, and the UI is handled by specialized Livewire components.
Core Data Models
The system relies on three primary entities to manage the voting lifecycle:
| Entity | Description |
|---|---|
| RatingGroup | Defines a category or question for voting (e.g., "Origin"). |
| RatingOption | Specific choices within a group (e.g., "Homemade", "Restaurant"). |
| RatingVote | The record of a specific user's choice for a post within a group. |
Sources: app/Models/RatingVote.php, database/seeders/DemoFillSeeder.php:300-305
Data Flow for a Voting Action
When a user submits a vote, the system follows a specific sequence of validation and persistence:
The VoteRatingOptionAction handles the replacement of previous votes if a user changes their mind within the same rating group, ensuring no duplicate entries exist for the same user, post, and group combination.
Sources: app/Livewire/Voting/RatingVoting.php:50-80, app/Actions/Rating/VoteRatingOptionAction.php:15-30
Functional Components
1. Voting Execution (Actions)
The VoteRatingOptionAction is the central service for recording votes. It performs several critical checks:
- Ownership Check: Users cannot vote on their own posts.
- Status Check: Votes are only allowed on published posts and active rating groups/options.
- Rate Limiting: Prevents abuse by limiting the frequency of voting actions.
- Idempotency: Replaces existing votes for the same group instead of creating new records.
Sources: app/Actions/Rating/VoteRatingOptionAction.php:35-80, tests/Feature/Actions/VoteRatingOptionActionTest.php:30-45
2. Livewire Integration
Voting is exposed to users via the RatingVoting component. This component is reactive and listens for the rating-voted event to stay in sync across different parts of the UI (e.g., the Feed Card and the Post Drawer).
3. Distribution & Metrics
The RatingVoteDistribution service calculates the percentages and counts for each option within a group for a specific post. It supports:
- Active Options: Current selectable items.
- Archived Options: Historically voted items that are no longer selectable but are included in the distribution results to maintain historical accuracy.
Sources: app/Support/Rating/RatingVoteDistribution.php:15-40, tests/Feature/Support/Rating/RatingVoteDistributionTest.php:35-45
Database Schema & Constraints
The rating_votes table uses a unique composite index to enforce business rules at the database level.
| Column | Type | Constraints |
|---|---|---|
id | BigInt | Primary Key |
post_id | Foreign Key | Indexed; Cascade on Delete |
user_id | Foreign Key | Indexed |
rating_group_id | Foreign Key | Part of Unique Index |
rating_option_id | Foreign Key | Indexed |
Unique Constraint: rating_votes_user_id_post_id_rating_group_id_unique
Sources: tests/Feature/Database/RatingVotesTableTest.php:10-25, tests/Feature/Database/RatingVotesTableTest.php:52-58
Administrative Management
Administrators manage the voting system through the Filament-based OptionsRelationManager. This interface allows for:
- Validation: Ensuring the number of active options stays within the defined
min_optionsandmax_optionsfor a group. - Soft Deletion (Archiving): If an option has existing votes, it cannot be deleted. Instead, it must be archived, which sets
is_activetofalseand records thearchived_attimestamp.
Sources: app/Filament/Resources/RatingGroups/RelationManagers/OptionsRelationManager.php:130-180, tests/Feature/Filament/RatingOptionRelationManagerTest.php:125-145
Conclusion
The Rating & Voting System provides a robust and flexible framework for gathering structured community feedback. By leveraging a combination of database constraints, dedicated action classes, and reactive Livewire components, the system maintains high data integrity while offering a seamless user experience. Its configurable nature allows administrators to evolve the rating criteria without losing historical data.