# dieg0r01/chesstrainer architecture

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

- Interactive diagram: https://gitdiagram.com/dieg0r01/chesstrainer
- Repository: https://github.com/dieg0r01/chesstrainer

## Overview

Para elaborar un diagrama de arquitectura claro y detallado de esta “Plataforma de Ajedrez con Motores Externos”, sigue estos pasos, adaptados al propósito y estructura del proyecto:

##### Identificación del tipo de proyecto y su propósito
- Es una aplicación web full-stack:
- Frontend en React.js (Vite) para la interfaz de usuario (UI).
- Backend en Python (FastAPI) que expone una API REST y sirve archivos estáticos.
- Integración con motores de ajedrez externos (REST y UCI).
- Objetivo: permitir partidas Humano vs. Motor o Motor vs. Motor, configurables vía YAML.

##### Análisis de la estructura de ficheros
- Top-level:
- Dockerfile, config/, engine_manager.py, main.py, requirements.txt
- frontend/ (React, Vite)
- Dentro de frontend/:
- Código React (src/), index.html, configuración Vite, ESLint, package.json
- Configuración de motores en config/engines.yaml
- Backend:
- main.py: instancia FastAPI, rutas `/` y `/move`
- engine_manager.py: EngineInterface, EngineManager, adaptadores RestEngineAdapter y UciEngineAdapter

##### Componentes principales para el diagrama
A. Usuario y Navegador (Browser)
B. Frontend React (Vite dev server o archivos estáticos servidos por FastAPI)
C. API Server FastAPI (Uvicorn)
D. EngineManager (carga config YAML, delega peticiones)
E. Adaptadores de motor:
1. RestEngineAdapter → Motores REST externos
2. UciEngineAdapter → Motores UCI locales (p. ej. Stockfish)
F. Archivo de configuración YAML (`config/engines.yaml`)
G. Motores externos:
1. Servicios REST (por ejemplo lichess.org)
2. Proceso local UCI (por ejemplo stockfish)
H. Contenedor Docker (opcionalmente, como envoltorio de todo)

##### Relaciones e interacciones
- El Usuario mueve una pieza en el UI (React + react-chessboard).
- La jugada se valida localmente con chess.js.
- Frontend envía POST /move al Backend con `{engine, fen, depth}`.
- FastAPI (main.py) recibe la petición y la pasa a EngineManager.
- EngineManager consulta `config/engines.yaml`, determina el adaptador: Rest o UCI.
- RestEngineAdapter: construye y ejecuta llamada HTTP al motor REST, extrae mejor movimiento con jsonpath.
- UciEngineAdapter: lanza o comunica con el proceso UCI (stdin/stdout).
- El adaptador devuelve `bestmove` a EngineManager, que lo envía como respuesta JSON al Frontend.
- Frontend actualiza el tablero.
- En modo Motor vs. Motor, el Frontend repite el ciclo automáticamente cada X segundos.

##### Patrón y principios arquitectónicos
- Separación clara Frontend / Backend (Single Page App y API REST).
- Adaptador (Adapter Pattern) para motores: RestEngineAdapter y UciEngineAdapter implementan la misma interfaz `EngineInterface`.
- Configuración declarativa (YAML) para facilidad de extensibilidad sin tocar código.
- Contenerización (Docker) para despliegue reproducible.
- Uso de librerías especializadas: `chess.js`, `react-chessboard`, `FastAPI`, `Pydantic`, `jsonpath`, `Vite`.

