How guillaumesd/chesskit works
Project type and purpose
• Chesskit is a full-stack, open-source chess web application.
• Frontend/UI is built with Next.js (React + TypeScript), Material-UI, and WebAssembly-based Stockfish engines.
• Infrastructure is defined and deployed via AWS CDK.
• It integrates with external chess APIs (chess.com, lichess.org) and persists games in a browser-based database (Firebase and/or IndexedDB).
File structure
• Top-level infra:
• cdk/ (AWS CDK definitions: app-stack.ts, app.ts, cdk.json)
• Public assets:
• Source code:
• src/pages/ (Next.js page routes: index, play, database, _app, _document)
• src/components/ (UI primitives, board renderer, navigation)
• src/sections/ (feature areas: play, analysis, engine settings, loadGame, layout)
• src/hooks/ (data fetching, state hooks for engine, game data, local storage)
• src/lib/ (core chess logic, UCI engine wrapper, helper functions, Firebase, Sentry, Lichess & Chess.com integrations)
• Config & scripts:
• package.json, next.config.ts, tsconfig.json, .eslintrc.json, .prettierrc
Extract architecture insights from README
• Next.js for SSR/SSG + SPA behavior
• AWS CDK deploys to CloudFront + S3 (static hosting) with optional Lambda@Edge or Lambda functions
• Firebase used to store user games in the browser database (probably Firestore or IndexedDB wrapper)
• Engines run entirely in the browser via WebAssembly and Web Workers
a. Main components
• Client Browser
• React/Next.js UI
• Web Worker(s) hosting Stockfish WASM
• Local browser storage (IndexedDB/localStorage)
• Static Hosting & Next.js Runtime
• S3 Bucket for static assets
• CloudFront distribution
• (Optional) Lambda@Edge or Lambda functions for SSR/API
• Firebase (Auth & Firestore/RTDB)
• External Chess APIs (chess.com, lichess.org)
b. Interactions & data flows
• User loads the app → CloudFront → S3 (static bundle) or SSR via Lambda@Edge
• UI invokes Stockfish in a Web Worker for analysis → engine returns evaluation & best-move info
• UI queries/stores games to Firebase or IndexedDB via Firebase SDK
• On “Load Game” actions, UI fetches PGN from chess.com/lichess REST endpoints via fetch hooks in the client
c. Architectural patterns & principles
• SPA with SSR/SSG: hybrid rendering for performance & SEO
• Infrastructure as Code: AWS CDK defines hosting, caching, domain, SSL
• Client-side compute: heavy compute (Stockfish) in WebAssembly + Web Worker to keep UI thread responsive
• Modular React: “sections” folder for feature-based code organization
d. Key technologies
• Next.js, React, Material-UI, TypeScript
• AWS CDK → S3, CloudFront, Route 53, Lambda@Edge (optional)
• Firebase SDK → Auth, Firestore or Realtime DB
• Stockfish engines compiled to WASM + JavaScript wrappers
• External REST APIs: chess.com, lichess.org
• Labels: each component (e.g., “Stockfish Web Worker”, “CloudFront CDN”, “Firestore DB”)
• Blue for client-side components
• Green for AWS infra
• Orange for external services & databases
• Rectangles for compute/services (Next.js, Web Worker)
Detailed elements to capture
• Stockfish engine initialization in a worker thread
• Next.js routing (_app, pages) and optional SSR Lambdas
• Firebase persistence vs. localStorage caching
• External PGN fetch flows from chess.com/lichess
• AWS CDK resource relationships (S3 → CloudFront → Route53)