Application Architecture
Relevant source files
The following files were used as context for generating this wiki page:
RateGuru is a community-driven rating and decision support platform built using the TALL stack (Tailwind CSS, Alpine.js, Laravel, and Livewire). The architecture emphasizes a "SQLite-first" approach and a strictly decoupled logic structure where business rules are separated from the presentation layer.
The system is designed to provide a "PlateRate" visual experience, utilizing Filament for administrative management and a robust set of Blade components for the frontend. Development follows a Test-Driven Development (TDD) methodology, ensuring that all features are validated against comprehensive test suites before implementation.
Sources: AGENTS.md:4-10, README.md:1-10, tests/Feature/ApplicationShellTest.php:1-10
Core Technology Stack
The application is built on a modern PHP ecosystem focused on reactive interfaces without a heavy JavaScript framework requirement.
| Layer | Technology | Purpose |
|---|---|---|
| Backend | Laravel 13.x | Core framework and API |
| Frontend (Reactive) | Livewire 4.3 | Server-side reactive components |
| Frontend (Client) | Alpine.js | Local UI state management (modals, drawers) |
| Styling | Tailwind CSS | Utility-first design system and tokens |
| Database | SQLite | Primary data storage (Production/Local) |
| Admin UI | Filament 5.0 | Back-office and project management |
| Testing | Pest / PHPUnit | Feature and Unit testing suite |
Sources: README.md:5-13, composer.json:11-15, AGENTS.md:5-11
Architectural Design Patterns
RateGuru enforces a strict separation of concerns through specific directory structures and logic placement rules.
Logic Distribution
To keep the codebase maintainable, the following rules apply:
- Actions (
app/Actions): All business logic resides here. - Services (
app/Services): Technical helpers and third-party integrations. - Policies: Authorization logic.
- Jobs: Asynchronous or background processing.
- Controllers & Livewire: Must remain "thin," acting only as entry points or state orchestrators.
- Blade Views: Forbidden from containing business logic or direct database queries.
Sources: AGENTS.md:25-32, tests/Feature/ApplicationShellTest.php:57-73
State Management Flow
The architecture distinguishes between server-side state (Livewire) and client-side UI state (Alpine.js).
This diagram shows how user interactions are routed either to Alpine for immediate UI updates or Livewire for server-side persistence.
Sources: AGENTS.md:40-42, config/livewire.php:127-142
Data Domain & Voting System
The core domain has evolved from a food-specific application (Cuisines/Dishes) to a generic rating platform using abstract vocabularies.
Generic Rating Architecture
The system utilizes a flexible schema to handle various rating scenarios:
- Rating Groups: Categorizations for sets of options.
- Rating Options: Specific items users can vote on.
- Rating Votes: Records of user participation (enforcing one vote per user, post, and group).
Sources: tests/Feature/Docs/DomainDocsTest.php:14-25, tests/Feature/Docs/RatingDocsTest.php:3-15
Schema Relationships
The ER diagram illustrates the relationship between users, their voting activity, and the generic post/rating entities.
Sources: tests/Feature/Docs/DomainDocsTest.php:17-23, resources/views/dev/ui-kit.blade.php:215-227
UI & Design System
The UI is governed by a "Design Contract" and visual tokens. A central "PlateRate Reference Composition" serves as the visual source of truth.
Component Architecture
- Primitive Components: Base UI elements like
x-ui.button,x-ui.input, andx-ui.card. - Product Components: Higher-level compositions like
x-feed.post-cardandx-voting.rating-options. - Layouts: The application shell is managed in
layouts.app, with sidebar and header data provided through a composer layer to keep views clean.
Sources: resources/views/dev/ui-kit.blade.php:32-150, tests/Feature/ApplicationShellTest.php:57-73
UI Tokens
The application uses custom Tailwind tokens to maintain consistency with the PlateRate reference:
- Colors:
bg-rg-bg,text-rg-text,bg-rg-topbar,border-rg-border,text-rg-accent. - Layout Constants: Topbar height is fixed at
60px, and the main container has amax-w-[1440px].
Sources: tests/Feature/ApplicationShellTest.php:12-25, tests/Feature/ApplicationShellTest.php:32-43
Deployment & Infrastructure
The project follows a specific deployment strategy focused on SQLite stability and performance.
- Database: SQLite is the primary driver. Migrations must be run with
--forcein production. Fresh migrations (migrate:fresh) are strictly forbidden in production environments. - Storage: Uses standard Laravel symbolic links (
php artisan storage:link). The image driver defaults tolocalunless Cloudinary is specifically implemented. - Queues: Handled via
php artisan queue:work. Note that Redis is explicitly not required for the current queue implementation. - Backups: SQLite databases are backed up using
.backupcommands to a dedicatedbackups/directory, ideally off-server.
Sources: tests/Feature/Docs/DeploymentDocsTest.php:3-15, tests/Feature/Docs/DeploymentDocsTest.php:48-60, tests/Feature/Docs/DeploymentDocsTest.php:110-125, AGENTS.md:46-49
Conclusion
RateGuru’s architecture is a disciplined implementation of the TALL stack, prioritizing logic isolation and a "SQLite-first" infrastructure. By moving from a specialized food domain to a generic rating system, the architecture supports a wide range of community-driven decision-making tools while maintaining a consistent visual identity through its strict design contract and component-based frontend.