# beterxie/ai_price_radar architecture

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

- Interactive diagram: https://gitdiagram.com/beterxie/ai_price_radar
- Repository: https://github.com/beterxie/ai_price_radar

## Overview

AI Price Memory aggregates public AI-subscription offers into a verified, comparable catalog and exposes it through a website and read-only feeds. Its main workflow is discovery and scanning, validation and publication, then API-backed browsing and comparison. The graph also includes account/notification, merchant-intake, and auxiliary catalog capabilities documented in the README. Source excerpts confirm API startup and snapshot-route fallback behavior; some subsystem links reflect README documentation rather than sampled implementation.

Main entry points: [`apps/api/app/database.py`](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/database.py) (Catalog database), [`apps/web/app`](https://github.com/beterxie/ai_price_radar/tree/main/apps/web/app) (Price comparison site), [`crawler/ldxp/ldxp_crawler`](https://github.com/beterxie/ai_price_radar/tree/main/crawler/ldxp/ldxp_crawler) (Discovery and scanner), [`pipeline/publish_catalog.py`](https://github.com/beterxie/ai_price_radar/blob/main/pipeline/publish_catalog.py) (Catalog sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Source collection"]
  node_crawler["Discovery and scanner"]
  node_sqlite[("Crawler database<br/>[db.py]")]
  node_detector["Source qualification<br/>[worker.py]"]
end

subgraph group_publication["Catalog publication"]
  node_pipeline["Catalog sync<br/>[publish_catalog.py]"]
  node_connectors["Merchant connectors"]
  node_postgres[("Catalog database<br/>[database.py]")]
  node_classifier["Classification and pricing<br/>[classifier.py]"]
end

subgraph group_serving["API and website"]
  node_api["FastAPI application<br/>[main.py]"]
  node_catalog_api["Catalog and feed routes<br/>[public.py]"]
  node_web["Price comparison site"]
  node_web_api["Web API client<br/>[api.ts]"]
  node_snapshot["Snapshot endpoints<br/>[route.ts]"]
end

subgraph group_engagement["User and merchant features"]
  node_account["Accounts and watchlists<br/>[user.py]"]
  node_notifications["Notification services"]
  node_bots["Bot integrations"]
  node_intake["Merchant intake<br/>[source_intake.py]"]
  node_admin["Review and administration<br/>[admin.py]"]
end

subgraph group_extensions["Catalog extensions"]
  node_guides["Buying guides"]
  node_skills["Community skills"]
  node_promotions["Ads and relay directory<br/>[public.py]"]
end

node_index(("Public indexes"))
node_merchant(("Public shops"))
node_shopper(("Price researchers"))
node_agents(("Feed consumers"))

node_index -->|"seed discovery"| node_crawler
node_merchant -->|"scan public offers"| node_crawler
node_crawler -->|"store scan results"| node_sqlite
node_detector -->|"submit qualification"| node_api
node_crawler -->|"provide crawler data"| node_pipeline
node_connectors -->|"supply merchant feeds"| node_pipeline
node_pipeline -->|"read scan data"| node_sqlite
node_pipeline -->|"publish catalog"| node_postgres
node_classifier -->|"classify and update"| node_postgres
node_api -->|"mount routes"| node_catalog_api
node_catalog_api -->|"read catalog"| node_postgres
node_web -->|"request catalog data"| node_web_api
node_web_api -->|"call API"| node_api
node_shopper -->|"browse and compare"| node_web
node_agents -->|"fetch snapshots"| node_snapshot
node_snapshot -.->|"fallback fetch"| node_api
node_account -->|"read and update accounts"| node_postgres
node_notifications -->|"read subscriptions"| node_postgres
node_notifications -->|"dispatch alerts"| node_bots
node_intake -->|"record submissions"| node_postgres
node_admin -->|"review and manage"| node_postgres
node_web -->|"present guides"| node_guides
node_web -->|"present community skills"| node_skills
node_catalog_api -->|"serve ads and relays"| node_promotions

click node_crawler "https://github.com/beterxie/ai_price_radar/tree/main/crawler/ldxp/ldxp_crawler"
click node_sqlite "https://github.com/beterxie/ai_price_radar/blob/main/crawler/ldxp/ldxp_crawler/db.py"
click node_detector "https://github.com/beterxie/ai_price_radar/blob/main/detector/worker.py"
click node_pipeline "https://github.com/beterxie/ai_price_radar/blob/main/pipeline/publish_catalog.py"
click node_connectors "https://github.com/beterxie/ai_price_radar/tree/main/pipeline/connectors"
click node_postgres "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/database.py"
click node_classifier "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/services/classifier.py"
click node_api "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/main.py"
click node_catalog_api "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/routers/public.py"
click node_web "https://github.com/beterxie/ai_price_radar/tree/main/apps/web/app"
click node_web_api "https://github.com/beterxie/ai_price_radar/blob/main/apps/web/lib/api.ts"
click node_snapshot "https://github.com/beterxie/ai_price_radar/blob/main/apps/web/app/data/latest.json/route.ts"
click node_account "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/routers/user.py"
click node_notifications "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/services/notification_hub.py"
click node_bots "https://github.com/beterxie/ai_price_radar/tree/main/extensions/bots"
click node_intake "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/services/source_intake.py"
click node_admin "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/routers/admin.py"
click node_guides "https://github.com/beterxie/ai_price_radar/tree/main/apps/web/content/guides"
click node_skills "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/services/community_skills.py"
click node_promotions "https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/routers/public.py"

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_crawler,node_sqlite,node_detector toneBlue
class node_pipeline,node_connectors,node_postgres,node_classifier toneAmber
class node_api,node_catalog_api,node_web,node_web_api,node_snapshot toneMint
class node_account,node_notifications,node_bots,node_intake,node_admin toneRose
class node_guides,node_skills,node_promotions,node_index,node_merchant,node_shopper,node_agents toneIndigo
```

## Components

### Source collection

- [Discovery and scanner](https://github.com/beterxie/ai_price_radar/tree/main/crawler/ldxp/ldxp_crawler): `crawler/ldxp/ldxp_crawler`
- [Crawler database](https://github.com/beterxie/ai_price_radar/blob/main/crawler/ldxp/ldxp_crawler/db.py): `crawler/ldxp/ldxp_crawler/db.py`
- [Source qualification](https://github.com/beterxie/ai_price_radar/blob/main/detector/worker.py): `detector/worker.py`

### Catalog publication

- [Catalog sync](https://github.com/beterxie/ai_price_radar/blob/main/pipeline/publish_catalog.py): `pipeline/publish_catalog.py`
- [Merchant connectors](https://github.com/beterxie/ai_price_radar/tree/main/pipeline/connectors): `pipeline/connectors`
- [Catalog database](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/database.py): `apps/api/app/database.py`
- [Classification and pricing](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/services/classifier.py): `apps/api/app/services/classifier.py`

### API and website

- [FastAPI application](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Catalog and feed routes](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/routers/public.py): `apps/api/app/routers/public.py`
- [Price comparison site](https://github.com/beterxie/ai_price_radar/tree/main/apps/web/app): `apps/web/app`
- [Web API client](https://github.com/beterxie/ai_price_radar/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`
- [Snapshot endpoints](https://github.com/beterxie/ai_price_radar/blob/main/apps/web/app/data/latest.json/route.ts): `apps/web/app/data/latest.json/route.ts`

### User and merchant features

- [Accounts and watchlists](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/routers/user.py): `apps/api/app/routers/user.py`
- [Notification services](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/services/notification_hub.py): `apps/api/app/services/notification_hub.py`
- [Bot integrations](https://github.com/beterxie/ai_price_radar/tree/main/extensions/bots): `extensions/bots`
- [Merchant intake](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/services/source_intake.py): `apps/api/app/services/source_intake.py`
- [Review and administration](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/routers/admin.py): `apps/api/app/routers/admin.py`

### Catalog extensions

- [Buying guides](https://github.com/beterxie/ai_price_radar/tree/main/apps/web/content/guides): `apps/web/content/guides`
- [Community skills](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/services/community_skills.py): `apps/api/app/services/community_skills.py`
- [Ads and relay directory](https://github.com/beterxie/ai_price_radar/blob/main/apps/api/app/routers/public.py): `apps/api/app/routers/public.py`

### Other components

- **Public indexes**
- **Public shops**
- **Price researchers**
- **Feed consumers**

## Connections

- Public indexes → Discovery and scanner: seed discovery
- Public shops → Discovery and scanner: scan public offers
- Discovery and scanner → Crawler database: store scan results
- Source qualification → FastAPI application: submit qualification
- Discovery and scanner → Catalog sync: provide crawler data
- Merchant connectors → Catalog sync: supply merchant feeds
- Catalog sync → Crawler database: read scan data
- Catalog sync → Catalog database: publish catalog
- Classification and pricing → Catalog database: classify and update
- FastAPI application → Catalog and feed routes: mount routes
- Catalog and feed routes → Catalog database: read catalog
- Price comparison site → Web API client: request catalog data
- Web API client → FastAPI application: call API
- Price researchers → Price comparison site: browse and compare
- Feed consumers → Snapshot endpoints: fetch snapshots
- Snapshot endpoints → FastAPI application: fallback fetch
- Accounts and watchlists → Catalog database: read and update accounts
- Notification services → Catalog database: read subscriptions
- Notification services → Bot integrations: dispatch alerts
- Merchant intake → Catalog database: record submissions
- Review and administration → Catalog database: review and manage
- Price comparison site → Buying guides: present guides
- Price comparison site → Community skills: present community skills
- Catalog and feed routes → Ads and relay directory: serve ads and relays