Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• composer.json
• docker/php.dockerfile
• docker/php/start-app.sh
• app/Providers/Filament/AdminPanelProvider.php
• app/Filament/Pages/AppSettingsPage.php
• config/app.php
• app/Filament/Resources/UserResource.php

PriceBuddy is an open-source, self-hostable web application designed for comparing product prices from various online retailers. The application is built upon the Laravel framework, providing a robust backend structure, and utilizes Filament for a comprehensive and user-friendly admin panel. The entire application is designed to be run within a containerized environment using Docker, simplifying installation and ensuring consistency across different systems.

The architecture is centered around a standard PHP-based web application stack. It includes components for web scraping, data management, user administration, and notifications. Background tasks, such as fetching prices, are handled by a cron job integrated into the Docker container. This document provides a high-level overview of the system's architecture, key components, and core dependencies.

Sources: README.md, composer.json, docker/php.dockerfile

Core Technology Stack

The application is built with PHP and the Laravel framework. The user interface and administrative functions are powered by Filament. Key dependencies are managed via Composer.

Sources: composer.json, README.md

Key Dependencies

The following table lists the primary frameworks and libraries that form the foundation of PriceBuddy.

Library	Description
laravel/framework	The core PHP web application framework.
filament/filament	A TALL stack admin panel for Laravel, used for the entire UI.
jez500/web-scraper-for-laravel	A library used for scraping product information from web pages.
laravel-notification-channels/pushover	A Laravel notification channel for sending Pushover notifications.
spatie/laravel-sluggable	Generates slugs for Eloquent models.
spatie/laravel-settings-plugin	A Filament plugin for managing application settings.
yoeriboven/laravel-log-db	A package to store Laravel logs in the database.
larastan/larastan	Static analysis tool for PHP, used in development.
pestphp/pest	A testing framework for PHP.

Sources: composer.json:10-41

Application Flow

The diagram below illustrates the high-level interaction between the user, the application, and its underlying services.

Sources: docker/php.dockerfile, docker/php/start-app.sh

Containerization with Docker

PriceBuddy is designed to be deployed using Docker, which simplifies the setup and management of its dependencies. The Docker environment is defined across multiple files, primarily docker/base.dockerfile and docker/php.dockerfile.

Sources: README.md:43-47, docker/php.dockerfile

Docker Build Process

The main Docker image is built in multiple stages to optimize the final image size and separate build-time dependencies from runtime dependencies.

Sources: docker/php.dockerfile:3-39

Application Startup

When the container starts, it executes the start-app.sh script. This script is responsible for initializing the application environment.

The startup sequence is as follows:

1. Environment Setup: Checks for a .env file. If it doesn't exist, it copies .env.example and generates an application key.
2. Storage Initialization: Creates necessary directories within the storage folder and sets permissions.
3. Database Connection: Waits for the database service to become available.
4. Database Initialization: Runs migrations and seeds the database using the custom buddy:init-db Artisan command.
5. Cache Warming: Clears and rebuilds application caches (config, routes, events, icons).
6. Supervisor Start: Starts supervisord, which manages both the Apache web server and the cron service for background tasks.

Sources: docker/php/start-app.sh:3-37, docker/php.dockerfile:23-24

Backend (Laravel)

The core of the application is built on the Laravel 11 framework. It follows standard Laravel conventions for routing, models, and controllers.

Sources: composer.json:16

Configuration

Application configuration is managed through environment variables and configuration files located in the config/ directory.

File	Purpose
config/app.php	Contains fundamental application settings like name, environment, debug mode, URL, and timezone.
.env	Stores environment-specific variables such as database credentials and application keys.

Key configuration values from config/app.php:

• name: APP_NAME (default: 'PriceBuddy')
• env: APP_ENV (default: 'production')
• debug: APP_DEBUG (default: false)
• url: APP_URL (default: 'http://localhost')
• timezone: APP_TIMEZONE (default: 'UTC')
• locale: APP_LOCALE (default: 'en')

Sources: config/app.php:13-68, docker/php/start-app.sh:4-6

Background Tasks

Background tasks, such as fetching product prices and sending notifications, are managed by a cron job. The schedule-cron file is copied into the Docker container to run the Laravel scheduler every minute. supervisord is configured to run the cron service.

Sources: README.md:58-59, docker/php.dockerfile:22, 24

Frontend & Admin Panel (Filament)

The entire user interface is built using Filament, a TALL stack (Tailwind CSS, Alpine.js, Laravel, Livewire) admin panel for Laravel. This provides a reactive and modern interface for managing all aspects of the application.

Sources: README.md:65-67, composer.json:14

Admin Panel Provider

The main configuration for the admin panel is located in app/Providers/Filament/AdminPanelProvider.php. This file defines the panel's identity, navigation, and middleware.

// app/Providers/Filament/AdminPanelProvider.php:15-39
public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->path('/')
        ->login()
        ->passwordReset()
        ->colors([
            'primary' => Color::Amber,
        ])
        ->discoverResources(in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources')
        ->discoverPages(in: app_path('Filament/Pages'), for: 'App\\Filament\\Pages')
        ->pages([
            HomeDashboard::class,
        ])
        ->discoverWidgets(in: app_path('Filament/Widgets'), for: 'App\\Filament\\Widgets')
        ->widgets([
            // ...
        ])
        ->middleware([
            // ...
        ])
        ->tenantMiddleware([
            // ...
        ], isPersistent: true);
}

Sources: app/Providers/Filament/AdminPanelProvider.php:15-39

UI Components

The UI is composed of several Filament components, including Pages, Resources, and Widgets.

Sources: app/Providers/Filament/AdminPanelProvider.php:24-29, app/Filament/Pages/HomeDashboard.php, app/Filament/Pages/AppSettingsPage.php, app/Filament/Resources/UserResource.php, app/Filament/Resources/TagResource.php, resources/views/filament/widgets/no-products-found.blade.php

Settings Management

Application settings are managed through the AppSettingsPage, which uses the spatie/laravel-settings-plugin. This page provides forms for configuring scraping, locale, logging, notifications (Email, Pushover, Gotify, Apprise), and integrations like SearXng.

Sources: app/Filament/Pages/AppSettingsPage.php:17, 28-100

User Management

User administration is handled by the UserResource. It provides forms for creating and editing users, including their account details and personal notification settings.

Sources: app/Filament/Resources/UserResource.php:17, 39-61