# guillaumesd/freechess architecture

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

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

## Overview

##### Main Components
- User Interface (UI) / Frontend:
- Pages (located in src/pages) that manage routing (e.g., _app.tsx, _document.tsx, play.tsx, database.tsx).
- Components and Sections (found in src/components and src/sections) such as the board display, analysis panels, navigation bar, and engine settings.
- Engine Integration:
- Dedicated engine libraries in src/lib/engine that wrap Stockfish (e.g., stockfish11.ts, stockfish16.ts, stockfish17.ts).
- Web worker implementations (worker.ts) for running engine evaluations asynchronously, alongside WebAssembly modules hosted in the public/engines folder.
- Utility & Data Modules:
- Helpers for chess logic (src/lib/chess.ts, src/lib/helpers.ts, src/types folder, etc.).
- Data integrations (src/lib/chessCom.ts, src/lib/lichess.ts) for fetching/analyzing imported games.
- Deployment & Firebase:
- Firebase configurations (firebase.json, src/lib/firebase.ts) that show deployment and potentially real-time data or user game storage.

##### Relationships and Interactions
- The Next.js layer processes requests and routes to various pages, each composed of multiple React components.
- Within the UI, specialized sections (like analysis, play, load game) interact with custom hooks (e.g., useGameData, useEngine) to manage state and trigger chess logic evaluations.
- The engine integration layer uses the UCI engine worker (src/lib/engine/worker.ts) that communicates with the Stockfish engine files (in public/engines) to generate move evaluations and analyses.
- External sources such as chess.com and lichess provide game PGNs/input which are handled by dedicated libraries and components.
- Firebase serves both the deployment and possibly game state persistence.

##### Important Architectural Patterns and Design Principles
- Component-based design: The clear organization into components and sections (layout, analysis, play, engine settings) reflects a modular approach.
- Separation of concerns: The UI (React components) is cleanly separated from business logic (in src/lib) and engine interactions.
- Asynchronous & Worker-based processing: Using web workers for Stockfish engine computations to keep the UI responsive.
- Integration of third-party services: Using external APIs (chess.com, lichess) and Firebase for deployment/storage.
- Use of TypeScript enhances type safety across these layers.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend technologies: Next.js, React, Material UI, TypeScript.
- Engine and computational modules: Stockfish engines (JavaScript and WebAssembly versions) integrated via custom UCI handling.
- Deployment/infrastructure: Firebase hosting, configuration files (firebase.json, next.config.ts).
- Code quality tools: ESLint, Prettier.

