# louisguichard/llm-chess-arena architecture

> Architecture diagram of the GitHub repository louisguichard/llm-chess-arena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/louisguichard/llm-chess-arena
- Repository: https://github.com/louisguichard/llm-chess-arena

## Overview

##### Project type and purpose
- This is a full-stack web application built with Flask (Python) on the backend and plain HTML/JavaScript on the frontend.
- Purpose: let users pick two LLMs to play chess against each other, stream moves in real time, compute and display ELO ratings, and persist game history to Google Cloud Storage (GCS).

##### File structure
- Top-level Python modules:
- app.py        – Flask server + SSE endpoint
- client.py     – OpenRouter API client wrapper
- prompts.py    – LLM prompt templates for chess moves
- match.py      – Game orchestration: turn loop, validation
- ratings.py    – ELO rating calculation & update logic
- gcp.py        – GCS read/write: PGN files & ratings.json
- utils.py, logger.py – support utilities/logging
- Config/data:
- models.txt    – list of model IDs to load at startup
- requirements.txt
- .env for API key & GCS_BUCKET_NAME
- Frontend:
- templates/*.html – Jinja templates (index, battle, leaderboard, etc.)
- static/js/*.js     – battle.js (SSE client), stockfish.js (move validation), wasm
- static/pieces      – chess piece images
- No traditional RDBMS: persistence layer is GCS.

##### README for additional insights
- Architecture is monolithic but layered (API-client, game logic, persistence, UI).
- Uses SSE to stream moves from server to browser.
- External dependencies: OpenRouter (OpenAI SDK), Google Cloud Storage.

a. Main components:
1. Browser (User Interface)
– HTML/CSS, JS (battle.js & stockfish.js), SSE client
2. Flask App (Backend)
– Endpoints:
- GET /         → index page
- GET /battle  → battle page
- GET /stream  → SSE stream of moves
- GET /leaderboard → ratings page
3. Match Engine
– match.py orchestrates move requests
– uses prompts.py to generate LLM prompts
4. LLM API Client
– client.py calls OpenRouter API
5. Rating Service
– ratings.py computes ELO
6. Persistence (Google Cloud Storage)
– gcp.py reads/writes PGN & ratings JSON
7. Configuration & Data
– models.txt, .env variables

b. Relationships & data flow
1. User selects two models → Browser sends request to Flask.
2. Flask invokes Match Engine → iterates moves:
a. For each move, prompts.py builds prompt.
b. client.py calls OpenRouter → receives move.
c. match.py validates via stockfish.js (if used client-side) or via server logic.
d. match.py emits move via SSE to browser.
3. At match end:
a. ratings.py computes new ELO.
b. gcp.py writes PGN & rating updates to GCS.
4. Leaderboard endpoint reads ratings.json from GCS via gcp.py.

c. Architectural patterns & design principles
- Layered architecture: presentation (templates/js), application logic (Flask routes + match/rating), infrastructure (OpenRouter client, GCS).
- Streaming (Server-Sent Events) for real-time updates.
- Single monolithic codebase: no microservices, but components are modularized by function.

d. Key technologies/frameworks/libraries
- Flask for web server & SSE
- OpenAI SDK (via OpenRouter)
- Google Cloud Storage Python client
- stockfish.wasm for move validation in browser
- Jinja2 templating
- ELO algorithm implementation in Python

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend Layer"
        BI["Browser UI"]:::frontend
        BJS["battle.js"]:::frontend
        SJS["stockfish.js"]:::frontend
        SWASM["stockfish.wasm"]:::frontend
        PIECES["static/pieces/"]:::frontend
        TINDEX["templates/index.html"]:::frontend
        TBATTLE["templates/battle.html"]:::frontend
        TLEAD["templates/leaderboard.html"]:::frontend
        TBASE["templates/base.html"]:::frontend
        TLOGO["templates/logos.html"]:::frontend
    end

    subgraph "Backend Layer"
        ROUTE["app.py"]:::backend
        MAIN["main.py"]:::backend
        M["match.py"]:::backend
        P["prompts.py"]:::backend
        RAT["ratings.py"]:::backend
        CLI["client.py"]:::backend
        UTIL["utils.py / logger.py"]:::backend
    end

    subgraph "Infrastructure / External"
        GCP["gcp.py"]:::infra
        CFG["models.txt, .env, requirements.txt"]:::infra
        ORAPI["OpenRouter API"]:::external
        GCS["GCS Bucket"]:::external
    end

    %% Data Flow
    BI -->|"select models"| ROUTE
    CFG -->|"load models at startup"| ROUTE
    ROUTE -->|"invoke match"| M
    M -->|"build prompt"| P
    P -->|"prompt text"| CLI
    CLI -->|"call API"| ORAPI
    ORAPI -->|"LLM response"| CLI
    CLI -->|"move data"| M
    M -->|"SSE: move stream"| BI
    M -->|"compute ELO"| RAT
    RAT -->|"update ratings"| GCP
    GCP -->|"write PGN & ratings.json"| GCS
    ROUTE -->|"GET /leaderboard"| GCP
    GCP -->|"read ratings.json"| ROUTE
    ROUTE -->|"serve leaderboard"| BI

    %% Click Events
    click BJS "https://github.com/louisguichard/llm-chess-arena/blob/main/static/js/battle.js"
    click SJS "https://github.com/louisguichard/llm-chess-arena/blob/main/static/js/stockfish.js"
    click SWASM "https://github.com/louisguichard/llm-chess-arena/blob/main/static/js/stockfish.wasm"
    click PIECES "https://github.com/louisguichard/llm-chess-arena/tree/main/static/pieces/"
    click TINDEX "https://github.com/louisguichard/llm-chess-arena/blob/main/templates/index.html"
    click TBATTLE "https://github.com/louisguichard/llm-chess-arena/blob/main/templates/battle.html"
    click TLEAD "https://github.com/louisguichard/llm-chess-arena/blob/main/templates/leaderboard.html"
    click TBASE "https://github.com/louisguichard/llm-chess-arena/blob/main/templates/base.html"
    click TLOGO "https://github.com/louisguichard/llm-chess-arena/blob/main/templates/logos.html"
    click ROUTE "https://github.com/louisguichard/llm-chess-arena/blob/main/app.py"
    click MAIN "https://github.com/louisguichard/llm-chess-arena/blob/main/main.py"
    click M "https://github.com/louisguichard/llm-chess-arena/blob/main/match.py"
    click P "https://github.com/louisguichard/llm-chess-arena/blob/main/prompts.py"
    click RAT "https://github.com/louisguichard/llm-chess-arena/blob/main/ratings.py"
    click CLI "https://github.com/louisguichard/llm-chess-arena/blob/main/client.py"
    click GCP "https://github.com/louisguichard/llm-chess-arena/blob/main/gcp.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px
    classDef backend fill:#DFF2D8,stroke:#228B22,color:#228B22,stroke-width:1px
    classDef infra fill:#FFEBCD,stroke:#DAA520,color:#DAA520,stroke-width:1px
    classDef external fill:#FFE1E1,stroke:#FF4500,color:#FF4500,stroke-width:1px
```
