# jeonjas25/cardfolio architecture

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

## Overview

Cardfolio manages a personal baseball-card collection, with a principal workflow from collection browsing or card entry through API-backed persistence to card details and price history. Photo identification fills card fields through Claude; price refreshes dispatch background work that searches eBay, filters listings, computes a median, and records history. The README also documents scheduled stale-price refreshes. The graph uses the sampled endpoint, task, service, and UI calls; some integrations and the scheduler are documented but their configuration details were not sampled.

Main entry points: [`backend/main.py`](https://github.com/jeonjas25/cardfolio/blob/main/backend/main.py) (REST endpoints), [`frontend/src/App.jsx`](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/App.jsx) (Route shell), [`frontend/src/components/CollectionPage.jsx`](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/CollectionPage.jsx) (Collection browser), [`backend/services.py`](https://github.com/jeonjas25/cardfolio/blob/main/backend/services.py) (Refresh service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Collection interface"]
  node_app["Route shell<br/>[App.jsx]"]
  node_collection["Collection browser<br/>[CollectionPage.jsx]"]
  node_toolbar["Search and filters"]
  node_card_tile["Card tile<br/>[Card.jsx]"]
  node_add_form["Add card form<br/>[AddCardForm.jsx]"]
  node_detail["Card details<br/>[CardDetail.jsx]"]
  node_chart["Price history chart"]
end

subgraph group_api["Card API"]
  node_client_api["HTTP client<br/>[api.js]"]
  node_http_api["REST endpoints<br/>[main.py]"]
  node_schemas["Request responses<br/>[schemas.py]"]
  node_card_model["Card record<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_identifier["Image identification<br/>[ai.py]"]
end

subgraph group_pricing["Market pricing"]
  node_task_queue["Celery dispatch<br/>[celery_app.py]"]
  node_worker["Price refresh tasks<br/>[tasks.py]"]
  node_pricing_service["Refresh service<br/>[services.py]"]
  node_ebay_search["eBay listings<br/>[ebay.py]"]
  node_matching["Listing matching<br/>[pricing.py]"]
end

node_collector(("Collector"))
node_claude{{"Claude Vision"}}
node_ebay{{"eBay Browse API"}}

node_collector -->|"uses"| node_app
node_app -->|"routes to"| node_collection
node_app -->|"routes to"| node_add_form
node_app -->|"routes to"| node_detail
node_collection -->|"loads cards"| node_client_api
node_collection -->|"renders"| node_toolbar
node_collection -->|"renders"| node_card_tile
node_add_form -->|"creates and identifies"| node_client_api
node_detail -->|"reads and updates"| node_client_api
node_detail -->|"renders"| node_chart
node_client_api -->|"HTTP requests"| node_http_api
node_http_api -->|"validates responses"| node_schemas
node_http_api -->|"reads and writes"| node_card_model
node_card_model -->|"maps records"| node_database
node_http_api -->|"identifies image"| node_identifier
node_identifier -.->|"analyzes image"| node_claude
node_http_api -->|"dispatches refresh"| node_task_queue
node_task_queue -->|"runs tasks"| node_worker
node_worker -->|"queries cards"| node_database
node_worker -->|"refreshes card"| node_pricing_service
node_pricing_service -->|"searches listings"| node_ebay_search
node_ebay_search -.->|"queries sold listings"| node_ebay
node_pricing_service -->|"filters and prices"| node_matching
node_pricing_service -->|"commits history"| node_database
node_collector -.->|"requests stale refresh"| node_http_api

click node_app "https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/App.jsx"
click node_collection "https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/CollectionPage.jsx"
click node_toolbar "https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/CollectionToolbar.jsx"
click node_card_tile "https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/Card.jsx"
click node_add_form "https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/AddCardForm.jsx"
click node_detail "https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/CardDetail.jsx"
click node_chart "https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/PriceHistoryChart.jsx"
click node_client_api "https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/api.js"
click node_http_api "https://github.com/jeonjas25/cardfolio/blob/main/backend/main.py"
click node_schemas "https://github.com/jeonjas25/cardfolio/blob/main/backend/schemas.py"
click node_card_model "https://github.com/jeonjas25/cardfolio/blob/main/backend/models.py"
click node_database "https://github.com/jeonjas25/cardfolio/blob/main/backend/database.py"
click node_identifier "https://github.com/jeonjas25/cardfolio/blob/main/backend/ai.py"
click node_task_queue "https://github.com/jeonjas25/cardfolio/blob/main/backend/celery_app.py"
click node_worker "https://github.com/jeonjas25/cardfolio/blob/main/backend/tasks.py"
click node_pricing_service "https://github.com/jeonjas25/cardfolio/blob/main/backend/services.py"
click node_ebay_search "https://github.com/jeonjas25/cardfolio/blob/main/backend/ebay.py"
click node_matching "https://github.com/jeonjas25/cardfolio/blob/main/backend/pricing.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_app,node_collection,node_toolbar,node_card_tile,node_add_form,node_detail,node_chart toneBlue
class node_client_api,node_http_api,node_schemas,node_card_model,node_database,node_identifier toneAmber
class node_task_queue,node_worker,node_pricing_service,node_ebay_search,node_matching,node_ebay toneMint
class node_collector,node_claude toneIndigo
```

## Components

### Collection interface

- [Route shell](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Collection browser](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/CollectionPage.jsx): `frontend/src/components/CollectionPage.jsx`
- [Search and filters](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/CollectionToolbar.jsx): `frontend/src/components/CollectionToolbar.jsx`
- [Card tile](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/Card.jsx): `frontend/src/components/Card.jsx`
- [Add card form](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/AddCardForm.jsx): `frontend/src/components/AddCardForm.jsx`
- [Card details](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/CardDetail.jsx): `frontend/src/components/CardDetail.jsx`
- [Price history chart](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/components/PriceHistoryChart.jsx): `frontend/src/components/PriceHistoryChart.jsx`

### Card API

- [HTTP client](https://github.com/jeonjas25/cardfolio/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [REST endpoints](https://github.com/jeonjas25/cardfolio/blob/main/backend/main.py): `backend/main.py`
- [Request responses](https://github.com/jeonjas25/cardfolio/blob/main/backend/schemas.py): `backend/schemas.py`
- [Card record](https://github.com/jeonjas25/cardfolio/blob/main/backend/models.py): `backend/models.py`
- [PostgreSQL](https://github.com/jeonjas25/cardfolio/blob/main/backend/database.py): `backend/database.py`
- [Image identification](https://github.com/jeonjas25/cardfolio/blob/main/backend/ai.py): `backend/ai.py`

### Market pricing

- [Celery dispatch](https://github.com/jeonjas25/cardfolio/blob/main/backend/celery_app.py): `backend/celery_app.py`
- [Price refresh tasks](https://github.com/jeonjas25/cardfolio/blob/main/backend/tasks.py): `backend/tasks.py`
- [Refresh service](https://github.com/jeonjas25/cardfolio/blob/main/backend/services.py): `backend/services.py`
- [eBay listings](https://github.com/jeonjas25/cardfolio/blob/main/backend/ebay.py): `backend/ebay.py`
- [Listing matching](https://github.com/jeonjas25/cardfolio/blob/main/backend/pricing.py): `backend/pricing.py`

### Other components

- **Collector**
- **Claude Vision**
- **eBay Browse API**

## Connections

- Collector → Route shell: uses
- Route shell → Collection browser: routes to (evidence: `frontend/src/App.jsx`)
- Route shell → Add card form: routes to (evidence: `frontend/src/App.jsx`)
- Route shell → Card details: routes to (evidence: `frontend/src/App.jsx`)
- Collection browser → HTTP client: loads cards (evidence: `frontend/src/components/CollectionPage.jsx`)
- Collection browser → Search and filters: renders (evidence: `frontend/src/components/CollectionPage.jsx`)
- Collection browser → Card tile: renders (evidence: `frontend/src/components/CollectionPage.jsx`)
- Add card form → HTTP client: creates and identifies (evidence: `frontend/src/components/AddCardForm.jsx`)
- Card details → HTTP client: reads and updates (evidence: `frontend/src/components/CardDetail.jsx`)
- Card details → Price history chart: renders (evidence: `frontend/src/components/CardDetail.jsx`)
- HTTP client → REST endpoints: HTTP requests (evidence: `frontend/src/api.js`)
- REST endpoints → Request responses: validates responses (evidence: `backend/main.py`)
- REST endpoints → Card record: reads and writes (evidence: `backend/main.py`)
- Card record → PostgreSQL: maps records (evidence: `backend/models.py`)
- REST endpoints → Image identification: identifies image (evidence: `backend/main.py`)
- Image identification → Claude Vision: analyzes image (evidence: `README.md`)
- REST endpoints → Celery dispatch: dispatches refresh (evidence: `backend/main.py`)
- Celery dispatch → Price refresh tasks: runs tasks (evidence: `backend/tasks.py`)
- Price refresh tasks → PostgreSQL: queries cards (evidence: `backend/tasks.py`)
- Price refresh tasks → Refresh service: refreshes card (evidence: `backend/tasks.py`)
- Refresh service → eBay listings: searches listings (evidence: `backend/services.py`)
- eBay listings → eBay Browse API: queries sold listings (evidence: `README.md`)
- Refresh service → Listing matching: filters and prices (evidence: `backend/services.py`)
- Refresh service → PostgreSQL: commits history (evidence: `backend/services.py`)
- Collector → REST endpoints: requests stale refresh (evidence: `README.md`)
