# rflvz/chess-app architecture

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

- Interactive diagram: https://gitdiagram.com/rflvz/chess-app
- Repository: https://github.com/rflvz/chess-app

## Overview

Para dibujar un diagrama de arquitectura claro y preciso para este proyecto “Chess App – Ajedrez vs Bot 400 ELO”, sigue estas indicaciones alineadas con su estructura y propósito:

##### Identificación del tipo de proyecto y propósito
- Es una aplicación full-stack híbrida de tres servicios desacoplados:
1. Chess Engine (Python + Flask)
2. Backend API (Node.js/TypeScript + Express + Socket.IO)
3. Frontend Web (React + TypeScript + Vite + TailwindCSS)
- Objetivo: permitir al usuario jugar ajedrez contra un bot (~400 ELO) en tiempo real.

##### Análisis de la estructura de carpetas
- Top-level:
· chess-engine/ → motor de ajedrez en Python
· backend/      → API REST + WebSocket en Node.js/TS
· frontend/     → SPA React/TS
· docs/, scripts/, tests/ → documentación, utilidades y suites de prueba
- Patrón MVC/”layered”:
– backend/src/routes → rutas
– backend/src/controllers → controladores
– backend/src/services → lógica de negocio y cliente HTTP al motor Python
– frontend/src/components, hooks, services, store → UI, lógica de hooks, cliente API y estado
- No hay base de datos externa: el estado de la partida se mantiene en memoria por el backend.

##### Base del diagrama de alto nivel
a. Componentes principales (cada uno representado por un contenedor o “nube”):
1. Browser / Cliente Web
2. Frontend React (Puerto 5173)
3. Backend Node.js/Express/Socket.IO (Puerto 3000)
4. Python Chess Engine (Flask) (Puerto 5000)
5. (Opcional) Scripts de orchestration y suites de tests (E2E, unitarios, performance)
b. Relaciones e interacciones:
- Browser ↔ Frontend: UI y llamada interna a servicios REST / WS
- Frontend ↔ Backend:
· HTTP REST “/api/game/…” → controladores
· WebSocket events “game:join / game:move” → backend/src/socket
- Backend ↔ Chess Engine:
· HTTP POST /get-move (cliente en backend/src/services/chessEngineClient.ts)
- Tests externos (E2E Playwright, scripts performance) interactúan con los puertos y APIs expuestas.
c. Patrones y principios:
- Microservicios ligeros: cada servicio en su puerto
- Capas bien definidas (routes → controllers → services)
- Comunicación síncrona HTTP + asíncrona WebSocket
- Hooks y state management (Zustand/MobX/Redux-like) en frontend
d. Tecnologías clave:
– React 18 + TypeScript + Vite + TailwindCSS
– Express 18+ + TypeScript + Socket.IO
– Flask + python-chess
– Jest/Vitest/Pytest/Playwright para testing
– Scripts de PowerShell / Bash para orquestación

##### Guía para un diagrama full-stack
- Dibuja tres capas horizontales:
Capa 1 (UI): Browser ↔ Frontend
Capa 2 (API): Backend
Capa 3 (Motor): Chess Engine
- Para cada capa, incluye subcomponentes internos si conviene (p. ej., en Backend muestra Routes, Controllers, Services, SocketHub).
- Señala las comunicaciones con flechas dirigidas:
→ REST calls (etiquetar “HTTP POST /api/game/start”, etc.)
↔ WebSocket (“game:join”, “game:updated”, etc.)
→ Motor Python (POST /get-move)
- Usa colores o formas:
· Azul para UI y componentes React
· Verde para capa de negocio (Backend)
· Naranja para motor Python
· Gris o punteado para tests/orquestación

##### Elementos imprescindibles
- Etiquetas claras: nombres de servicios, puertos, endpoints clave
- Flechas con direccionalidad y nombres de eventos o rutas
- Inclusión opcional de “Scripts de arranque” y “Suites de tests” como roles externos

##### Nivel de detalle recomendado
- No sobrecargar con cada archivo: agrupa por carpetas funcionales
- Captura flujos de datos esenciales (UI→API→Engine→UI)
- Añade notas breves (p. ej., “Alpha-Beta search”, “Minimax depth 2–3”) si ayuda a comprender responsabilidades

