Introduction to RateGuru
Relevant source files
The following files were used as context for generating this wiki page:
RateGuru is a community-driven rating and decision support application built on the Laravel framework. It facilitates structured feedback through posts, comments, and a configurable voting system. The platform is designed to transition from a food-specific domain (PlateRate) toward a generic rating vocabulary, supporting various categories and sources.
The application leverages a modern TALL stack (Tailwind, Alpine.js, Laravel, Livewire) along with Filament for administrative management. It emphasizes a "SQLite-first" development approach and follows strict architectural patterns to keep business logic separated from the user interface.
Sources: README.md:3-10, AGENTS.md:4-8, tests/Feature/Docs/DomainDocsTest.php:19-28
Core Technology Stack
The project utilizes a specific set of tools and technologies to maintain performance and developer productivity.
| Component | Technology | Description |
|---|---|---|
| Backend Framework | Laravel | The primary PHP framework. |
| Frontend Interactivity | Livewire | Handles server-side state like forms, voting, and filtering. |
| Client-side State | Alpine.js | Manages local UI state such as modals, drawers, and previews. |
| Admin Panel | Filament | Provides the moderation and content management interface. |
| Database | SQLite | Primary database for development and initial deployment. |
| CSS Framework | Tailwind CSS | Utility-first styling with a custom design contract (RateGuru tokens). |
| Testing | Pest / PHPUnit | Testing frameworks for TDD and feature verification. |
Sources: README.md:5-13, AGENTS.md:5-11, 41-42
Architectural Principles
RateGuru follows a structured architecture to ensure maintainability and separation of concerns.
Component Logic Distribution
Logic is distributed based on its technical or business nature:
- Thin Controllers/Livewire: Components must remain slim, delegating heavy lifting.
- Actions (
app/Actions): Contain all core business logic. - Services (
app/Services): Reserved for technical helpers. - Policies: Handle all authorization logic.
- Jobs: Manage background tasks.
- Blade Components: Reusable UI elements that must not contain business rules.
Sources: AGENTS.md:23-32
Data Flow and State Management
The application distinguishes between local UI state and persistent server state.
Diagram shows the separation between local UI interactivity (Alpine.js) and persistent data operations (Livewire/Actions).
Sources: AGENTS.md:41-42, 23-25
UI Design & The Reference Composition
RateGuru enforces a visual contract through the "PlateRate Reference Composition." This serves as the visual source of truth for the Phase 1+ product UI.
App Shell Structure
The application layout is structured as a grid-based shell:
- Topbar: Fixed at
60pxheight with a maximum width of1440px. - Sidebar: Fixed width of
240pxcontaining categories, tags, and navigation links. - Feed: The central column for viewing posts and content.
- Detail Column: A fixed right-hand column (approx.
380px-460px) for post details and results.
Sources: tests/Feature/ApplicationShellTest.php:32-55, resources/views/dev/partials/platerate-reference-composition.blade.php:7-17
UI Components
The project maintains a UI Kit located at /dev/ui-kit to document and test reusable components.
| Component Type | Examples | Description |
|---|---|---|
| Primitives | Buttons, Inputs, Textareas | Basic building blocks using RateGuru design tokens. |
| Product Components | Post Card Shell, Vote Rail, Dish Placeholder | Specific abstractions for the rating domain. |
| Overlays | Modals, Drawers, Dropdowns | Managed via Alpine.js for local state. |
| Feedback | Error Messages, Skeletons, Empty States | Visual cues for system status. |
Sources: resources/views/dev/ui-kit.blade.php:15-180
Rating and Domain Logic
The system is evolving from a food-specific application (Dishes, Cuisines) to a generic rating platform (Posts, Categories, Sources).
Configurable Voting System
The voting architecture is designed to be highly configurable via the database:
- Rating Groups: Definitions for a set of voting criteria (e.g., "Source", "Category").
- Rating Options: The specific choices available within a group (e.g., "Homemade", "Restaurant").
- Rating Votes: The actual records of user interaction, restricted to one vote per user, post, and group.
Sources: tests/Feature/Docs/RatingDocsTest.php:3-13, 27-37, lang/en/ui.php:151-157
API Implementation
API development is planned for Phase 40 and beyond. Currently, the routes/api.php file is prepared but endpoints are intentionally not implemented to avoid reusing Livewire/Filament resources as API contracts. The strategy includes:
- Versioned routes (e.g.,
/api/v1). - Public-safe data by default.
- Sanctum for write-endpoint authentication.
Sources: routes/api.php:10-20, tests/Feature/Docs/ApiDocsTest.php:3-20
Development Workflow
RateGuru utilizes a "GitFlow-lite" strategy for managing code changes.
Diagram illustrates the branch transitions and integration flow within the project.
Sources: README.md:46-52, CONTRIBUTING.md:5-11
Definition of Done (DoD)
A task is considered complete only when:
- The specific task scope is respected.
- Tests (written via TDD) pass successfully.
- Code is formatted and no unrelated files are modified.
- UI changes align with the
ui-review-checklist.mdand the PlateRate Reference.
Sources: AGENTS.md:15-21, 51-57