Saltar al contenido principal

Arquitectura Web Portal

El Portal Web es una Single Page Application (SPA) moderna construida con React y Vite. A diferencia del cliente de escritorio, esta aplicación está optimizada para ser ligera, de carga rápida y con un enfoque Mobile First, ya que la mayoría de los residentes accederán a ella desde sus teléfonos.

Estrategia de Manejo de Estado​

Para mantener la aplicación performante y fácil de mantener, separamos claramente los tipos de estado:

Server State (Data del API)​

Utilizamos TanStack Query (React Query) como estándar.

  • Cacheo: Evita peticiones redundantes al backend.
  • Revalidación: Mantiene los datos frescos en segundo plano (stale-while-revalidate).
  • Optimistic Updates: La UI se actualiza instantáneamente antes de que el servidor confirme la operación, mejorando la percepción de velocidad.

Global Client State (Sesión)​

Para datos que son puramente del cliente y globales (como el Usuario Logueado o el Tema UI), utilizamos Context API o Zustand. Evitamos Redux por ser excesivamente complejo para este caso de uso.

Patrón de "Escritura Diferida"​

Dado que el sistema opera en un entorno híbrido, la escritura de datos críticos (como reportar un pago) sigue un patrón de colas para garantizar la resiliencia.

  1. Acción: El usuario envía el formulario de pago.
  2. Feedback Inmediato: La UI muestra "Enviado exitosamente (En Cola)".
  3. Procesamiento: La petición POST no va directamente a la Base de Datos Maestra (que podría estar offline si se va la luz en el condominio). En su lugar, se envía a un endpoint de AWS SQS (Queue).
  4. Consistencia Eventual: Cuando el servidor local recupera conexión, procesa la cola y confirma el pago.

Organización de Código (DDD Lite)​

Estructuramos el proyecto por dominios funcionales en lugar de por tipos de archivo ("components", "hooks").

  • /src/modules/payments: Todo lo relacionado con pagos.
    • components/PaymentForm.tsx
    • hooks/usePaymentHistory.ts
    • services/paymentApi.ts
  • /src/modules/booking: Reserva de áreas comunes.
  • /src/lib/api: Configuración base del cliente HTTP (Axios) con interceptores para manejo de tokens y errores globales.