Siguiendo esta guía, el diagrama mostrará de manera inmediata la separación de responsabilidades, los flujos de datos y las tecnologías involucradas en cada componente, facilitando la comprensión y discusión con stakeholders o nuevos integrantes del equipo.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% UI Layer
  subgraph "UI Layer"
    Browser["Browser / Client"]:::ui
    subgraph "Frontend (frontend/)"
      FE_main["main.tsx"]:::ui
      FE_App["App.tsx"]:::ui
      FE_Components["components/"]:::ui
      FE_Hooks["hooks/"]:::ui
      FE_Services["services/api.ts"]:::ui
      FE_Store["store/gameStore.ts"]:::ui
    end
    Browser -->|"UI & events"| FE_App
  end

  %% API Layer
  subgraph "API Layer"
    subgraph "Backend (backend/)"
      BE_Index["src/index.ts"]:::api
      BE_Routes["src/routes/"]:::api
      BE_Controllers["src/controllers/"]:::api
      BE_Services["src/services/"]:::api
      BE_Socket["src/socket/"]:::api
    end
    FE_App -->|"REST / WebSocket"| BE_Index
  end

  %% Engine Layer
  subgraph "Engine Layer"
    subgraph "Chess Engine (chess-engine/)"
      CE_App["app.py"]:::engine
      CE_Engine["engine.py"]:::engine
      CE_Bot["bot.py"]:::engine
      CE_Evaluator["evaluator.py"]:::engine
      CE_Mock["mock_server.py"]:::engine
      CE_Tests["tests/"]:::engine
    end
    BE_Services -->|"HTTP POST /get-move"| CE_App
  end

  %% Orchestration & Tests
  subgraph "Orchestration & Tests"
    Scripts["scripts/"]:::misc
    Tests["tests/"]:::misc
  end
  Scripts -.-> BE_Index
  Scripts -.-> CE_App
  Tests -.-> FE_App
  Tests -.-> BE_Index
  Tests -.-> CE_App

  %% Click Events
  click CE_App "https://github.com/rflvz/chess-app/blob/master/chess-engine/app.py"
  click CE_Engine "https://github.com/rflvz/chess-app/blob/master/chess-engine/engine.py"
  click CE_Bot "https://github.com/rflvz/chess-app/blob/master/chess-engine/bot.py"
  click CE_Evaluator "https://github.com/rflvz/chess-app/blob/master/chess-engine/evaluator.py"
  click CE_Mock "https://github.com/rflvz/chess-app/blob/master/chess-engine/mock_server.py"
  click CE_Tests "https://github.com/rflvz/chess-app/tree/master/chess-engine/tests/"

  click BE_Index "https://github.com/rflvz/chess-app/blob/master/backend/src/index.ts"
  click BE_Routes "https://github.com/rflvz/chess-app/tree/master/backend/src/routes/"
  click BE_Controllers "https://github.com/rflvz/chess-app/tree/master/backend/src/controllers/"
  click BE_Services "https://github.com/rflvz/chess-app/tree/master/backend/src/services/"
  click BE_Socket "https://github.com/rflvz/chess-app/tree/master/backend/src/socket/"

  click FE_main "https://github.com/rflvz/chess-app/blob/master/frontend/src/main.tsx"
  click FE_App "https://github.com/rflvz/chess-app/blob/master/frontend/src/App.tsx"
  click FE_Components "https://github.com/rflvz/chess-app/tree/master/frontend/src/components/"
  click FE_Hooks "https://github.com/rflvz/chess-app/tree/master/frontend/src/hooks/"
  click FE_Services "https://github.com/rflvz/chess-app/blob/master/frontend/src/services/api.ts"
  click FE_Store "https://github.com/rflvz/chess-app/blob/master/frontend/src/store/gameStore.ts"

  click Scripts "https://github.com/rflvz/chess-app/tree/master/scripts/"
  click Tests "https://github.com/rflvz/chess-app/tree/master/tests/"

  %% Styles
  classDef ui fill:#D0E8FF,stroke:#0366D6,color:#000;
  classDef api fill:#DFF8D8,stroke:#228B22,color:#000;
  classDef engine fill:#FFE5B4,stroke:#FF8C00,color:#000;
  classDef misc fill:#F0F0F0,stroke:#888888,color:#000;
```
