README.md

metadata

title: Hyper Reality Room Visualizer
emoji: 🏠
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

Hyper Reality Room Visualizer — PoC SaaS

Visualizador de habitaciones embebido como SaaS mediante iframe. Los clientes reciben una API key y un snippet HTML; el backend genera un token temporal y carga el visualizador en un iframe.

Estructura del repositorio

Prueba-PoC/
├── backend/            # FastAPI — API, autenticación, SAM2, texturas
│   ├── main.py
│   ├── routers/
│   ├── services/
│   ├── requirements.txt
│   ├── .env            # variables locales (no se sube a git)
│   └── Dockerfile      # usado solo por docker-compose (desarrollo local)
├── frontend/           # React + Vite — visualizador embebido
│   ├── src/
│   ├── package.json
│   └── dist/           # generado por npm run build (ignorado en git)
├── Dockerfile          # multi-stage para HuggingFace Spaces
├── docker-compose.yml  # entorno local con Docker
└── README.md

Arquitectura

Cliente externo (HTML del cliente)
  └─► widget.js          — se auto-descarga desde el servidor
        └─► POST /api/token   — obtiene token temporal
              └─► <iframe src="/app?token=...">
                    └─► FastAPI sirve index.html del SPA React
                          └─► SPA carga assets desde /assets/...

El backend expone:

Endpoint	Descripción
POST /api/token	Genera token temporal (TTL 5 min)
GET /config	Devuelve datos del cliente validando token
POST /session/start	Registra sesión activa
GET /widget.js	Script que el cliente externo incluye en su HTML
GET /admin	Panel de gestión de API keys
GET /app	Punto de entrada del SPA React
POST /api/generate-key	Crea nueva API key (persiste en MongoDB)
DELETE /api/keys/{id}	Elimina API key

Variables de entorno

Crea el archivo backend/.env (ya está en .gitignore):

MONGODB_URI=mongodb+srv://<usuario>:<password>@<cluster>.mongodb.net/

En HuggingFace Spaces: Settings → Repository secrets → MONGODB_URI.

Desarrollo local

Hay dos opciones: con o sin Docker.

Opción A — Sin Docker (recomendado para desarrollo activo)

Levanta backend y frontend en terminales separadas para obtener hot reload en ambos.

Terminal 1 — Backend:

cd backend
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # Mac / Linux
pip install -r requirements.txt
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 — Frontend:

cd frontend
npm install
npm run dev

URLs disponibles:

URL	Qué muestra
http://localhost:5173/app	SPA React con hot reload (Vite dev server)
http://localhost:8000/admin	Panel de API keys
http://localhost:8000/preview	Vista previa del iframe

El frontend en localhost:5173 proxea automáticamente /api, /seg, /uploads y /widget.js hacia localhost:8000 (configurado en vite.config.ts).

Opción B — Con Docker Compose

Levanta solo el backend en contenedor. Útil para probar la integración completa.

docker compose up --build

Accede en http://localhost:8000. El frontend se sirve desde frontend/dist montado como volumen — necesitas haber ejecutado npm run build antes.

Integración completa (backend sirve el frontend)

Cuando quieres probar exactamente como quedaría en producción:

# 1. Construir el frontend
cd frontend
npm run build

# 2. Levantar el backend (sirve frontend/dist en /app)
cd ../backend
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Abre http://localhost:8000/app — el backend sirve los assets estáticos desde frontend/dist.

Despliegue en HuggingFace Spaces

El Dockerfile de la raíz es el que usa HuggingFace. Hace dos cosas:

1. Stage 1 (Node): ejecuta npm run build y produce frontend/dist
2. Stage 2 (Python): instala dependencias del backend y copia el dist del stage 1

No necesitas subir frontend/dist al repositorio — Docker lo genera automáticamente en cada push.

git add .
git commit -m "tu mensaje"
git push

HuggingFace detecta el push y reconstruye el contenedor.

URL del Space: https://huggingface.co/spaces/eduardo4547/hyper-reality-visualizer

Flujo del widget para clientes externos

El cliente externo pega este snippet en su HTML (se obtiene desde /admin):

<div id="contenedor-saas" data-client-id="CLIENTE_XXXXXXXX"></div>
<script src="https://<tu-space>.hf.space/widget.js"></script>

El script:

1. Lee data-client-id del div
2. Llama POST /api/token con ese ID
3. Inyecta un <iframe> apuntando a /app?token=<token>

Comandos útiles

# Backend
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Frontend — desarrollo
npm run dev

# Frontend — producción
npm run build

# Docker local
docker compose up --build
docker compose down