​

Arquitectura

​

Estructura de carpetas

api/                    Funciones serverless de Vercel (reportes de feedback)
src/
  main.tsx              Providers globales + router
  router/               Rutas, guards de sesión y de permisos
  pages/{Page}/         Una carpeta por ruta; compone features
  features/{feature}/   Lógica por dominio
    api/requests/       Funciones HTTP contra vivla-api
    api/dtos/           Schemas Zod + mappers a modelos de dominio
    queries/            Hooks de TanStack Query (lectura y mutaciones)
    components/         Componentes del dominio
    hooks/ constants/ utils/ state/
  core/{domain}/models/ Modelos de dominio, independientes de la API
  components/           UI compartida (Table, Sheet, Dialog, DatePicker…)
  components/layouts/   PortalRoot, Sidebar, Header
  config/               env, paths, routes, theme, i18n, queryClient, sentry, analytics
  lib/                  apiClient, toast, CSV, subida de documentos, utilidades
  hooks/                Hooks transversales (móvil, debounce, versión)
  assets/locales/es/    Traducciones, un namespace por feature

​

Flujo de una petición

pages/CreateUser
  └─ useCreateUser()                   features/users/queries/createUser.ts
       └─ createUser(payload)          features/users/api/requests/createUser.ts
            └─ apiClient.post("/v2/admin/users/create", …)
                 └─ UserSummaryApiDto.mapper.parseMap(response.data.data)
                      └─ User                    core/users/models/User.ts

1. Request: una función por endpoint en api/requests/. Traduce del payload del panel al formato de la API.
2. DTO: el schema Zod valida la respuesta y el mapper la convierte en un modelo de core/. Se crea con Mapper.create(schema, mapping) (src/core/shared/Mapper.ts). Si la API cambia su contrato, falla aquí y Sentry lo etiqueta como contract_violation.
3. Query: el hook de TanStack Query envuelve la request. Las mutaciones invalidan las queries relacionadas y muestran un toast en español. Muchas registran también un evento de analytics.
4. Página: usa el hook y pinta skeletons mientras carga.

​

El cliente HTTP

• vivla-api responde con un sobre { code, msg, data }. code: 20 es éxito. Cualquier otro código se convierte en un ApiError.
• Si la API devuelve code: 41 (token inválido) o un HTTP 401, el cliente fuerza un refresh del token y reintenta la petición una sola vez.
• Los códigos esperados (41, 43, 44, 49) no se envían a Sentry. El resto sí. Ver Observabilidad.

​

Router y guards

/login, /forgot-password         UnprotectedRoute
/  (PortalRoot: Sidebar + Header) ProtectedRoute → si no hay sesión, /login?redirect=…
  ├─ index            PermissionGuard(read:exchanges)
  ├─ homes…           PermissionGuard(read:homes / edit:homes)
  ├─ bookings…        PermissionGuard(read:bookings / edit:bookings)
  ├─ users…           PermissionGuard(read:users / edit:users)
  ├─ calendars…       PermissionGuard(read:calendar-manager)
  └─ unauthorized     Sin permisos para ninguna sección
*                                 Redirige a /login

• Si no tienes el permiso de una ruta, PermissionBasedRedirect te lleva a la primera sección del menú a la que sí tienes acceso. Si no tienes ninguna, acabas en /unauthorized.
• Las rutas se construyen siempre con src/config/paths.ts (paths.bookings.getHref({ user })), nunca con strings sueltos.
• src/config/routes.ts (navigableRoutes) define las entradas del menú lateral y el permiso de cada una. Las etiquetas salen de locales/es/sidebar.json.

​

Estado en la URL

​

Providers globales

​

Autenticación

• Dominios permitidos: el login y la recuperación de contraseña solo aceptan correos de los dominios de allowedEmailDomains (features/auth/constants).
• Almacenamiento: el access token y el refresh token se guardan en localStorage con Zustand persist. Las pestañas se sincronizan entre sí con el evento storage.
• Refresh proactivo: se refresca 2 minutos antes de caducar, o si el token tiene más de 10 minutos. También se comprueba cada minuto y al volver el foco a la pestaña. Un lock de navigator.locks evita que dos pestañas refresquen a la vez.
• Sesión caducada: si Auth0 rechaza el refresh con un 4xx, se borra la sesión y aparece el toast Tu sesión ha caducado. Vuelve a iniciar sesión.
• Permisos: salen del claim permissions del access token. Ver Permisos.

​

Convenciones de código

• TypeScript estricto: sin any. type antes que interface, salvo para props (interface ComponentNameProps).
• Estilos: styled-components en un Styles.ts junto al componente. Todo en rem. Sufijo Wrapper, nunca Container. Props transitorias con $ ($isOpen). Colores desde el tema.
• Imports: primero los estilos con imports nombrados desde ./Styles (nunca import * as S). Después librerías, tipos, assets e imports locales.
• React Query: query keys en kebab-case (["booking-details", id]) y throwOnError: false. Las mutaciones invalidan lo relacionado y muestran un toast en español.
• Formularios: React Hook Form + Zod, con el schema en schema.ts y mensajes en español.
• Textos: nada hardcodeado. Todo pasa por i18next, con un namespace por feature en src/assets/locales/es/.
• Carga: siempre skeletons (react-loading-skeleton) con la misma forma que el componente final.

​

Añadir un módulo nuevo