# jez500/pricebuddy architecture

> Architecture diagram of the GitHub repository jez500/pricebuddy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jez500/pricebuddy
- Repository: https://github.com/jez500/pricebuddy

## Overview

PriceBuddy is a self-hosted product price tracker. A user adds a product URL in the web app; PriceBuddy scrapes it on a schedule, records price and availability history, compares listings, and sends alerts when configured conditions are met. The graph also preserves product-source search, price insights, configurable scraping, and optional AI-assisted extraction and repair. Edges are limited to relationships stated in the README or visible in the supplied excerpts and SOURCE INDEX; unsampled subsystems are represented without speculative internal links.

Main entry points: [`app/Models/Url.php`](https://github.com/jez500/pricebuddy/blob/main/app/Models/Url.php) (Tracked listings), [`app/Models/Product.php`](https://github.com/jez500/pricebuddy/blob/main/app/Models/Product.php) (Product catalog), [`app/Services/SearchService.php`](https://github.com/jez500/pricebuddy/blob/main/app/Services/SearchService.php) (Product search), [`app/Services/AiConfigHealer.php`](https://github.com/jez500/pricebuddy/blob/main/app/Services/AiConfigHealer.php) (AI strategy repair)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web control room"]
  node_api["REST API"]
end

subgraph group_catalog["Products and stores"]
  node_product[("Product catalog<br/>[Product.php]")]
  node_url[("Tracked listings<br/>[Url.php]")]
  node_store[("Store strategies<br/>[Store.php]")]
  node_product_source[("Search sources<br/>[ProductSource.php]")]
end

subgraph group_acquisition["Search and scraping"]
  node_search["Product search<br/>[SearchService.php]"]
  node_source_search["Source scraper"]
  node_scrape["Page scraper<br/>[ScrapeUrl.php]"]
  node_meta["Metadata extraction"]
  node_ai_healing["AI strategy repair<br/>[AiConfigHealer.php]"]
end

subgraph group_tracking["Tracking and insights"]
  node_price[("Price history<br/>[Price.php]")]
  node_insights["Price insights"]
  node_jobs["Scheduled checks"]
end

subgraph group_integrations["Alerts and integrations"]
  node_notifications["Alert delivery"]
  node_channels["Notification channels<br/>[AppriseChannel.php]"]
end

node_user(("User"))
node_external(("Stores and search"))
node_ai_providers{{"AI providers"}}
node_notification_services{{"Notification services"}}

node_user -->|"tracks products"| node_web
node_user -->|"scripts tracking"| node_api
node_web -->|"manages products"| node_product
node_api -.->|"manages products"| node_product
node_product -->|"tracks listings"| node_url
node_url -->|"resolves store"| node_store
node_url -->|"scrapes page"| node_scrape
node_scrape -->|"fetches page"| node_external
node_jobs -->|"checks listings"| node_url
node_url -->|"records prices"| node_price
node_price -->|"updates price cache"| node_product
node_product -->|"calculates insights"| node_insights
node_product -->|"triggers alerts"| node_notifications
node_notifications -->|"delivers alerts"| node_notification_services
node_channels -.->|"sends notifications"| node_notification_services
node_user -->|"searches products"| node_search
node_search -->|"queries sources"| node_product_source
node_product_source -->|"delegates search"| node_source_search
node_source_search -->|"scrapes results"| node_external
node_search -->|"matches domains"| node_store
node_user -.->|"extracts page data"| node_meta
node_meta -->|"repairs strategy"| node_ai_healing
node_url -->|"heals scrape config"| node_ai_healing
node_ai_healing -.->|"uses provider"| node_ai_providers

click node_web "https://github.com/jez500/pricebuddy/blob/main/app/Filament/Resources/ProductResource.php"
click node_api "https://github.com/jez500/pricebuddy/blob/main/app/Filament/Resources/ProductResource/Api/ProductApiService.php"
click node_product "https://github.com/jez500/pricebuddy/blob/main/app/Models/Product.php"
click node_url "https://github.com/jez500/pricebuddy/blob/main/app/Models/Url.php"
click node_store "https://github.com/jez500/pricebuddy/blob/main/app/Models/Store.php"
click node_product_source "https://github.com/jez500/pricebuddy/blob/main/app/Models/ProductSource.php"
click node_search "https://github.com/jez500/pricebuddy/blob/main/app/Services/SearchService.php"
click node_source_search "https://github.com/jez500/pricebuddy/blob/main/app/Services/ProductSourceSearchService.php"
click node_scrape "https://github.com/jez500/pricebuddy/blob/main/app/Services/ScrapeUrl.php"
click node_meta "https://github.com/jez500/pricebuddy/blob/main/app/Services/MetaExtractionService.php"
click node_ai_healing "https://github.com/jez500/pricebuddy/blob/main/app/Services/AiConfigHealer.php"
click node_price "https://github.com/jez500/pricebuddy/blob/main/app/Models/Price.php"
click node_insights "https://github.com/jez500/pricebuddy/blob/main/app/Services/Insights/ProductInsights.php"
click node_jobs "https://github.com/jez500/pricebuddy/blob/main/app/Jobs/UpdateAllPricesJob.php"
click node_notifications "https://github.com/jez500/pricebuddy/blob/main/app/Notifications/PriceAlertNotification.php"
click node_channels "https://github.com/jez500/pricebuddy/blob/main/app/Notifications/Channels/AppriseChannel.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_api,node_user toneBlue
class node_product,node_url,node_store,node_product_source toneAmber
class node_search,node_source_search,node_scrape,node_meta,node_ai_healing toneMint
class node_price,node_insights,node_jobs toneRose
class node_notifications,node_channels,node_external,node_ai_providers,node_notification_services toneIndigo
```

## Components

### User experience

- [Web control room](https://github.com/jez500/pricebuddy/blob/main/app/Filament/Resources/ProductResource.php): `app/Filament/Resources/ProductResource.php`
- [REST API](https://github.com/jez500/pricebuddy/blob/main/app/Filament/Resources/ProductResource/Api/ProductApiService.php): `app/Filament/Resources/ProductResource/Api/ProductApiService.php`

### Products and stores

- [Product catalog](https://github.com/jez500/pricebuddy/blob/main/app/Models/Product.php): `app/Models/Product.php`
- [Tracked listings](https://github.com/jez500/pricebuddy/blob/main/app/Models/Url.php): `app/Models/Url.php`
- [Store strategies](https://github.com/jez500/pricebuddy/blob/main/app/Models/Store.php): `app/Models/Store.php`
- [Search sources](https://github.com/jez500/pricebuddy/blob/main/app/Models/ProductSource.php): `app/Models/ProductSource.php`

### Search and scraping

- [Product search](https://github.com/jez500/pricebuddy/blob/main/app/Services/SearchService.php): `app/Services/SearchService.php`
- [Source scraper](https://github.com/jez500/pricebuddy/blob/main/app/Services/ProductSourceSearchService.php): `app/Services/ProductSourceSearchService.php`
- [Page scraper](https://github.com/jez500/pricebuddy/blob/main/app/Services/ScrapeUrl.php): `app/Services/ScrapeUrl.php`
- [Metadata extraction](https://github.com/jez500/pricebuddy/blob/main/app/Services/MetaExtractionService.php): `app/Services/MetaExtractionService.php`
- [AI strategy repair](https://github.com/jez500/pricebuddy/blob/main/app/Services/AiConfigHealer.php): `app/Services/AiConfigHealer.php`

### Tracking and insights

- [Price history](https://github.com/jez500/pricebuddy/blob/main/app/Models/Price.php): `app/Models/Price.php`
- [Price insights](https://github.com/jez500/pricebuddy/blob/main/app/Services/Insights/ProductInsights.php): `app/Services/Insights/ProductInsights.php`
- [Scheduled checks](https://github.com/jez500/pricebuddy/blob/main/app/Jobs/UpdateAllPricesJob.php): `app/Jobs/UpdateAllPricesJob.php`

### Alerts and integrations

- [Alert delivery](https://github.com/jez500/pricebuddy/blob/main/app/Notifications/PriceAlertNotification.php): `app/Notifications/PriceAlertNotification.php`
- [Notification channels](https://github.com/jez500/pricebuddy/blob/main/app/Notifications/Channels/AppriseChannel.php): `app/Notifications/Channels/AppriseChannel.php`

### Other components

- **User**
- **Stores and search**
- **AI providers**
- **Notification services**

## Connections

- User → Web control room: tracks products (evidence: `README.md`)
- User → REST API: scripts tracking (evidence: `README.md`)
- Web control room → Product catalog: manages products (evidence: `README.md`)
- REST API → Product catalog: manages products
- Product catalog → Tracked listings: tracks listings (evidence: `README.md`)
- Tracked listings → Store strategies: resolves store (evidence: `app/Models/Url.php`)
- Tracked listings → Page scraper: scrapes page (evidence: `app/Models/Url.php`)
- Page scraper → Stores and search: fetches page (evidence: `README.md`)
- Scheduled checks → Tracked listings: checks listings (evidence: `README.md`)
- Tracked listings → Price history: records prices (evidence: `README.md`)
- Price history → Product catalog: updates price cache (evidence: `app/Models/Price.php`)
- Product catalog → Price insights: calculates insights (evidence: `app/Models/Product.php`)
- Product catalog → Alert delivery: triggers alerts (evidence: `README.md`)
- Alert delivery → Notification services: delivers alerts (evidence: `README.md`)
- Notification channels → Notification services: sends notifications
- User → Product search: searches products (evidence: `README.md`)
- Product search → Search sources: queries sources (evidence: `app/Services/SearchService.php`)
- Search sources → Source scraper: delegates search (evidence: `app/Models/ProductSource.php`)
- Source scraper → Stores and search: scrapes results (evidence: `app/Services/ProductSourceSearchService.php`)
- Product search → Store strategies: matches domains (evidence: `app/Services/SearchService.php`)
- User → Metadata extraction: extracts page data
- Metadata extraction → AI strategy repair: repairs strategy (evidence: `app/Services/MetaExtractionService.php`)
- Tracked listings → AI strategy repair: heals scrape config (evidence: `app/Models/Url.php`)
- AI strategy repair → AI providers: uses provider
