Local Setup & Development
Relevant source files
The following files were used as context for generating this wiki page:
RateGuru is a Laravel-based application designed for community-driven ratings. The development environment is optimized for a "SQLite-first" approach, utilizing Livewire and Alpine.js for the frontend and Filament for administrative interfaces. Sources: README.md:3-11, AGENTS.md:6-12
This guide details the procedures for environment initialization, data seeding for development, and the architectural rules that govern the local development workflow.
Initial Environment Setup
The local setup involves cloning the repository, managing PHP and Node.js dependencies, and configuring the local environment file.
Installation Steps
- Dependency Installation: Install PHP dependencies via Composer and frontend assets via NPM.
- Environment Configuration: Create a
.envfile from the provided example and generate a unique application key. - Database Initialization: Create a local SQLite database file and execute migrations.
Sources: README.md:15-33
# Core setup commands
git clone git@github.com:menvil/rateguru.git
composer install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
npm install && npm run build
Sources: README.md:17-33
Architecture Rules
The project follows strict architectural boundaries to maintain code quality:
- Thin Layers: Controllers and Livewire components must remain thin. Business logic resides in
app/Actions, while technical helpers are placed inapp/Services. Sources: AGENTS.md:23-25 - State Management: Alpine.js is reserved for local UI state (modals, drawers), whereas Livewire handles server-side state (forms, voting). Sources: AGENTS.md:37-38
- Image Storage: The system uses a local driver by default (
RATEGURU_IMAGE_DRIVER=local). Sources: AGENTS.md:43-44
Development Tools and UI Kit
For visual consistency, developers must utilize the internal UI Kit. This tool serves as the visual source of truth and ensures all components align with the "PlateRate Reference Composition". Sources: AGENTS.md:31-35
The Dev UI Kit
The UI kit is accessible at /dev/ui-kit but is strictly restricted to local and testing environments. It is automatically disabled in production. Sources: tests/Feature/DevUiKitRouteTest.php:17-21
The kit provides interactive previews for:
- Primitive Components: Buttons, Cards, and Form controls.
- Product Components: Post cards, Vote rails, and Comment panels.
- Overlays: Modals and Drawers for mobile UX testing.
Sources: resources/views/dev/ui-kit.blade.php:14-150
Visual Review Workflow
The following diagram illustrates the workflow for implementing new UI features:
Sources: AGENTS.md:31-34
Data Seeding & Testing
RateGuru uses deterministic seed data to facilitate a consistent development experience across different local environments.
Seeding Strategies
Developers can refresh their local database with demo data using specific commands. The DemoFillSeeder is designed to create a robust dataset including users, posts, and nested comment structures. Sources: tests/Feature/Docs/SeedDataDocsTest.php:10-12, database/seeders/DemoFillSeeder.php:19-25
| Seeder Component | Description | Default Volume |
|---|---|---|
| Users | Active accounts with roles (Admin, Moderator, User). | 500 |
| Posts | Published posts with generated JPG images and truth metadata. | 100 |
| Votes | Post, origin, and cuisine votes (85% participation). | Variable |
| Comments | Nested threads up to 3 levels deep. | 6-12 per post |
Sources: database/seeders/DemoFillSeeder.php:27-35, database/seeders/DemoFillSeeder.php:131-137
Testing (TDD)
The project mandates a Test-Driven Development (TDD) approach. Developers are required to write tests first using Pest or PHPUnit before implementing features. Sources: AGENTS.md:17-21
# Run the test suite
composer test
Sources: README.md:40-42
Workflow & Contribution Rules
The project follows a "GitFlow-lite" strategy for branch management.
Branching and Commits
- Base Branch: All work must start from the
developbranch. Sources: AGENTS.md:14, CONTRIBUTING.md:10 - Naming Convention:
feature/RG-XXX-short-title. Sources: AGENTS.md:15 - Commit Format:
RG-XXX: English commit title. Sources: CONTRIBUTING.md:13
Contribution Process
The lifecycle of a local development task is visualized below:
Sources: AGENTS.md:14-21, CONTRIBUTING.md:10-14
Summary
The local setup for RateGuru is designed for rapid onboarding using SQLite and Laravel's built-in server. By adhering to the strict architectural boundaries and utilizing the Dev UI Kit, developers ensure that the application remains modular and visually consistent with the PlateRate design contract. Testing and deterministic seeding are central to the workflow, ensuring stability across feature branches.