# lordtiva/snake_3d_rl architecture

> Architecture diagram of the GitHub repository lordtiva/snake_3d_rl, 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/lordtiva/snake_3d_rl
- Repository: https://github.com/lordtiva/snake_3d_rl

## Overview

Para diseñar el diagrama de arquitectura más preciso y completo para este proyecto “Snake 3D RL” dirige tu atención a las siguientes indicaciones, basadas en el árbol de archivos y el README:

##### Proyecto y propósito
- Se trata de una aplicación full-stack que combina un backend en Python (FastAPI) encargado de gestionar la lógica del juego, el entrenamiento por refuerzo de una IA y la comunicación en tiempo real, con un frontend web basado en HTML/CSS/JS para la visualización 3D (mediante Three.js) y panel de control.
- El propósito es ofrecer una plataforma interactiva que permite tanto jugar manualmente al clásico juego Snake en 3D como observar y entrenar a un agente IA, mostrando métricas en tiempo real y utilizando técnicas de RL (Stable Baselines3).

##### Análisis de la estructura del proyecto
- Componentes principales del backend:
- main.py: Punto de entrada del servidor, orquestador de las rutas y WebSockets.
- Directorio api: Define rutas REST (routes.py), esquemas y la integración de WebSockets (websocket_manager.py).
- Directorio callbacks: Contiene callbacks dedicados a la comunicación de actualizaciones vía WebSocket (por ejemplo, websocket_callback.py) y manejo de evaluación / checkpoints.
- Carpeta core: Incluye la definición del entorno de la serpiente (snake_env.py) y la lógica del entrenamiento (training_manager.py).
- dependencies.py: Facilita la inyección de dependencias y la creación de instancias únicas (singleton) para los managers.
- Componentes principales del frontend:
- index.html, CSS y módulos JavaScript: Múltiples scripts modulares (api.js, charts.js, main.js, play_solo.js, snake_visualizer.js, ui.js, watch_ai.js y websocket.js) que se encargan de la visualización 3D, interacciones con el usuario y conexión con el backend.
- Librerías externas en la carpeta libs: Incluyen archivos esenciales de Three.js, OrbitControls y otros.

##### Pautas para el diagrama
a. Componentes principales a incluir:
- Frontend:
- HTML/CSS/JS de la UI.
- Módulo de visualización 3D (snake_visualizer.js con Three.js y OrbitControls).
- Módulo de gráficos en tiempo real (usando Chart.js).
- Conexiones a WebSockets y llamadas a la API REST.
- Backend:
- Servidor FastAPI (main.py) que centraliza:
· API REST (definida en api/routes.py) para controlar el flujo de entrenamiento y acciones de la UI.
· Gestión de rutas WebSocket (websocket_manager.py) para enviar actualizaciones de entrenamiento y el estado del juego.
- Lógica de entrenamiento:
· TrainingManager (core/training_manager.py): Controla los procesos de entrenamiento en hilos separados y gestiona el ciclo de aprendizaje.
· SnakeEnv (core/snake_env.py): Entorno de juego compatible con Gymnasium.
- Callbacks y Managers:
· Callbacks para mandar actualizaciones, evaluaciones y checkpoints.
· Dependencias centralizadas (dependencies.py) para la inyección de managers.
b. Relaciones e interacciones:
- Flechas dirigidas desde el Frontend hacia el Backend para las llamadas a la API REST (inicio, parada, consulta de estado).
- Conexión bidireccional a través de WebSockets entre el Backend (mediante el WebSocketManager y callbacks) y el Frontend, para transmitir métricas y estado en tiempo real.
- Internamente, el TrainingManager lanza el proceso de entrenamiento y comunica actualizaciones a través de la cola de mensajes, mientras que los callbacks supervisan el progreso y activan la comunicación WebSocket.
c. Patrones arquitectónicos y decisiones de diseño:
- Separación de responsabilidades: Dividir claramente la lógica de negocio (entrenamiento y gestión de juego) del frontend (visualización e interacción).
- Uso de inyección de dependencias mediante un patrón singleton (dependencies.py) para evitar importaciones circulares y simplificar la administración de recursos compartidos.
- Comunicación asíncrona: Utilización de hilos en el backend para manejar la ejecución del entrenamiento sin bloquear la API, y el uso de WebSockets para actualizaciones “push”.
d. Tecnologías clave a destacar:
- Backend: Python, FastAPI, Uvicorn, Stable Baselines3, Gymnasium, PyTorch, NumPy, psutil.
- Frontend: JavaScript ES6, Three.js (con OrbitControls), Chart.js y HTML5/CSS3.

##### Guías para adaptar el diagrama al proyecto
- Para un full-stack interactivo, asegúrate de marcar visualmente la separación entre el frontend y el backend, indicando claramente:
- El flujo de información de la UI (eventos y comandos del usuario) a la API.
- Los canales de comunicación con WebSockets para actualizaciones en tiempo real.
- La integración de la lógica del entrenamiento en el backend y cómo ésta interactúa con la base del juego.
- Usa diferentes colores o formas para distinguir entre:
- Componentes de presentación (frontend).
- Componentes de procesamiento y lógica (backend).
- Elementos de comunicación (API REST, WebSockets).
- Lógica interna del entrenamiento (Training Manager, Callbacks).

