How lordtiva/snake_3d_rl works
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.