##### Elements
- Nodes for major components:
- “User / Browser”
- “Next.js Frontend (Pages & Components)”
- “UI Layers (Analysis, Play, Navigation, etc.)”
- “React Hooks & State Management”
- “Engine Integration (UCI, Stockfish Workers, WebAssembly Modules)”
- “External APIs (Chess.com, Lichess)”
- “Firebase Deployment & Game Data Storage”

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User / Browser"]:::user
    F["Next.js Frontend (Pages & Components)"]:::ui
    H["React Hooks & State Management"]:::ui

    %% Frontend Pages Subgraph
    subgraph "Frontend Pages"
        AppPage["App Page (_app.tsx)"]:::ui
        DocumentPage["Document Page (_document.tsx)"]:::ui
        PlayPage["Play Page (play.tsx)"]:::ui
        DatabasePage["Database Page (database.tsx)"]:::ui
    end

    %% UI Components Subgraph
    subgraph "UI Components"
        Board["Board Component"]:::ui
        AnalysisSection["Analysis Section"]:::ui
        PlaySection["Play Section"]:::ui
        LayoutSection["Layout Section"]:::ui
        EngineSettingsSection["Engine Settings Section"]:::ui
        LoadGameSection["Load Game Section"]:::ui
    end

    %% Engine Integration Subgraph
    subgraph "Engine Integration"
        EWorker["Engine Worker"]:::engine
        Stockfish11["Stockfish 11"]:::engine
        Stockfish16["Stockfish 16"]:::engine
        Stockfish16_1["Stockfish 16.1"]:::engine
        Stockfish17["Stockfish 17"]:::engine
        UCI["UCI Engine"]:::engine
        WASMModules["WebAssembly Modules"]:::engine
    end

    %% Utility & Data Modules Subgraph
    subgraph "Utility & Data Modules"
        ChessLogic["Chess Logic"]:::util
        Helpers["Helpers"]:::util
        MathLib["Math Library"]:::util
        ChessCom["Chess.com Integration"]:::util
        Lichess["Lichess Integration"]:::util
        TypeDefinitions["Type Definitions"]:::util
    end

    %% Deployment & Firebase Subgraph
    subgraph "Deployment & Firebase"
        FirebaseConfig["Firebase Config"]:::deployment
        FirebaseLib["Firebase Library"]:::deployment
    end

    %% Connections
    U -->|"UserInput"| F
    F -->|"Routing"| AppPage
    F -->|"Routing"| DocumentPage
    F -->|"Routing"| PlayPage
    F -->|"Routing"| DatabasePage
    F -->|"RenderUI"| Board
    F -->|"RenderUI"| AnalysisSection
    F -->|"RenderUI"| PlaySection
    F -->|"RenderUI"| LayoutSection
    F -->|"RenderUI"| EngineSettingsSection
    F -->|"RenderUI"| LoadGameSection

    Board --> H
    AnalysisSection --> H
    PlaySection --> H
    LayoutSection --> H
    EngineSettingsSection --> H
    LoadGameSection --> H

    H -->|"EngineEvaluation"| EWorker
    EWorker -->|"Results"| H

    H -->|"DataFetch"| ChessCom
    H -->|"DataFetch"| Lichess

    Board -->|"LogicOps"| ChessLogic
    Board -->|"HelperCalls"| Helpers
    Board -->|"MathOps"| MathLib

    H -->|"FirebaseSync"| FirebaseLib

    %% Engine Integration internal connections
    EWorker --> Stockfish11
    EWorker --> Stockfish16
    EWorker --> Stockfish16_1
    EWorker --> Stockfish17
    EWorker --> UCI
    EWorker --> WASMModules

    %% Class definitions for color coding
    classDef ui fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef engine fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef util fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef deployment fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef user fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;

    %% Click Events for UI/Frontend Pages
    click AppPage "https://github.com/guillaumesd/freechess/blob/main/src/pages/_app.tsx"
    click DocumentPage "https://github.com/guillaumesd/freechess/blob/main/src/pages/_document.tsx"
    click PlayPage "https://github.com/guillaumesd/freechess/blob/main/src/pages/play.tsx"
    click DatabasePage "https://github.com/guillaumesd/freechess/blob/main/src/pages/database.tsx"

    %% Click Events for UI Components
    click Board "https://github.com/guillaumesd/freechess/blob/main/src/components/board/index.tsx"
    click AnalysisSection "https://github.com/guillaumesd/freechess/tree/main/src/sections/analysis"
    click PlaySection "https://github.com/guillaumesd/freechess/tree/main/src/sections/play"
    click LayoutSection "https://github.com/guillaumesd/freechess/tree/main/src/sections/layout"
    click EngineSettingsSection "https://github.com/guillaumesd/freechess/tree/main/src/sections/engineSettings"
    click LoadGameSection "https://github.com/guillaumesd/freechess/tree/main/src/sections/loadGame"

    %% Click Events for Engine Integration
    click Stockfish11 "https://github.com/guillaumesd/freechess/blob/main/src/lib/engine/stockfish11.ts"
    click Stockfish16 "https://github.com/guillaumesd/freechess/blob/main/src/lib/engine/stockfish16.ts"
    click Stockfish16_1 "https://github.com/guillaumesd/freechess/blob/main/src/lib/engine/stockfish16_1.ts"
    click Stockfish17 "https://github.com/guillaumesd/freechess/blob/main/src/lib/engine/stockfish17.ts"
    click UCI "https://github.com/guillaumesd/freechess/blob/main/src/lib/engine/uciEngine.ts"
    click EWorker "https://github.com/guillaumesd/freechess/blob/main/src/lib/engine/worker.ts"
    click WASMModules "https://github.com/guillaumesd/freechess/tree/main/public/engines"

    %% Click Events for Utility & Data Modules
    click ChessLogic "https://github.com/guillaumesd/freechess/blob/main/src/lib/chess.ts"
    click Helpers "https://github.com/guillaumesd/freechess/blob/main/src/lib/helpers.ts"
    click MathLib "https://github.com/guillaumesd/freechess/blob/main/src/lib/math.ts"
    click ChessCom "https://github.com/guillaumesd/freechess/blob/main/src/lib/chessCom.ts"
    click Lichess "https://github.com/guillaumesd/freechess/blob/main/src/lib/lichess.ts"
    click TypeDefinitions "https://github.com/guillaumesd/freechess/tree/main/src/types"

    %% Click Events for Deployment & Firebase
    click FirebaseConfig "https://github.com/guillaumesd/freechess/blob/main/firebase.json"
    click FirebaseLib "https://github.com/guillaumesd/freechess/blob/main/src/lib/firebase.ts"
```
