Chess is part of my life outside software. At 1839 Rapid and 1817 Blitz, I care about what happens after a game: the decisions I missed, the openings I keep returning to, and the questions worth asking before the next one.
I wanted to bring that review into a conversation with ChatGPT without repeatedly copying PGN files and rebuilding the context. My games already existed on Chess.com. The missing piece was a dependable way to make them readable.
So I built a small bridge: one permanent URL, the latest completed games, and the original record preserved. A personal reason to build it became an engineering problem about validation, chess notation, reliable APIs, and keeping data in sync.
Project illustration · API flow verified against source
OVERVIEW
A personal bridge from Chess.com to ChatGPT: completed games become structured JSON with the original PGN, move history, and player context intact.
MY ROLE
Personal project · API design, upstream integration, PGN normalization, scheduled synchronization, and shared deployment adapters.
STATUS
Live Cloudflare API · Health endpoint verified · Private source
Reviewing one game is easy to start manually. Repeatedly retrieving the right games, preserving their complete move history, and giving ChatGPT consistent player-relative context creates friction. Monthly archives also need filtering and validation before they are useful.
02 — APPROACH
The system
A TypeScript/Hono service reads the official Chess.com PubAPI for a fixed player. Zod validates upstream payloads; chess.js parses PGN into moves and positions. Read-only endpoints expose games, profile, ratings, and objective summaries. A separate Cloudflare Cron job maintains JSON snapshots in a GitHub data repository.
ArchitectureSimplified system flow
01
Chess.com PubAPI
Completed games · PGN
→↓02
Validated Fetch
Zod · Filters · Deduplication
→↓03
Normalize / Parse
chess.js · SAN · FEN
↓Independent Cron path↳
Scheduled GitHub Mirror
Cron · SHA-256 · Atomic commit
→↓04
JSON → ChatGPT
Read-only Hono endpoints
01 / On-demand reads
A GET request enters Hono. The client walks monthly archives newest-first, validates upstream responses, filters by time class, and stops once it has enough unique games. The default traversal cap is 24 months.
02 / Preserve the evidence
chess.js replays the PGN into SAN moves and FEN positions. Results and ratings are oriented around the configured player. The original PGN survives even when parsing fails, with an explicit parse.ok flag.
03 / A separate scheduled path
The Cloudflare scheduler reuses the same client and normalization pipeline once per minute. It compares game IDs and stable SHA-256 fingerprints, then writes latest, recent, stats, and status JSON in one atomic Git commit only when content changes. API reads do not trigger writes.
04 / One app, two runtimes
A shared Hono app serves the Worker and a thin Vercel Node adapter. Cloudflare provides native IP rate limiting; Vercel uses a bounded in-memory limiter per instance. No database or application-level game cache is required.
03 — IMPLEMENTATION
Engineering highlights
Kept the player fixed server-side and constructed only official PubAPI paths, avoiding an unrestricted proxy or any need for Chess.com login credentials.
Traversed archives sequentially, newest-first, with an early stop, duplicate detection, strict query limits, an 8-second default timeout, and bounded retries for upstream HTTP 429 responses.
Preserved original PGN and marked parsing failures explicitly so a malformed historical game does not discard the entire multi-game response.
Made synchronization change-driven: reuse unchanged parsed games, compare stable content fingerprints, and update four JSON documents in one atomic commit without timestamp-only churn.
Shared one Hono application across Workers and Vercel while keeping scheduling and GitHub write credentials confined to the Cloudflare sync path.
Added mocked tests for normalization, API validation, rate limits, upstream failures, deployment adapters, and atomic mirror updates that skip unchanged content.
04 — REALITY CHECK
Scope & transparency
This service prepares data for a separate ChatGPT conversation; it does not call an AI model, run Stockfish, assign engine evaluations, or play moves. Recent summaries are descriptive aggregates. Chess.com upstream caching can delay new games. The source and data repositories are currently private, so GitHub Raw access is not presented as a public feature. The live health check confirms service availability, not the current scheduler state or Vercel deployment.
