README.md

---
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`):

```env
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:**

```bash
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:**

```bash
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.

```bash
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:

```bash
# 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.

```bash
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`):

```html
<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

```bash
# 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
```