##### Guía práctica para el diagrama
a. Usa contenedores (rectángulos con esquinas redondeadas) para cada componente mayor:
– Cliente (Browser)
– Frontend React
– Backend FastAPI
– EngineManager
– Adaptadores (Rest, UCI)
– Motores externos
– Configuración YAML
– (Opcional) Docker Host
b. Dibuja flechas direccionales para mostrar flujos de datos:
– Cliente → Frontend (interacción UI)
– Frontend → Backend (HTTP GET/POST)
– Backend → EngineManager → Adaptadores → Motores
– Motores → Adaptadores → EngineManager → Backend → Frontend
– Azul para componentes del Frontend
– Verde para Backend y gestión interna
– Naranja para adaptadores
– Rojo para servicios externos / procesos locales
d. Etiqueta cada flecha con la operación o formato de datos (por ejemplo, “POST /move {fen, depth}”, “HTTP GET JSON”, “stdin/stdout UCI”).

##### Elementos mínimos obligatorios en el diagrama
- Componentes claramente nombrados (p. ej. “RestEngineAdapter”).
- Flechas con dirección y texto explicativo.
- Archivos clave (config/engines.yaml) destacados junto al EngineManager.
- Indicaciones de ciclo para Motor vs. Motor (loop timer).
- Servicio de archivos estáticos para React (ruta `/`).

Con esta guía, el diagrama reflejará con precisión la arquitectura de la plataforma, resaltando la separación de responsabilidades, los flujos de comunicación y los puntos de extensión para nuevos motores.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container" 
        direction TB
        subgraph "Client"
            direction TB
            Browser["Browser (UI)"]:::frontend
        end

        subgraph "Frontend Layer"
            direction TB
            ReactApp["React Application (Vite)"]:::frontend
        end

        subgraph "Backend Layer"
            direction TB
            FastAPI["FastAPI Server"]:::backend
            EM["EngineManager"]:::backend
            YAML["engines.yaml"]:::config
            RestAdapter["RestEngineAdapter"]:::adapter
            UciAdapter["UciEngineAdapter"]:::adapter
        end

        subgraph "External Engines"
            direction TB
            RESTEngine["External REST Engine"]:::external
            UCIEngine["Local UCI Engine"]:::external
        end
    end

    %% Connections
    Browser -->|"Interacts with UI"| ReactApp
    ReactApp -->|"POST /move {fen,depth}"| FastAPI
    FastAPI -->|"delegate Move()"| EM
    EM -->|"load config"| YAML
    EM -->|"uses Adapter"| RestAdapter
    EM -->|"uses Adapter"| UciAdapter
    RestAdapter -->|"HTTP GET JSON"| RESTEngine
    UciAdapter -->|"stdin/stdout UCI"| UCIEngine
    RESTEngine -->|"JSON {bestmove}"| RestAdapter
    UCIEngine -->|"UCI response"| UciAdapter
    RestAdapter -->|"bestmove"| EM
    UciAdapter -->|"bestmove"| EM
    EM -->|"JSON {bestmove}"| FastAPI
    FastAPI -->|"response"| ReactApp
    ReactApp -->|"update board"| Browser
    ReactApp -.->|"loop timer Motor vs Motor"| ReactApp

    %% Click Events
    click ReactApp "https://github.com/dieg0r01/chesstrainer/tree/main/frontend/"
    click FastAPI "https://github.com/dieg0r01/chesstrainer/blob/main/main.py"
    click FastAPI "https://github.com/dieg0r01/chesstrainer/blob/main/requirements.txt"
    click EM "https://github.com/dieg0r01/chesstrainer/blob/main/engine_manager.py"
    click YAML "https://github.com/dieg0r01/chesstrainer/blob/main/config/engines.yaml"
    click Dockerfile "https://github.com/dieg0r01/chesstrainer/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0275D8,color:#0275D8;
    classDef backend fill:#DFF0D8,stroke:#5CB85C,color:#5CB85C;
    classDef adapter fill:#FCF8E3,stroke:#F0AD4E,color:#F0AD4E;
    classDef external fill:#F2DEDE,stroke:#D9534F,color:#D9534F;
    classDef config fill:#FCF8E3,stroke:#F7E6A0,color:#C09853;
    classDef docker fill:#F5F5F5,stroke:#999999,color:#333333;
```
