Hugging Face's logo

Spaces:
eduardo4547
/
hyper-reality-visualizer
Running

App Files Community
hyper-reality-visualizer / frontend /FRONTEND_DOCUMENTATION.md
eduardo4547's picture
eduardo4547
Upload 150 files
cb5d9d0 verified
preview code
|
raw
history blame contribute delete
5.97 kB

Documentación del Frontend

Este documento describe la arquitectura, las rutas, los estados, los hooks y los componentes principales del frontend React + TypeScript ubicado en frontend/.

1. Visión general

El frontend está construido con:

  • React 19
  • TypeScript
  • Vite
  • React Router DOM
  • Zustand para estado global
  • @tanstack/react-query para consultas asíncronas
  • Tailwind CSS para estilos
  • Arquitectura basada en características (features)

La carpeta principal de la aplicación es frontend/src.

2. Estructura de carpetas clave

  • src/main.tsx - punto de entrada, configuración de router y React Query
  • src/App.tsx - rutas principales de la aplicación
  • src/store - estado global con Zustand
  • src/api - cliente y funciones de API centralizadas
  • src/hooks - hooks reutilizables del frontend
  • src/features - features organizadas por dominio
  • src/utils - utilidades compartidas
  • src/types.ts - tipos globales de la aplicación

3. Rutas principales

src/App.tsx define las rutas:

  • / → RoomSetup
  • /visualizer → RoomVisualizer
  • /settings → SettingsPage
  • * → redirección a /

4. Estado global (Zustand)

src/store/useAppStore.ts almacena:

  • previewImage - URL de la imagen cargada
  • uploadMessage - estado de mensaje de subida
  • openProductId - producto seleccionado en RoomVisualizer
  • viewMode - vista actual de productos en el visualizador (grid o list)

Funciones disponibles:

  • setPreviewImage
  • setUploadMessage
  • setOpenProductId
  • setViewMode
  • reset

5. Cliente API centralizado

src/api/client.ts incluye:

  • DEV_API_BASE y API_BASE para la URL del backend
  • getApiBase / buildApiUrl para construir endpoints
  • fetchClientConfig para obtener configuración de cliente
  • uploadRoomImage para subir imágenes al servidor
  • startSession para iniciar una sesión remota

Esta capa permite mantener la URL del backend en un solo lugar y soportar un token de desarrollo automático.

6. Hooks compartidos

src/hooks/useUploadImage.ts

  • Maneja la subida de imágenes al backend
  • Controla isUploading y uploadError
  • Envuelve uploadRoomImage del cliente API

7. Tipos globales

src/types.ts declara tipos comunes como:

  • ClientData
  • RouteItem
  • Product

El tipo Product se usa en el visualizador para productos de catálogo.

8. Feature: Room Setup

Archivos

  • src/features/roomSetup/RoomSetup.tsx
  • src/features/roomSetup/roomSetupHooks.ts
  • src/features/roomSetup/RoomSetupComponents.tsx
  • src/data/roomSetupData.ts

Comportamiento

RoomSetup es la página principal donde el usuario puede:

  • subir una imagen arrastrando o seleccionando archivo
  • ver una vista previa de la imagen
  • iniciar la navegación hacia el visualizador
  • ver habitaciones de demostración filtrables

useRoomSetup

Este hook abstrae toda la lógica de:

  • drag & drop
  • selección de archivos
  • subida de imagen
  • gestión de estados de carga
  • navegación con useNavigate

Componentes auxiliares

  • FilterButton - botón de filtrado por categoría
  • RoomCard - tarjeta de habitación de demostración

9. Feature: Room Visualizer

Archivos

  • src/features/roomVisualizer/RoomVisualizer.tsx
  • src/features/roomVisualizer/roomVisualizerHooks.ts
  • src/features/roomVisualizer/roomVisualizerData.ts
  • src/features/roomVisualizer/ProductCards.tsx

Comportamiento

RoomVisualizer muestra:

  • la imagen subida por el usuario
  • controles de zoom y arrastre de la imagen
  • lista / grid de productos para aplicar en la habitación
  • selección de producto y detalles asociados

useRoomVisualizer

Extrae la lógica de visualización de productos:

  • modo de vista (grid / list)
  • búsqueda y filtros básicos
  • producto seleccionado
  • manejo de selección de producto
  • agrupación en chunks para renderizar grillas

Datos de productos

  • roomVisualizerData.ts contiene el catálogo de productos estáticos usados en la vista.

Componentes

  • ProductGroupCard - renderiza un grupo de 3 productos en grid
  • IndividualProductCard - renderiza un producto en modo lista

10. Feature: Settings

Archivo

  • src/features/settings/SettingsPage.tsx

Comportamiento

La página de configuración permite al usuario:

  • definir la URL base de la API
  • activar / desactivar la lista de rutas en el viewer
  • definir token de desarrollo automático

Soporte de almacenamiento

src/utils/settings.ts gestiona:

  • carga de localStorage
  • guardado de configuración
  • valores por defecto

11. Componentes comunes

  • src/components/ui/LoadingScreen.tsx - pantalla de carga reutilizable

12. Flujo principal de la app

  1. Usuario entra en /
  2. Sube una imagen en RoomSetup
  3. Se crea una vista previa y se almacena en Zustand
  4. Se navega a /visualizer
  5. RoomVisualizer usa la imagen y muestra productos
  6. El usuario filtra, busca y selecciona productos
  7. SettingsPage permite ajustar la API y opciones de la app

13. Cómo ejecutar el frontend

Desde frontend/:

npm install
npm run dev

Construcción de producción:

npm run build

14. Posibles mejoras futuras

  • mover roomVisualizerProducts a una API real o servicio de datos
  • extraer más componentes presentacionales del visualizador
  • usar React Query para cargar configuración del cliente en lugar de gestión manual
  • añadir tests unitarios para hooks y componentes
  • normalizar rutas y nombres de features

15. Observaciones adicionales

  • La base API se controla desde VITE_API_BASE_URL o DEV_API_BASE en desarrollo.
  • La aplicación usa queryClient de React Query, aunque hoy solo se usa para potenciales fetches futuros.
  • El estado global es ligero y se usa principalmente para compartir imagen previa, modo de vista y selección de producto.