Documentation Index
Fetch the complete documentation index at: https://wiki.vivla.com/llms.txt
Use this file to discover all available pages before exploring further.
Home Excellence
apps/home-excellence es una aplicacion Next.js 14 para propietarios de Vivla. Muestra metricas de satisfaccion NPS, estado de calidad, tickets, protocolos y resultados del Home Review 2026.
Dominio: hx.vivla.com
Puerto: 3003
Acceso: publico via HID (Home ID) en query parameter — sin login.
Arquitectura
La app consume tres backends a traves de rewrites en Next.js:
Browser → Next.js (port 3003)
│
├─ /api/surveys/* → Monorepo Backend (port 3001)
│ └─ Home Review 2026: resultados, action plans, legacy NPS
│
├─ /api/dashboard/* → dashboard.vivla.com
│ └─ NPS scores, propiedades, factores, clientes, tickets calidad
│
└─ /api/vivla/* → api.vivla.com/v1
└─ Homes, tickets Zendesk, inspecciones, checkpoints, estancias
Rutas
| Ruta | Descripcion |
|---|
/ | Landing page para propietarios |
/home-status?hid=XXX | Dashboard principal: NPS, satisfaccion, factores, calidad, tickets |
/protocols?hid=XXX | Protocolos de limpieza y mantenimiento |
/opportunities?hid=XXX | Propuestas de mejora con tabla filtrable y formulario de envio |
/home-review?hid=XXX | Resultados del Home Review 2026 (encuestas del monorepo) |
Stack tecnico
| Tecnologia | Uso |
|---|
| Next.js 14 | Framework (App Router, standalone output) |
| React Query | Cache de estado del servidor |
| Axios | HTTP client con interceptor de auth |
| Recharts | Graficos (area, bar, radial, ring) |
| Tailwind CSS | Estilos con tokens de Vivla |
| Radix UI | Componentes (dialog, select, tooltip) |
| i18next | Internacionalizacion (ES/EN) |
| PostHog | Analytics |
| Sneak + Teodor | Fuentes custom (bundled via next/font/local) |
Variables de entorno
| Variable | Requerida | Descripcion |
|---|
NEXT_PUBLIC_VIVLA_API_TOKEN | Si | Bearer token para Vivla API |
NEXT_PUBLIC_API_URL | No | Backend monorepo. Default: http://localhost:3001/api |
DASHBOARD_API_URL | No | Dashboard API. Default: https://dashboard.vivla.com/api |
VIVLA_API_URL | No | Vivla API. Default: https://api.vivla.com/v1 |
NEXT_PUBLIC_POSTHOG_KEY | No | PostHog analytics key |
NEXT_PUBLIC_POSTHOG_HOST | No | PostHog API host |
Feature flags
| Variable | Efecto |
|---|
NEXT_PUBLIC_DISABLE_MENU | Oculta menu de navegacion |
NEXT_PUBLIC_ANONYMIZE_DATA | Anonimiza datos de propietarios |
NEXT_PUBLIC_HIDE_MAINTENANCE_LIST_BUTTON | Oculta boton de mantenimiento |
Endpoints consumidos
Monorepo Backend (publicos, sin auth)
| Endpoint | Descripcion |
|---|
GET /surveys/public/results?property={HID}&surveyType=home-review | Resultados agregados del Home Review |
GET /surveys/public/legacy-results?property={HID}&surveyType=home-review | Datos legacy NPS de Firestore |
GET /surveys/public/legacy-results/notes?property={HID} | Notas de texto de respuestas |
GET /surveys/public/action-plans?property={HID} | Planes de accion por scope |
GET /surveys/public/scores?property={HID} | Headline scores por propiedad |
GET /surveys/public/home-review-results?property={HID} | Participacion, top rated, oportunidades |
Dashboard API (via rewrite /api/dashboard/*)
- NPS scores y evolucion por propiedad
- Factores de calidad (limpieza, confort, equipamiento, mantenimiento)
- Informacion de clientes
- Tickets de calidad
Vivla API (via rewrite /api/vivla/*)
| Endpoint | Descripcion |
|---|
GET /homes/{HID} | Metadata del home (Firebase, dashboard, Zendesk) |
GET /homes/list-with-dashboard | Listado de homes con integracion dashboard |
GET /tickets?home={name} | Tickets Zendesk por propiedad |
GET /tickets/home-repair-stats/{name} | Estadisticas de reparaciones |
GET /tickets/repairs?home={name} | Tickets de reparacion |
GET /tickets/improvement-proposals?home={name} | Propuestas de mejora |
GET /checkpoints?homeName={name} | Checkpoints de mantenimiento |
GET /stays/{HID}/inspections | Inspecciones programadas |
GET /stays/{HID}/stats | Estadisticas de estancias |
GET /getAnnualHomeRevision?homeName={name} | Estado de revision anual |
GET /homes/{HID}/room-images | Imagenes por habitacion |
Funcionalidades principales
- Dashboard de satisfaccion: metricas tridimensionales (Home Excellence, Stay Experience, Design) con graficos radiales
- Evolucion NPS: graficos area/bar con escala cromatica de 11 pasos
- Calidad por habitacion: mapa visual de scores por espacio
- Tickets de calidad: tabla con estado y seguimiento
- Incidencias: reporte con severidad y resolucion
- Oportunidades: tabla filtrable con envio de propuestas y upload de imagenes
- Home Review: participacion, ratings por espacio, distribucion de sentimiento
Despliegue
- Modo: standalone (binario autocontenido)
- Plataforma: Railway / Vercel
- Auth: acceso publico via HID — sin login
