Image Storage & Processing

Relevant source files

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

• app/Services/Images/ImageStorage.php
• app/Services/Images/CloudinaryImageStorage.php
• app/Services/Images/LocalImageStorage.php
• app/Services/Images/ImageCleanup.php
• AGENTS.md
• database/seeders/DemoFillSeeder.php
• resources/views/livewire/feed/upload-post-form.blade.php

RateGuru provides a flexible image storage and processing system designed to handle user-generated content, specifically for dish and post imagery. The system supports multiple storage drivers, including local filesystem storage and Cloudinary integration, though development guidelines currently mandate the local driver for standard implementation.

Architecture & Storage Drivers

The architecture follows a service-oriented pattern where an ImageStorage interface defines the contract for storing, retrieving, and deleting images. This allows the application to switch between local storage and cloud providers via environment configuration.

Driver Configuration

Storage behavior is controlled via the RATEGURU_IMAGE_DRIVER environment variable. The default setting is local. Implementation of the Cloudinary driver is restricted until a formal implementation task is initiated.

Driver	Environment Value	Description
Local	local	Stores images in the local filesystem under storage/app/public.
Cloudinary	cloudinary	Intended for remote cloud storage and on-the-fly transformations.

Sources: AGENTS.md:58-61, app/Services/Images/LocalImageStorage.php

Component Relationship

The following diagram illustrates the relationship between the storage interface and its concrete implementations.

The system abstracts the underlying storage mechanism from the rest of the application.
Sources: app/Services/Images/ImageStorage.php, app/Services/Images/LocalImageStorage.php, app/Services/Images/CloudinaryImageStorage.php

Upload Flow & Processing

Image uploads are primarily handled through Livewire components. The system supports two primary methods for adding images to posts: direct file uploads and URL-based imports.

File Upload Process

1. Selection: Users select a file via a dropzone or file browser in the upload-post-form.
2. Preview: Alpine.js generates a local data URL using FileReader to show an immediate preview before the server-side upload.
3. Storage: Upon form submission, the ImageStorage service persists the file. For local storage, files are organized by user ID (e.g., posts/{user_id}/filename.jpg).

URL Import Process

When the allow_url_imports feature flag is enabled, users can provide a direct link to an image. The system validates the URL and displays a preview. The actual persistence of the remote image is handled during the post creation logic.

The upload flow utilizes Alpine.js for client-side state and Livewire for server-side persistence.
Sources: resources/views/livewire/feed/upload-post-form.blade.php:79-136, database/seeders/DemoFillSeeder.php:181-190

Synthetic Image Generation

For development and testing environments, the DemoFillSeeder includes a custom image processing engine using the PHP GD library. This engine generates deterministic, procedurally generated "post images" in five distinct visual styles to simulate real user content without requiring external assets.

Style ID	Name	Implementation Detail
0	Diagonal	Column-based diagonal gradient with a white top-right glow.
1	Radial	Concentric ellipses with a central bright spot.
2	Stripes	Horizontal stripes with a diagonal shimmer bar highlight.
3	Grid	Mosaic grid of rectangles with alternating color flips.
4	Waves	Banded sine-wave polygons with a shimmer line.

Every generated image is finalized with a vignette effect to improve visual depth.
Sources: database/seeders/DemoFillSeeder.php:200-344

// Example of procedural generation style selection
match ($style) {
    0 => $this->drawDiagonal($im, $w, $h, $r1, $g1, $b1, $r2, $g2, $b2),
    1 => $this->drawRadial($im, $w, $h, $r1, $g1, $b1, $r2, $g2, $b2),
    2 => $this->drawStripes($im, $w, $h, $r1, $g1, $b1, $r2, $g2, $b2),
    3 => $this->drawGrid($im, $w, $h, $r1, $g1, $b1, $r2, $g2, $b2),
    4 => $this->drawWaves($im, $w, $h, $r1, $g1, $b1, $r2, $g2, $b2),
};

Sources: database/seeders/DemoFillSeeder.php:210-216

Maintenance & Cleanup

The ImageCleanup service is responsible for managing storage health. Its primary role is to identify and remove orphaned image files that are no longer associated with active Post records. This prevents local storage from bloating due to deleted posts or failed upload attempts.

Key responsibilities include:

• Scanning the posts/ directory structure.
• Comparing found files against the image_path entries in the posts table.
• Deleting files found on disk but absent from the database.

Sources: app/Services/Images/ImageCleanup.php

Data Model Integration

The Post model tracks image-related data through several fields. While image_path is the primary reference for local files, other fields support future cloud integration and external sourcing.

Field	Type	Description
image_path	String	Relative path in the storage disk (e.g., posts/1/image.jpg).
image_url	String	Full external URL, primarily used for remote imports.
thumbnail_url	String	Path or URL to a processed smaller version of the image.
source_url	String	The original website URL where the image was found (if applicable).

Sources: database/seeders/DemoFillSeeder.php:151-154, resources/views/livewire/feed/upload-post-form.blade.php:212-225

The Image Storage & Processing system ensures that RateGuru can handle high volumes of visual content efficiently, providing clear paths for both local development and production-scale cloud storage.