##### Incluir en el diagrama
- Etiquetas claras en cada componente:
- “Frontend UI” para la vista interactiva.
- “3D Visualizer” para la renderización con Three.js.
- “API Gateway” para las rutas REST.
- “Training Manager” para la orquestación del entrenamiento vía Stable Baselines3.
- “WebSocket Manager & Callbacks” para las actualizaciones en tiempo real.
- “Snake Environment” (Gymnasium) como base del juego.
- Flechas direccionales que indiquen:
- La entrada de comandos desde la UI al backend a través de REST.
- El flujo de datos de entrenamiento y métricas desde el TrainingManager hacia el WebSocket Manager y al frontend.
- Dependencias internas entre módulos (por ejemplo, dependencies.py proveyendo instancias a los módulos de la API y Core).
- Usa por ejemplo rectángulos para módulos funcionales, nubes para indicar comunicaciones o conexiones de red, y diferentes colores para separar dominios (azul para frontend, verde para backend, naranja para comunicación).

Esta aproximación te ayudará a capturar de manera detallada cada aspecto esencial de la arquitectura: desde el inicio del servidor, el flujo de datos y comandos, los procesos asíncronos en el entrenamiento, hasta la representación visual vía Three.js y Chart.js. No dudes en incluir tantos componentes y conexiones como sean relevantes para reflejar a detalle el sistema modular y la interacción en tiempo real que hace único este proyecto.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Backend"
        API_GW("API Gateway"):::backend
        API_REST("API REST"):::backend
        WS_MANAGER("WebSocket Manager"):::backend
        DEP("Dependencies"):::backend
        WS_CB("WebSocket Callbacks"):::backend
        TRAIN_MGR("Training Manager"):::backend
        SNAKE_ENV("Snake Environment"):::backend
    end

    subgraph "Frontend"
        FE_UI("Frontend UI"):::frontend
        API_CLIENT("API Client"):::communication
        WS_CLIENT("WebSocket Client"):::communication
        VIS3D("3D Visualizer"):::frontend
        THREEJS("Three.js Lib"):::frontend
        ORBIT("OrbitControls"):::frontend
        CHARTS("Real-time Charts"):::frontend
        UI_CONTROL("UI Control & Interaction"):::frontend
        AI_MONITOR("AI Monitoring"):::frontend
    end

    %% Frontend interactions
    FE_UI -->|"sendsCommands"| API_CLIENT
    FE_UI -->|"sendsCommands"| WS_CLIENT
    FE_UI --> VIS3D
    FE_UI --> CHARTS
    FE_UI --> UI_CONTROL
    FE_UI --> AI_MONITOR

    VIS3D --> THREEJS
    VIS3D --> ORBIT

    %% Backend interactions
    API_GW -->|"routes"| API_REST
    API_GW -->|"manages"| WS_MANAGER

    DEP --> API_REST
    DEP --> WS_MANAGER
    DEP --> TRAIN_MGR

    TRAIN_MGR -->|"uses"| SNAKE_ENV
    TRAIN_MGR -->|"sendsUpdates"| WS_MANAGER

    WS_MANAGER -->|"forwards"| WS_CB
    WS_CB -->|"pushesUpdates"| WS_CLIENT

    %% Communication between Frontend and Backend
    API_CLIENT -->|"RESTcall"| API_GW

    %% Click Events (paths are for click events only)
    click API_GW "https://github.com/lordtiva/snake_3d_rl/blob/main/backend/main.py"
    click API_REST "https://github.com/lordtiva/snake_3d_rl/blob/main/backend/api/routes.py"
    click WS_MANAGER "https://github.com/lordtiva/snake_3d_rl/blob/main/backend/api/websocket_manager.py"
    click DEP "https://github.com/lordtiva/snake_3d_rl/blob/main/backend/dependencies.py"
    click WS_CB "https://github.com/lordtiva/snake_3d_rl/blob/main/backend/callbacks/websocket_callback.py"
    click SNAKE_ENV "https://github.com/lordtiva/snake_3d_rl/blob/main/backend/core/snake_env.py"
    click TRAIN_MGR "https://github.com/lordtiva/snake_3d_rl/blob/main/backend/core/training_manager.py"
    click FE_UI "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/index.html"
    click VIS3D "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/js/snake_visualizer.js"
    click THREEJS "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/libs/three.module.js"
    click ORBIT "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/libs/controls/OrbitControls.js"
    click CHARTS "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/js/charts.js"
    click API_CLIENT "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/js/api.js"
    click WS_CLIENT "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/js/websocket.js"
    click UI_CONTROL "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/js/main.js"
    click AI_MONITOR "https://github.com/lordtiva/snake_3d_rl/blob/main/frontend/js/watch_ai.js"

    %% Styles
    classDef backend fill:#c8e6c9,stroke:#256029,stroke-width:2px;
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef communication fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
```
