Developer Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides a technical overview of the PriceBuddy application, intended for developers who wish to contribute to the project or set up their own development environment. It covers the project's architecture, technology stack, setup procedures, and coding standards.
PriceBuddy is a self-hostable web application for comparing product prices from various online retailers. It is built on the Laravel framework and utilizes Filament for its admin panel. The application is designed to be deployed using Docker, and the recommended development environment is managed by Lando.
Sources: README.md:3-7, README.md:73-75
1. Technology Stack
The project uses a modern PHP and JavaScript stack.
1.1. Backend
The backend is built with PHP and the Laravel framework. Key dependencies are managed via Composer.
- PHP Version:
^8.4 - Framework: Laravel
^11.31 - Admin Panel: Filament
^3.2 - Web Scraping:
jez500/web-scraper-for-laravel^1.0.6 - Notifications:
laravel-notification-channels/pushover^4.0
Sources: composer.json:9-23
1.2. Frontend
The frontend is built using Vite and utilizes Tailwind CSS for styling.
- Build Tool: Vite
^6.0 - CSS Framework: Tailwind CSS
^3.4.17 - CSS Preprocessor: Sass
^1.83.3 - JavaScript Libraries: Chart.js
^4.4.7
Sources: package.json:8-20, resources/views/welcome.blade.php:11-13
1.3. Key PHP Dependencies
The following table lists the main PHP packages required by the application.
| Package | Version | Description |
|---|---|---|
laravel/framework | ^11.31 | The core Laravel framework. |
filament/filament | ^3.2 | The TALL stack admin panel for Laravel. |
jez500/web-scraper-for-laravel | ^1.0.6 | Used for fetching product information from store pages. |
laravel-notification-channels/pushover | ^4.0 | Enables sending Pushover notifications. |
moneyphp/money | ^3.3 | PHP library for handling monetary values. |
spatie/laravel-sluggable | ^3.7 | Generates slugs for Eloquent models. |
Sources: composer.json:9-23
1.4. Key Frontend Dependencies
The following table lists the main Node.js packages used for frontend development.
| Package | Version | Description |
|---|---|---|
vite | ^6.0 | Next-generation frontend tooling. |
tailwindcss | ^3.4.17 | A utility-first CSS framework. |
sass | ^1.83.3 | CSS preprocessor. |
chart.js | ^4.4.7 | Used for visualizing product price history. |
laravel-vite-plugin | ^1.0 | Laravel integration for Vite. |
Sources: package.json:8-20
2. Development Environment
The recommended development environment uses Lando, which simplifies the setup process by managing the necessary services in Docker containers.
2.1. Lando Setup Flow
The following diagram illustrates the steps to start the development environment.
This flow is the standard procedure for getting the local development server running.
Sources: README.md:76-78
2.2. Composer Scripts
Several scripts are defined in composer.json to aid in development.
| Script | Description |
|---|---|
post-autoload-dump | Runs after composer install or update. Discovers packages and upgrades Filament. |
post-update-cmd | Publishes Laravel's assets after an update. |
post-create-project-cmd | Sets up the .env file, creates the database, and runs migrations on initial project creation. |
dev | Starts a concurrent development server, queue listener, log tailer, and Vite dev server. |
Sources: composer.json:48-69
3. Code Quality & Standards
The project enforces code quality through a set of standardized tools.
- Coding Standards: Enforced by Laravel Pint. Configuration can be found in
pint.json. - Static Analysis: Performed by PHPStan. Configuration is located in
phpstan.neon. - Testing: Handled by PHPUnit.
Sources: README.md:80-84
4. Containerization with Docker
The application is designed for easy deployment using Docker and Docker Compose. The primary Dockerfile for the PHP environment is docker/php.dockerfile.
4.1. Docker Build Process
The docker/php.dockerfile uses a multi-stage build to create a lean production image.
The diagram below shows the stages of the Docker build.
This multi-stage process first builds all dependencies and frontend assets in a builder image, then copies only the necessary artifacts to a smaller, cleaner final image.
Sources: docker/php.dockerfile
4.2. Background Tasks
The Docker container includes a cron job that handles background tasks like fetching prices and sending notifications. This is configured via /etc/cron.d/schedule-cron and started by the /start-cron.sh script, which is managed by supervisord.
Sources: README.md:63-65, docker/php.dockerfile:20-22
5. Licensing
The project is licensed under a modified GPL-3.0 license. A key restriction is that the software cannot be used for commercial purposes. This includes, but is not limited to:
- Selling access to a hosted solution.
- Distributing executable files for sale.
- Incorporating the software into a commercial product or service.
Developers contributing to or using this software should be aware of these commercial use restrictions.
Sources: LICENSE.md:31-45