# poli0981/free-steam-games-list architecture

> Architecture diagram of the GitHub repository poli0981/free-steam-games-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-steam-games-list
- Repository: https://github.com/poli0981/free-steam-games-list

## Overview

This repository curates a Steam free-to-play game dataset through a Python discovery and maintenance pipeline, then serves it through a public web app and companion desktop/Android apps. The main contributor workflow runs discovery, submits candidate games for admin review, and publishes accepted changes; the public app then serves browse, search, charts, and exports from the dataset. The graph also shows the admin and Worker API, plus pipeline monitoring. Source excerpts are partial, so some subsystem links are documented rather than traced through every handler.

Main entry points: [`scripts/ingest_new.py`](https://github.com/poli0981/free-steam-games-list/blob/main/scripts/ingest_new.py) (Game Discovery), [`web/worker/routes/admin.ts`](https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/admin.ts) (Admin Handlers), [`web/src/routes`](https://github.com/poli0981/free-steam-games-list/tree/main/web/src/routes) (Web App), [`web/worker/index.ts`](https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/index.ts) (Worker Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Dataset Pipeline"]
  node_discovery["Game Discovery<br/>[ingest_new.py]"]
  node_python_core["Pipeline Core"]
  node_dataset[("Published Dataset")]
end

subgraph group_public["Public Apps"]
  node_site["Web App"]
  node_data_client["Dataset Client<br/>[fetcher.ts]"]
  node_charts["Charts"]
  node_desktop_android["Desktop &amp; Android<br/>[lib.rs]"]
end

subgraph group_admin["Admin Review"]
  node_admin_spa["Admin Console<br/>[App.svelte]"]
  node_review_queue["Review Queue<br/>[QueueView.svelte]"]
  node_pipeline_view["Pipeline Monitor"]
  node_admin_api_client["Admin API Client<br/>[api.ts]"]
end

subgraph group_worker["Worker Services"]
  node_worker_entry["Worker Router<br/>[index.ts]"]
  node_ingest_api["Candidate Ingest<br/>[ingest.ts]"]
  node_admin_routes["Admin Handlers<br/>[admin.ts]"]
  node_pipeline_api["Pipeline API<br/>[pipeline.ts]"]
  node_commit_service["Git Commit Service<br/>[git-commit.ts]"]
  node_queue_db[("Review Queue DB<br/>[ingest.ts]")]
end

node_maintainer(("Maintainer"))
node_github["GitHub Actions &amp; Git"]
node_steam["Steam Data Sources"]

node_maintainer -->|"runs sweep"| node_discovery
node_discovery -.->|"fetches game data"| node_steam
node_discovery -->|"submits candidates"| node_ingest_api
node_discovery -.->|"uses pipeline helpers"| node_python_core
node_python_core -.->|"maintains data"| node_dataset
node_maintainer -->|"reviews candidates"| node_admin_spa
node_admin_spa -->|"renders queue"| node_review_queue
node_review_queue -.->|"requests admin API"| node_admin_api_client
node_admin_api_client -->|"calls API"| node_admin_routes
node_admin_routes -->|"reads and updates"| node_queue_db
node_admin_routes -->|"commits changes"| node_commit_service
node_commit_service -->|"writes Git commits"| node_github
node_admin_spa -->|"renders monitor"| node_pipeline_view
node_pipeline_view -->|"requests status"| node_pipeline_api
node_pipeline_api -->|"reads workflow runs"| node_github
node_worker_entry -.->|"routes requests"| node_ingest_api
node_worker_entry -.->|"routes requests"| node_admin_routes
node_worker_entry -.->|"routes requests"| node_pipeline_api
node_site -.->|"loads dataset"| node_data_client
node_data_client -->|"fetches data"| node_dataset
node_site -->|"offers charts"| node_charts
node_site -.->|"shares app experience"| node_desktop_android

click node_discovery "https://github.com/poli0981/free-steam-games-list/blob/main/scripts/ingest_new.py"
click node_python_core "https://github.com/poli0981/free-steam-games-list/tree/main/scripts/core"
click node_dataset "https://github.com/poli0981/free-steam-games-list/tree/main/data"
click node_site "https://github.com/poli0981/free-steam-games-list/tree/main/web/src/routes"
click node_data_client "https://github.com/poli0981/free-steam-games-list/blob/main/web/src/lib/fetcher.ts"
click node_charts "https://github.com/poli0981/free-steam-games-list/tree/main/web/src/routes/charts"
click node_desktop_android "https://github.com/poli0981/free-steam-games-list/blob/main/web/src-tauri/src/lib.rs"
click node_admin_spa "https://github.com/poli0981/free-steam-games-list/blob/main/web/admin/src/App.svelte"
click node_review_queue "https://github.com/poli0981/free-steam-games-list/blob/main/web/admin/src/views/QueueView.svelte"
click node_pipeline_view "https://github.com/poli0981/free-steam-games-list/blob/main/web/admin/src/views/PipelineView.svelte"
click node_admin_api_client "https://github.com/poli0981/free-steam-games-list/blob/main/web/admin/src/lib/api.ts"
click node_worker_entry "https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/index.ts"
click node_ingest_api "https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/ingest.ts"
click node_admin_routes "https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/admin.ts"
click node_pipeline_api "https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/pipeline.ts"
click node_commit_service "https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/lib/git-commit.ts"
click node_queue_db "https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/ingest.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_discovery,node_python_core,node_dataset toneBlue
class node_site,node_data_client,node_charts,node_desktop_android toneAmber
class node_admin_spa,node_review_queue,node_pipeline_view,node_admin_api_client toneMint
class node_worker_entry,node_ingest_api,node_admin_routes,node_pipeline_api,node_commit_service,node_queue_db toneRose
class node_maintainer,node_github,node_steam toneIndigo
```

## Components

### Dataset Pipeline

- [Game Discovery](https://github.com/poli0981/free-steam-games-list/blob/main/scripts/ingest_new.py): `scripts/ingest_new.py`
- [Pipeline Core](https://github.com/poli0981/free-steam-games-list/tree/main/scripts/core): `scripts/core`
- [Published Dataset](https://github.com/poli0981/free-steam-games-list/tree/main/data): `data`

### Public Apps

- [Web App](https://github.com/poli0981/free-steam-games-list/tree/main/web/src/routes): `web/src/routes`
- [Dataset Client](https://github.com/poli0981/free-steam-games-list/blob/main/web/src/lib/fetcher.ts): `web/src/lib/fetcher.ts`
- [Charts](https://github.com/poli0981/free-steam-games-list/tree/main/web/src/routes/charts): `web/src/routes/charts`
- [Desktop & Android](https://github.com/poli0981/free-steam-games-list/blob/main/web/src-tauri/src/lib.rs): `web/src-tauri/src/lib.rs`

### Admin Review

- [Admin Console](https://github.com/poli0981/free-steam-games-list/blob/main/web/admin/src/App.svelte): `web/admin/src/App.svelte`
- [Review Queue](https://github.com/poli0981/free-steam-games-list/blob/main/web/admin/src/views/QueueView.svelte): `web/admin/src/views/QueueView.svelte`
- [Pipeline Monitor](https://github.com/poli0981/free-steam-games-list/blob/main/web/admin/src/views/PipelineView.svelte): `web/admin/src/views/PipelineView.svelte`
- [Admin API Client](https://github.com/poli0981/free-steam-games-list/blob/main/web/admin/src/lib/api.ts): `web/admin/src/lib/api.ts`

### Worker Services

- [Worker Router](https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/index.ts): `web/worker/index.ts`
- [Candidate Ingest](https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/ingest.ts): `web/worker/routes/ingest.ts`
- [Admin Handlers](https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/admin.ts): `web/worker/routes/admin.ts`
- [Pipeline API](https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/pipeline.ts): `web/worker/routes/pipeline.ts`
- [Git Commit Service](https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/lib/git-commit.ts): `web/worker/lib/git-commit.ts`
- [Review Queue DB](https://github.com/poli0981/free-steam-games-list/blob/main/web/worker/routes/ingest.ts): `web/worker/routes/ingest.ts`

### Other components

- **Maintainer**
- **GitHub Actions & Git**
- **Steam Data Sources**

## Connections

- Maintainer → Game Discovery: runs sweep
- Game Discovery → Steam Data Sources: fetches game data
- Game Discovery → Candidate Ingest: submits candidates (evidence: `web/worker/routes/ingest.ts`)
- Game Discovery → Pipeline Core: uses pipeline helpers (evidence: `scripts/ingest_new.py`)
- Pipeline Core → Published Dataset: maintains data
- Maintainer → Admin Console: reviews candidates
- Admin Console → Review Queue: renders queue (evidence: `web/admin/src/App.svelte`)
- Review Queue → Admin API Client: requests admin API (evidence: `web/admin/src/views/QueueView.svelte`)
- Admin API Client → Admin Handlers: calls API (evidence: `web/admin/src/lib/api.ts`)
- Admin Handlers → Review Queue DB: reads and updates (evidence: `web/worker/routes/admin.ts`)
- Admin Handlers → Git Commit Service: commits changes (evidence: `web/worker/routes/admin.ts`)
- Git Commit Service → GitHub Actions & Git: writes Git commits (evidence: `web/worker/lib/git-commit.ts`)
- Admin Console → Pipeline Monitor: renders monitor (evidence: `web/admin/src/App.svelte`)
- Pipeline Monitor → Pipeline API: requests status (evidence: `web/admin/src/views/PipelineView.svelte`)
- Pipeline API → GitHub Actions & Git: reads workflow runs (evidence: `web/worker/routes/pipeline.ts`)
- Worker Router → Candidate Ingest: routes requests (evidence: `web/worker/index.ts`)
- Worker Router → Admin Handlers: routes requests (evidence: `web/worker/index.ts`)
- Worker Router → Pipeline API: routes requests
- Web App → Dataset Client: loads dataset
- Dataset Client → Published Dataset: fetches data (evidence: `web/src/lib/fetcher.ts`)
- Web App → Charts: offers charts
- Web App → Desktop & Android: shares app experience
