# guillaumesd/chesskit architecture

> Architecture diagram of the GitHub repository guillaumesd/chesskit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guillaumesd/chesskit
- Repository: https://github.com/guillaumesd/chesskit

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Browser["Client Browser"]:::client
        UI["Next.js UI"]:::client
        Worker["Stockfish Web Worker"]:::client
        LocalStorage["IndexedDB / localStorage"]:::data
    end

    %% Data & Engine Layer
    subgraph "Data & Engine Layer"
        direction TB
        Firebase["Firebase (Auth & Firestore)"]:::data
        ExternalAPIs["External Chess APIs"]:::external
        Engines["Stockfish WASM Engines"]:::data
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        Route53["Route 53"]:::infra
        CloudFront["CloudFront CDN"]:::infra
        S3["S3 Bucket (Static Assets)"]:::infra
        LambdaEdge["Lambda@Edge / Lambda Functions"]:::infra
        CDK["AWS CDK Definitions"]:::infra
    end

    %% Connections
    Browser -->|Load App| CloudFront
    CloudFront -->|Fetch Static Assets| S3
    CloudFront -->|SSR/SSG Requests| LambdaEdge
    LambdaEdge -->|Deploy via IaC| CDK

    CloudFront -->|Deliver Bundle| Browser
    Browser -->|Render UI| UI
    UI -->|Spawn| Worker
    Worker -->|Run Analysis| Engines

    UI -->|Read/Write| LocalStorage
    UI -->|Read/Write| Firebase
    UI -->|Fetch PGN| ExternalAPIs

    %% Click Events
    click CDK "https://github.com/guillaumesd/chesskit/blob/main/cdk/app-stack.ts"
    click Engines "https://github.com/guillaumesd/chesskit/blob/main/public/engines/stockfish-11.js"
    click UI "https://github.com/guillaumesd/chesskit/blob/main/src/pages/_app.tsx"
    click Browser "https://github.com/guillaumesd/chesskit/blob/main/src/pages/index.tsx"
    click LocalStorage "https://github.com/guillaumesd/chesskit/blob/main/src/pages/database.tsx"
    click Worker "https://github.com/guillaumesd/chesskit/blob/main/src/pages/play.tsx"

    click ComponentsDir "https://github.com/guillaumesd/chesskit/tree/main/src/components/"
    click SectionsPlay "https://github.com/guillaumesd/chesskit/blob/main/src/sections/play/board.tsx"
    click SectionsAnalysis "https://github.com/guillaumesd/chesskit/blob/main/src/sections/analysis/board/index.tsx"
    click SectionsEngineSettings "https://github.com/guillaumesd/chesskit/blob/main/src/sections/engineSettings/engineSettingsDialog.tsx"
    click SectionsLoadGame "https://github.com/guillaumesd/chesskit/blob/main/src/sections/loadGame/loadGameDialog.tsx"
    click HooksDir "https://github.com/guillaumesd/chesskit/tree/main/src/hooks/"
    click LibEngineDir "https://github.com/guillaumesd/chesskit/blob/main/src/lib/engine/uciEngine.ts"

    %% Style Definitions
    classDef client fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef infra fill:#E6FFDA,stroke:#28a745,color:#28a745,stroke-width:1px;
    classDef data fill:#FFF4CC,stroke:#DBA506,color:#DBA506,stroke-width:1px;
    classDef external fill:#FFE6E6,stroke:#d73a49,color:#d73a49,stroke-width:1px;
```
