# heykelh/pokewatch architecture

> Architecture diagram of the GitHub repository heykelh/pokewatch, 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/heykelh/pokewatch
- Repository: https://github.com/heykelh/pokewatch
- Video tour (about a minute): https://gitdiagram.com/heykelh/pokewatch/video

## Overview

PokéWatch is a Pokémon TCG market-surveillance product: its daily workflow collects official price and card-reference data, applies deterministic anomaly rules, and presents documented signals as investigation candidates rather than verdicts. The dashboard also exposes market summaries, pipeline health, methodology, investigations, and a 30th-anniversary card study. README-described SQL and reporting subsystems are represented where the tree supports them; the SQL implementation itself is not present in the supplied tree, so its source path is unknown.

Main entry points: [`web/src/lib/pokewatch.ts`](https://github.com/heykelh/pokewatch/blob/main/web/src/lib/pokewatch.ts) (Dashboard data access), [`scripts/generate_report.py`](https://github.com/heykelh/pokewatch/blob/main/scripts/generate_report.py) (Daily report builder), [`scripts/ingest_priceguide.py`](https://github.com/heykelh/pokewatch/blob/main/scripts/ingest_priceguide.py) (Price ingestion), [`scripts/ingest_tcgdex.py`](https://github.com/heykelh/pokewatch/blob/main/scripts/ingest_tcgdex.py) (Catalog ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and reference data"]
  node_price_ingest["Price ingestion"]
  node_catalog_ingest["Catalog ingestion<br/>[ingest_tcgdex.py]"]
end

subgraph group_analysis["Detection and investigation"]
  node_detection["Deterministic rules"]
  node_investigation["Targeted investigation"]
  node_report_builder["Daily report builder<br/>[generate_report.py]"]
end

subgraph group_storage["Shared data services"]
  node_market_store[("Supabase market data")]
  node_anomaly_data[("Market anomalies")]
end

subgraph group_product["Dashboard and reporting"]
  node_web_data["Dashboard data access<br/>[pokewatch.ts]"]
  node_dashboard["Market dashboard<br/>[page.tsx]"]
  node_anomaly_page["Anomaly view<br/>[page.tsx]"]
  node_investigation_page["Case investigations<br/>[page.tsx]"]
  node_methodology_page["Methodology and limits<br/>[page.tsx]"]
  node_anniversary_page["30th anniversary study<br/>[page.tsx]"]
  node_verdict_widget["Market verdict<br/>[index.tsx]"]
  node_market_widget["Market scan<br/>[index.tsx]"]
  node_pipeline_widget["Pipeline health<br/>[index.tsx]"]
end

node_visitor(("Dashboard visitor"))
node_cardmarket["Cardmarket guide"]
node_tcgdex["TCGdex API"]
node_ebay["eBay Browse API"]
node_groq["Groq LLM"]

node_cardmarket -->|"supplies prices"| node_price_ingest
node_price_ingest -->|"ingests snapshots"| node_market_store
node_tcgdex -->|"supplies catalog"| node_catalog_ingest
node_catalog_ingest -->|"ingests references"| node_market_store
node_market_store -->|"provides history"| node_detection
node_detection -->|"stores signals"| node_anomaly_data
node_market_store -->|"provides evidence"| node_investigation
node_investigation -.->|"queries listings"| node_ebay
node_market_store -->|"provides metrics"| node_report_builder
node_report_builder -.->|"requests prose"| node_groq
node_report_builder -->|"stores report"| node_market_store
node_visitor -->|"views"| node_dashboard
node_dashboard -->|"requests metrics"| node_web_data
node_anomaly_page -->|"requests signals"| node_web_data
node_investigation_page -->|"reads market data"| node_web_data
node_anniversary_page -->|"requests card data"| node_web_data
node_verdict_widget -->|"fetches verdict"| node_web_data
node_market_widget -->|"fetches market"| node_web_data
node_pipeline_widget -->|"fetches health"| node_web_data
node_web_data -->|"reads dashboard data"| node_market_store
node_web_data -->|"reads signals"| node_anomaly_data
node_methodology_page -->|"explains limits"| node_visitor

click node_price_ingest "https://github.com/heykelh/pokewatch/blob/main/scripts/ingest_priceguide.py"
click node_catalog_ingest "https://github.com/heykelh/pokewatch/blob/main/scripts/ingest_tcgdex.py"
click node_investigation "https://github.com/heykelh/pokewatch/blob/main/scripts/ebay_investigate.py"
click node_report_builder "https://github.com/heykelh/pokewatch/blob/main/scripts/generate_report.py"
click node_web_data "https://github.com/heykelh/pokewatch/blob/main/web/src/lib/pokewatch.ts"
click node_dashboard "https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/page.tsx"
click node_anomaly_page "https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/anomalies/page.tsx"
click node_investigation_page "https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/investigations/page.tsx"
click node_methodology_page "https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/methodologie/page.tsx"
click node_anniversary_page "https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/30-ans/page.tsx"
click node_verdict_widget "https://github.com/heykelh/pokewatch/blob/main/web/src/components/chart-blocks/charts/pokewatch-verdict/index.tsx"
click node_market_widget "https://github.com/heykelh/pokewatch/blob/main/web/src/components/chart-blocks/charts/pokewatch-market/index.tsx"
click node_pipeline_widget "https://github.com/heykelh/pokewatch/blob/main/web/src/components/chart-blocks/charts/pokewatch-pipeline/index.tsx"

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_price_ingest,node_catalog_ingest toneBlue
class node_detection,node_investigation,node_report_builder toneAmber
class node_market_store,node_anomaly_data,node_tcgdex,node_ebay toneMint
class node_web_data,node_dashboard,node_anomaly_page,node_investigation_page,node_methodology_page,node_anniversary_page,node_verdict_widget,node_market_widget,node_pipeline_widget toneRose
class node_visitor,node_cardmarket,node_groq toneIndigo
```

## Components

### Collection and reference data

- [Price ingestion](https://github.com/heykelh/pokewatch/blob/main/scripts/ingest_priceguide.py): `scripts/ingest_priceguide.py`
- [Catalog ingestion](https://github.com/heykelh/pokewatch/blob/main/scripts/ingest_tcgdex.py): `scripts/ingest_tcgdex.py`

### Detection and investigation

- **Deterministic rules**
- [Targeted investigation](https://github.com/heykelh/pokewatch/blob/main/scripts/ebay_investigate.py): `scripts/ebay_investigate.py`
- [Daily report builder](https://github.com/heykelh/pokewatch/blob/main/scripts/generate_report.py): `scripts/generate_report.py`

### Shared data services

- **Supabase market data**
- **Market anomalies**

### Dashboard and reporting

- [Dashboard data access](https://github.com/heykelh/pokewatch/blob/main/web/src/lib/pokewatch.ts): `web/src/lib/pokewatch.ts`
- [Market dashboard](https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/page.tsx): `web/src/app/(dashboard)/page.tsx`
- [Anomaly view](https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/anomalies/page.tsx): `web/src/app/(dashboard)/anomalies/page.tsx`
- [Case investigations](https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/investigations/page.tsx): `web/src/app/(dashboard)/investigations/page.tsx`
- [Methodology and limits](https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/methodologie/page.tsx): `web/src/app/(dashboard)/methodologie/page.tsx`
- [30th anniversary study](https://github.com/heykelh/pokewatch/blob/main/web/src/app/(dashboard)/30-ans/page.tsx): `web/src/app/(dashboard)/30-ans/page.tsx`
- [Market verdict](https://github.com/heykelh/pokewatch/blob/main/web/src/components/chart-blocks/charts/pokewatch-verdict/index.tsx): `web/src/components/chart-blocks/charts/pokewatch-verdict/index.tsx`
- [Market scan](https://github.com/heykelh/pokewatch/blob/main/web/src/components/chart-blocks/charts/pokewatch-market/index.tsx): `web/src/components/chart-blocks/charts/pokewatch-market/index.tsx`
- [Pipeline health](https://github.com/heykelh/pokewatch/blob/main/web/src/components/chart-blocks/charts/pokewatch-pipeline/index.tsx): `web/src/components/chart-blocks/charts/pokewatch-pipeline/index.tsx`

### Other components

- **Dashboard visitor**
- **Cardmarket guide**
- **TCGdex API**
- **eBay Browse API**
- **Groq LLM**

## Connections

- Cardmarket guide → Price ingestion: supplies prices
- Price ingestion → Supabase market data: ingests snapshots
- TCGdex API → Catalog ingestion: supplies catalog
- Catalog ingestion → Supabase market data: ingests references
- Supabase market data → Deterministic rules: provides history
- Deterministic rules → Market anomalies: stores signals
- Supabase market data → Targeted investigation: provides evidence
- Targeted investigation → eBay Browse API: queries listings
- Supabase market data → Daily report builder: provides metrics
- Daily report builder → Groq LLM: requests prose
- Daily report builder → Supabase market data: stores report
- Dashboard visitor → Market dashboard: views
- Market dashboard → Dashboard data access: requests metrics
- Anomaly view → Dashboard data access: requests signals
- Case investigations → Dashboard data access: reads market data
- 30th anniversary study → Dashboard data access: requests card data
- Market verdict → Dashboard data access: fetches verdict
- Market scan → Dashboard data access: fetches market
- Pipeline health → Dashboard data access: fetches health
- Dashboard data access → Supabase market data: reads dashboard data
- Dashboard data access → Market anomalies: reads signals
- Methodology and limits → Dashboard visitor: explains limits