# poli0981/free-games-itchio-list architecture

> Architecture diagram of the GitHub repository poli0981/free-games-itchio-list, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poli0981/free-games-itchio-list
- Repository: https://github.com/poli0981/free-games-itchio-list

## Overview

Free Itch.io Games List is a public read-only catalog with web and native viewers, plus a maintainer workflow for reviewing additions and a daily data-refresh pipeline. Visitors browse, filter, inspect, and explore catalog charts or removed games; submitters can suggest games, while maintainers review candidates and edit catalog data. The sampled sources show the frontend entry points, Worker routing, and parts of admin handling; README capabilities fill in unsampled domain branches. Some pipeline and storage relationships are documented but their implementation was not sampled.

Main entry points: [`webapp/worker/index.ts`](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/index.ts) (Request router), [`webapp/src/App.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/App.tsx) (Web app), [`webapp/src/lib/data/catalog.ts`](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/lib/data/catalog.ts) (Catalog data), [`webapp/worker/admin.ts`](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/admin.ts) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browse["Public catalog"]
  node_frontend["Web app<br/>[App.tsx]"]
  node_games["Game browsing<br/>[games.tsx]"]
  node_details["Game details<br/>[game-detail.tsx]"]
  node_charts["Catalog charts<br/>[charts.tsx]"]
  node_removed["Removed games<br/>[deleted.tsx]"]
  node_suggest["Suggestions<br/>[suggest.tsx]"]
end

subgraph group_edge["Edge services"]
  node_worker["Request router<br/>[index.ts]"]
  node_gate["Visitor gate<br/>[gate.ts]"]
  node_image["Image resizing<br/>[img.ts]"]
end

subgraph group_maintain["Maintainer workflow"]
  node_adminui["Admin app<br/>[app.tsx]"]
  node_adminpages["Review and editing<br/>[add.tsx]"]
  node_adminapi["Admin API client<br/>[api.ts]"]
  node_adminhandler["Admin API<br/>[admin.ts]"]
  node_queue[("Candidate queue<br/>[queue.ts]")]
end

subgraph group_refresh["Catalog updates"]
  node_repo["Catalog repository<br/>[repo.ts]"]
  node_automation["Automatic discovery<br/>[discover.ts]"]
  node_automationrun["Automated rules<br/>[automation.ts]"]
  node_scrape["Itch scraper<br/>[scraper.py]"]
  node_refreshscript["Data refresh<br/>[refresh.py]"]
  node_rawdata[("Raw catalog<br/>[data_store.py]")]
end

subgraph group_client["App runtime"]
  node_catalog["Catalog data<br/>[catalog.ts]"]
  node_viewer["Native viewers<br/>[lib.rs]"]
end

node_visitor(("Visitor"))
node_itch(("itch.io"))
node_maintainer(("Maintainer"))
node_d1[("Cloudflare D1")]
node_assets["Static assets"]
node_github[("GitHub repository")]

node_visitor -->|"opens"| node_frontend
node_frontend -->|"routes to"| node_games
node_frontend -->|"routes to"| node_details
node_frontend -->|"routes to"| node_charts
node_frontend -->|"routes to"| node_removed
node_frontend -.->|"routes to"| node_suggest
node_games -.->|"reads"| node_catalog
node_details -.->|"reads"| node_catalog
node_charts -.->|"reads"| node_catalog
node_removed -.->|"reads"| node_catalog
node_viewer -.->|"downloads"| node_catalog
node_visitor -->|"requests"| node_worker
node_worker -->|"checks pass"| node_gate
node_worker -->|"dispatches"| node_image
node_image -->|"reads"| node_assets
node_worker -.->|"serves"| node_assets
node_maintainer -->|"uses"| node_adminui
node_adminui -->|"routes to"| node_adminpages
node_adminpages -->|"calls"| node_adminapi
node_adminapi -->|"requests"| node_adminhandler
node_worker -.->|"dispatches"| node_adminhandler
node_adminhandler -.->|"reads and writes"| node_queue
node_adminhandler -.->|"updates"| node_repo
node_worker -->|"runs"| node_automation
node_worker -->|"runs"| node_automationrun
node_automation -.->|"reads feeds"| node_itch
node_automationrun -.->|"uses"| node_repo
node_refreshscript -.->|"uses"| node_scrape
node_refreshscript -.->|"updates"| node_rawdata
node_scrape -.->|"scrapes"| node_itch
node_repo -.->|"reads and writes"| node_github
node_worker -.->|"stores queue"| node_d1

click node_frontend "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/App.tsx"
click node_games "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/games.tsx"
click node_details "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/game-detail.tsx"
click node_charts "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/charts.tsx"
click node_removed "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/deleted.tsx"
click node_suggest "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/suggest.tsx"
click node_catalog "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/lib/data/catalog.ts"
click node_viewer "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src-tauri/src/lib.rs"
click node_worker "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/index.ts"
click node_gate "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/gate.ts"
click node_image "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/img.ts"
click node_adminui "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/admin/app.tsx"
click node_adminpages "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/admin/add.tsx"
click node_adminapi "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/admin/api.ts"
click node_adminhandler "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/admin.ts"
click node_queue "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/queue.ts"
click node_repo "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/repo.ts"
click node_automation "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/discover.ts"
click node_automationrun "https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/automation.ts"
click node_scrape "https://github.com/poli0981/free-games-itchio-list/blob/main/scripts/scraper.py"
click node_refreshscript "https://github.com/poli0981/free-games-itchio-list/blob/main/scripts/refresh.py"
click node_rawdata "https://github.com/poli0981/free-games-itchio-list/blob/main/scripts/data_store.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_frontend,node_games,node_details,node_charts,node_removed,node_suggest toneBlue
class node_worker,node_gate,node_image,node_d1,node_github toneAmber
class node_adminui,node_adminpages,node_adminapi,node_adminhandler,node_queue toneMint
class node_repo,node_automation,node_automationrun,node_scrape,node_refreshscript,node_rawdata toneRose
class node_catalog,node_viewer,node_visitor,node_itch,node_maintainer,node_assets toneIndigo
```

## Components

### Public catalog

- [Web app](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/App.tsx): `webapp/src/App.tsx`
- [Game browsing](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/games.tsx): `webapp/src/routes/games.tsx`
- [Game details](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/game-detail.tsx): `webapp/src/routes/game-detail.tsx`
- [Catalog charts](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/charts.tsx): `webapp/src/routes/charts.tsx`
- [Removed games](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/deleted.tsx): `webapp/src/routes/deleted.tsx`
- [Suggestions](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/routes/suggest.tsx): `webapp/src/routes/suggest.tsx`

### Edge services

- [Request router](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/index.ts): `webapp/worker/index.ts`
- [Visitor gate](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/gate.ts): `webapp/worker/gate.ts`
- [Image resizing](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/img.ts): `webapp/worker/img.ts`

### Maintainer workflow

- [Admin app](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/admin/app.tsx): `webapp/admin/app.tsx`
- [Review and editing](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/admin/add.tsx): `webapp/admin/add.tsx`
- [Admin API client](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/admin/api.ts): `webapp/admin/api.ts`
- [Admin API](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/admin.ts): `webapp/worker/admin.ts`
- [Candidate queue](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/queue.ts): `webapp/worker/queue.ts`

### Catalog updates

- [Catalog repository](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/repo.ts): `webapp/worker/repo.ts`
- [Automatic discovery](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/discover.ts): `webapp/worker/discover.ts`
- [Automated rules](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/worker/automation.ts): `webapp/worker/automation.ts`
- [Itch scraper](https://github.com/poli0981/free-games-itchio-list/blob/main/scripts/scraper.py): `scripts/scraper.py`
- [Data refresh](https://github.com/poli0981/free-games-itchio-list/blob/main/scripts/refresh.py): `scripts/refresh.py`
- [Raw catalog](https://github.com/poli0981/free-games-itchio-list/blob/main/scripts/data_store.py): `scripts/data_store.py`

### App runtime

- [Catalog data](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src/lib/data/catalog.ts): `webapp/src/lib/data/catalog.ts`
- [Native viewers](https://github.com/poli0981/free-games-itchio-list/blob/main/webapp/src-tauri/src/lib.rs): `webapp/src-tauri/src/lib.rs`

### Other components

- **Visitor**
- **itch.io**
- **Maintainer**
- **Cloudflare D1**
- **Static assets**
- **GitHub repository**

## Connections

- Visitor → Web app: opens (evidence: `README.md`)
- Web app → Game browsing: routes to (evidence: `webapp/src/App.tsx`)
- Web app → Game details: routes to (evidence: `webapp/src/App.tsx`)
- Web app → Catalog charts: routes to (evidence: `webapp/src/App.tsx`)
- Web app → Removed games: routes to (evidence: `webapp/src/App.tsx`)
- Web app → Suggestions: routes to (evidence: `README.md`)
- Game browsing → Catalog data: reads
- Game details → Catalog data: reads
- Catalog charts → Catalog data: reads
- Removed games → Catalog data: reads
- Native viewers → Catalog data: downloads (evidence: `README.md`)
- Visitor → Request router: requests (evidence: `webapp/worker/index.ts`)
- Request router → Visitor gate: checks pass (evidence: `webapp/worker/index.ts`)
- Request router → Image resizing: dispatches (evidence: `webapp/worker/index.ts`)
- Image resizing → Static assets: reads (evidence: `webapp/worker/img.ts`)
- Request router → Static assets: serves (evidence: `webapp/worker/index.ts`)
- Maintainer → Admin app: uses (evidence: `README.md`)
- Admin app → Review and editing: routes to (evidence: `webapp/admin/app.tsx`)
- Review and editing → Admin API client: calls (evidence: `webapp/admin/add.tsx`)
- Admin API client → Admin API: requests (evidence: `webapp/admin/api.ts`)
- Request router → Admin API: dispatches (evidence: `webapp/worker/index.ts`)
- Admin API → Candidate queue: reads and writes (evidence: `webapp/worker/admin.ts`)
- Admin API → Catalog repository: updates (evidence: `webapp/worker/admin.ts`)
- Request router → Automatic discovery: runs (evidence: `webapp/worker/index.ts`)
- Request router → Automated rules: runs (evidence: `webapp/worker/index.ts`)
- Automatic discovery → itch.io: reads feeds (evidence: `README.md`)
- Automated rules → Catalog repository: uses
- Data refresh → Itch scraper: uses
- Data refresh → Raw catalog: updates
- Itch scraper → itch.io: scrapes (evidence: `README.md`)
- Catalog repository → GitHub repository: reads and writes
- Request router → Cloudflare D1: stores queue
