# wesbos/yard-sale architecture

> Architecture diagram of the GitHub repository wesbos/yard-sale, 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/wesbos/yard-sale
- Repository: https://github.com/wesbos/yard-sale

## Overview

Yard Sale Gold is a camera- and upload-based scanner that identifies and values likely sale items, then saves findings for browsing. The main workflow samples frames in the browser, sends them to the Worker for agent analysis and research, and returns annotated findings to the live feed. Saved inventory, item details, agent activity, and batch processing are additional product branches. The supplied excerpts document the main calls and storage behavior; some UI and batch wiring is described only by the README, so uncertain internal links are omitted.

Main entry points: [`src/App.tsx`](https://github.com/wesbos/yard-sale/blob/main/src/App.tsx) (Scan and live feed), [`worker/index.ts`](https://github.com/wesbos/yard-sale/blob/main/worker/index.ts) (Frame analysis API), [`worker/agent.ts`](https://github.com/wesbos/yard-sale/blob/main/worker/agent.ts) (Frame analysis agent), [`src/router.tsx`](https://github.com/wesbos/yard-sale/blob/main/src/router.tsx) (URL routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and UI"]
  node_app["Scan and live feed<br/>[App.tsx]"]
  node_router["URL routes<br/>[router.tsx]"]
end

subgraph group_analysis["Frame Analysis"]
  node_frame["Frame analysis API<br/>[index.ts]"]
  node_batch["Batch processing<br/>[index.ts]"]
  node_agent["Frame analysis agent<br/>[agent.ts]"]
  node_matching["Fingerprint matching<br/>[normalize.ts]"]
end

subgraph group_research["Valuation Research"]
  node_websearch["Web research"]
  node_ebaytools["eBay search tool<br/>[ebay.ts]"]
  node_ebay["eBay Browse API"]
end

subgraph group_storage["Inventory and Evidence"]
  node_d1[("D1 inventory store")]
  node_schema["Inventory schema<br/>[schema.ts]"]
  node_r2[("R2 thumbnails")]
end

subgraph group_browse["Finds and History"]
  node_history["History query<br/>[history.ts]"]
  node_finds["Saved finds<br/>[App.tsx]"]
  node_detail["Find detail and export<br/>[App.tsx]"]
  node_activity["Agent activity<br/>[App.tsx]"]
  node_download["Image export<br/>[download-modal.ts]"]
end

node_user(("Scanner user"))

node_user -->|"captures or uploads"| node_app
node_user -->|"opens views"| node_router
node_app -->|"sends sampled frames"| node_frame
node_app -->|"submits batch work"| node_batch
node_app -->|"filters inventory"| node_finds
node_router -->|"selects route"| node_app
node_frame -->|"runs analysis"| node_agent
node_agent -->|"scores fingerprints"| node_matching
node_agent -->|"checks prior scans"| node_d1
node_agent -->|"researches products"| node_websearch
node_agent -.->|"invokes search tool"| node_ebaytools
node_ebaytools -.->|"searches listings"| node_ebay
node_frame -->|"saves findings and audit"| node_d1
node_frame -->|"stores thumbnails"| node_r2
node_frame -->|"returns detected items"| node_app
node_finds -->|"requests filtered pages"| node_history
node_history -->|"queries inventory"| node_d1
node_frame -->|"uses data model"| node_schema
node_detail -->|"loads item view"| node_app
node_app -->|"opens run activity"| node_activity
node_activity -->|"requests saved run"| node_frame
node_detail -->|"exports item image"| node_download

click node_app "https://github.com/wesbos/yard-sale/blob/main/src/App.tsx"
click node_router "https://github.com/wesbos/yard-sale/blob/main/src/router.tsx"
click node_frame "https://github.com/wesbos/yard-sale/blob/main/worker/index.ts"
click node_batch "https://github.com/wesbos/yard-sale/blob/main/worker/index.ts"
click node_agent "https://github.com/wesbos/yard-sale/blob/main/worker/agent.ts"
click node_matching "https://github.com/wesbos/yard-sale/blob/main/worker/normalize.ts"
click node_ebaytools "https://github.com/wesbos/yard-sale/blob/main/worker/ebay.ts"
click node_schema "https://github.com/wesbos/yard-sale/blob/main/worker/db/schema.ts"
click node_history "https://github.com/wesbos/yard-sale/blob/main/worker/history.ts"
click node_finds "https://github.com/wesbos/yard-sale/blob/main/src/App.tsx"
click node_detail "https://github.com/wesbos/yard-sale/blob/main/src/App.tsx"
click node_activity "https://github.com/wesbos/yard-sale/blob/main/src/App.tsx"
click node_download "https://github.com/wesbos/yard-sale/blob/main/src/download-modal.ts"

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_app,node_router,node_user toneBlue
class node_frame,node_batch,node_agent,node_matching toneAmber
class node_websearch,node_ebaytools,node_ebay toneMint
class node_d1,node_schema,node_r2 toneRose
class node_history,node_finds,node_detail,node_activity,node_download toneIndigo
```

## Components

### Capture and UI

- [Scan and live feed](https://github.com/wesbos/yard-sale/blob/main/src/App.tsx): `src/App.tsx`
- [URL routes](https://github.com/wesbos/yard-sale/blob/main/src/router.tsx): `src/router.tsx`

### Frame Analysis

- [Frame analysis API](https://github.com/wesbos/yard-sale/blob/main/worker/index.ts): `worker/index.ts`
- [Batch processing](https://github.com/wesbos/yard-sale/blob/main/worker/index.ts): `worker/index.ts`
- [Frame analysis agent](https://github.com/wesbos/yard-sale/blob/main/worker/agent.ts): `worker/agent.ts`
- [Fingerprint matching](https://github.com/wesbos/yard-sale/blob/main/worker/normalize.ts): `worker/normalize.ts`

### Valuation Research

- **Web research**
- [eBay search tool](https://github.com/wesbos/yard-sale/blob/main/worker/ebay.ts): `worker/ebay.ts`
- **eBay Browse API**

### Inventory and Evidence

- **D1 inventory store**
- [Inventory schema](https://github.com/wesbos/yard-sale/blob/main/worker/db/schema.ts): `worker/db/schema.ts`
- **R2 thumbnails**

### Finds and History

- [History query](https://github.com/wesbos/yard-sale/blob/main/worker/history.ts): `worker/history.ts`
- [Saved finds](https://github.com/wesbos/yard-sale/blob/main/src/App.tsx): `src/App.tsx`
- [Find detail and export](https://github.com/wesbos/yard-sale/blob/main/src/App.tsx): `src/App.tsx`
- [Agent activity](https://github.com/wesbos/yard-sale/blob/main/src/App.tsx): `src/App.tsx`
- [Image export](https://github.com/wesbos/yard-sale/blob/main/src/download-modal.ts): `src/download-modal.ts`

### Other components

- **Scanner user**

## Connections

- Scanner user → Scan and live feed: captures or uploads
- Scanner user → URL routes: opens views
- Scan and live feed → Frame analysis API: sends sampled frames
- Scan and live feed → Batch processing: submits batch work
- Scan and live feed → Saved finds: filters inventory
- URL routes → Scan and live feed: selects route
- Frame analysis API → Frame analysis agent: runs analysis
- Frame analysis agent → Fingerprint matching: scores fingerprints
- Frame analysis agent → D1 inventory store: checks prior scans
- Frame analysis agent → Web research: researches products
- Frame analysis agent → eBay search tool: invokes search tool
- eBay search tool → eBay Browse API: searches listings
- Frame analysis API → D1 inventory store: saves findings and audit
- Frame analysis API → R2 thumbnails: stores thumbnails
- Frame analysis API → Scan and live feed: returns detected items
- Saved finds → History query: requests filtered pages
- History query → D1 inventory store: queries inventory
- Frame analysis API → Inventory schema: uses data model
- Find detail and export → Scan and live feed: loads item view
- Scan and live feed → Agent activity: opens run activity
- Agent activity → Frame analysis API: requests saved run
- Find detail and export → Image export: exports item image