# wintrcat/freechess architecture

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

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

## Overview

##### Project Identification
- This is a full-stack web application that analyzes chess games entered by users (via PGN or by retrieving games from Chess.com or Lichess) and generates classifications for each move.
- The README clearly explains that the application “WintrCat's Game Report” processes chess games to highlight mistakes and brilliancies, making it a specialized tool in the chess analytics space.

##### Main Components
a. Client/Frontend:
- A Browser Client that loads static assets.
- HTML files (e.g., located in src/public/pages/report/index.html and src/public/pages/privacy/index.html)
- CSS files (from src/public/global.css and various subdirectories under src/public/pages/report/styles)
- JavaScript files (including client-side scripts like SpeechBubble.js and multiple analysis/report scripts in src/public/pages/report/scripts)
- Media assets (sound files in src/public/media to provide interactive feedback during chess move analysis)
- The Stockfish engine integration for additional on-the-fly evaluation (stockfish.js and the accompanying WASM file)

b. Web Server / Backend:
- A “Web Server” component that handles incoming HTTP requests. This is implemented in Node.js and compiled/use TypeScript (see src/index.ts and src/api.ts).
- An “API Layer” to handle user submissions (e.g., receiving PGNs from the client), likely supporting REST endpoints.
- A “Static Content Server” which serves the files under src/public.

c. Business Logic / Core Services:
- A “Analysis Module” (src/lib/analysis.ts) that will likely contain the logic for processing and evaluating chess moves.
- A “Classification Module” (src/lib/classification.ts) that uses this analysis to generate reports on move quality.
- A “Board Module” (src/lib/board.ts) that may manage the chess board state, positions, or handle move-related computations.
- A collection of “Type Definitions” (in src/lib/types) ensuring type safety and consistency across components (for Classification, Engine, Position, Report, RequestBody).
- A “Resources Module” (src/resources/openings.json) that might contain opening data used during analysis.

d. Testing Subsystem:
- A testing component (src/test containing evaluations.json and reports.ts) used for verifying the classification logic and ensuring accurate evaluation reports.

e. Deployment & Configuration:
- A “Deployment Module” representing Docker configuration (Dockerfile) and environment configurations (.env file, as seen in README instructions).
- The npm scripts and TypeScript configuration (tsconfig.json) guide the build and compilation processes.

##### Inter-Component Relationships and Data Flow
- Within the backend, show how the API layer calls the core business logic modules (Analysis, Classification, Board) to compute results.
- Specify that the processed results (move classifications and analysis reports) are then sent back to the client for display.
- If applicable, show integration with the Stockfish engine scripts (client-side via WASM or JavaScript) as part of the user’s interactive experience.
- Dependency of modules on shared types and interfaces (from src/lib/types).

##### Architectural Patterns and Design Principles
- Separation of concerns: clear division between presentation (frontend static files) and business logic (backend API and analysis modules).
- Modular design principles: distinct libraries (analysis, classification, board) making the system extensible.
- That the use of TypeScript ensures type safety across the application.
- The deployment component via Docker encapsulates environment-specific configuration, making the app portable across servers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Presentation Layer
    subgraph "Browser/Client"
        ReportHTML["Report HTML"]:::client
        PrivacyHTML["Privacy HTML"]:::client
        GlobalCSS["Global CSS"]:::client
        ReportStyles["Report Styles CSS"]:::client
        SpeechBubble["SpeechBubble.js"]:::client
        ReportScripts["Report Scripts"]:::client
        StockfishJS["Stockfish.js"]:::client
        StockfishNNUE["Stockfish-nnue-16.js"]:::client
        StockfishWASM["Stockfish-nnue-16-single.wasm"]:::client
        MediaAssets["Media Assets"]:::client
    end

    %% Web Server / Backend Layer
    subgraph "Web Server / Backend"
        WebServer["Web Server"]:::backend
        APIEndpoints["API Endpoints"]:::backend
    end

    %% Core Business Logic Modules
    subgraph "Business Logic / Core Services"
        AnalysisModule["Analysis Module"]:::core
        ClassificationModule["Classification Module"]:::core
        BoardModule["Board Module"]:::core
        TypeDefinitions["Type Definitions"]:::core
    end

    %% Resources Module
    subgraph "Resources Module"
        OpeningsData["Openings Data"]:::resources
    end

    %% Testing Subsystem
    subgraph "Testing Subsystem"
        TestingSuite["Testing Suite"]:::testing
    end

    %% Deployment & Configuration
    subgraph "Deployment & Configuration"
        DockerConfig["Docker Config"]:::deployment
        TSConfig["tsconfig.json"]:::deployment
        NMPScripts["npm Scripts"]:::deployment
    end

    %% Data Flow Connections
    ReportHTML ---|"loads"| WebServer
    PrivacyHTML ---|"loads"| WebServer
    GlobalCSS ---|"loads"| WebServer
    ReportStyles ---|"loads"| WebServer
    SpeechBubble ---|"loads"| WebServer
    ReportScripts ---|"loads"| WebServer
    StockfishJS ---|"integrates"| ReportScripts
    StockfishNNUE ---|"integrates"| ReportScripts
    StockfishWASM ---|"integrates"| ReportScripts
    MediaAssets ---|"provides assets for"| ReportHTML

    WebServer -->|"processes HTTP"| APIEndpoints
    APIEndpoints -->|"calls"| AnalysisModule
    APIEndpoints -->|"calls"| ClassificationModule
    APIEndpoints -->|"calls"| BoardModule

    AnalysisModule -->|"uses"| TypeDefinitions
    ClassificationModule -->|"uses"| TypeDefinitions
    BoardModule -->|"uses"| TypeDefinitions

    AnalysisModule -->|"reads"| OpeningsData

    APIEndpoints ---|"returns results to"| ReportHTML

    TestingSuite ---|"tests"| ClassificationModule
    TestingSuite ---|"tests"| AnalysisModule

    DockerConfig ---|"deploys"| WebServer
    DockerConfig ---|"deploys"| APIEndpoints
    TSConfig ---|"builds"| WebServer
    TSConfig ---|"builds"| AnalysisModule
    NMPScripts ---|"orchestrates"| WebServer

    %% Click Events for Browser/Client
    click ReportHTML "https://github.com/wintrcat/freechess/blob/master/src/public/pages/report/index.html"
    click PrivacyHTML "https://github.com/wintrcat/freechess/blob/master/src/public/pages/privacy/index.html"
    click GlobalCSS "https://github.com/wintrcat/freechess/blob/master/src/public/global.css"
    click ReportStyles "https://github.com/wintrcat/freechess/tree/master/src/public/pages/report/styles"
    click SpeechBubble "https://github.com/wintrcat/freechess/blob/master/src/public/scripts/SpeechBubble.js"
    click ReportScripts "https://github.com/wintrcat/freechess/tree/master/src/public/pages/report/scripts"
    click StockfishJS "https://github.com/wintrcat/freechess/blob/master/src/public/scripts/stockfish.js"
    click StockfishNNUE "https://github.com/wintrcat/freechess/blob/master/src/public/scripts/stockfish-nnue-16.js"
    click StockfishWASM "https://github.com/wintrcat/freechess/blob/master/src/public/scripts/stockfish-nnue-16-single.wasm"
    click MediaAssets "https://github.com/wintrcat/freechess/tree/master/src/public/media"

    %% Click Events for Web Server / Backend
    click WebServer "https://github.com/wintrcat/freechess/blob/master/src/index.ts"
    click APIEndpoints "https://github.com/wintrcat/freechess/blob/master/src/api.ts"

    %% Click Events for Business Logic / Core Services
    click AnalysisModule "https://github.com/wintrcat/freechess/blob/master/src/lib/analysis.ts"
    click ClassificationModule "https://github.com/wintrcat/freechess/blob/master/src/lib/classification.ts"
    click BoardModule "https://github.com/wintrcat/freechess/blob/master/src/lib/board.ts"
    click TypeDefinitions "https://github.com/wintrcat/freechess/tree/master/src/lib/types"

    %% Click Event for Resources Module
    click OpeningsData "https://github.com/wintrcat/freechess/blob/master/src/resources/openings.json"

    %% Click Event for Testing Subsystem
    click TestingSuite "https://github.com/wintrcat/freechess/tree/master/src/test"

    %% Click Events for Deployment & Configuration
    click DockerConfig "https://github.com/wintrcat/freechess/tree/master/Dockerfile"
    click TSConfig "https://github.com/wintrcat/freechess/blob/master/tsconfig.json"
    click NMPScripts "https://github.com/wintrcat/freechess/blob/master/package.json"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#F4A460,stroke:#000,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef resources fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef testing fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef deployment fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
