karibeo_backend_admin/docs/ARCHITECTURE.md

🏗️ Arquitectura del Sistema Karibeo

Visión General

Karibeo está construido siguiendo una arquitectura modular de frontend con separación clara de responsabilidades y patrones de diseño modernos.

Diagrama de Arquitectura

┌─────────────────────────────────────────────────────────────┐
│                      PRESENTACIÓN                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Tourist │  │  Hotel   │  │Restaurant│  │ Commerce │   │
│  │   App    │  │   POS    │  │   POS    │  │   POS    │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │          Admin Dashboard & Control Panel             │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                    CAPA DE NEGOCIO                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Contexts │  │  Hooks   │  │ Services │  │Validation│   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                  CAPA DE DATOS                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │   API    │  │  Cache   │  │ LocalSt  │  │  State   │   │
│  │  Client  │  │(TanStack)│  │ (tokens) │  │Management│   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                  BACKEND API REST                            │
│        https://karibeo.lesoluciones.net:8443/api/v1         │
└─────────────────────────────────────────────────────────────┘

Capas de la Aplicación

1. Capa de Presentación (UI)

Componentes Principales

src/components/
├── ui/              # Componentes base (shadcn)
├── admin/           # Componentes administrativos
├── hotel/           # Componentes hoteleros
├── restaurant/      # Componentes de restaurante
├── tourist/         # Componentes para turistas
└── shared/          # Componentes compartidos

Responsabilidades:

• Renderizado de UI
• Interacción con el usuario
• Delegación de lógica a hooks y contexts

Patrones Utilizados:

• Composition Pattern: Composición de componentes pequeños
• Compound Components: Para componentes complejos como Forms
• Render Props: Para lógica reutilizable

2. Capa de Lógica de Negocio

React Contexts

src/contexts/
├── AuthContext.tsx       # Autenticación y sesión
├── CartContext.tsx       # Carrito de compras
├── CurrencyContext.tsx   # Gestión de monedas
└── LanguageContext.tsx   # Internacionalización

Responsabilidades:

• Estado global de la aplicación
• Lógica de negocio compartida
• Sincronización de estado

Custom Hooks

src/hooks/
├── useAdminData.ts           # Datos de administración
├── useBooking.ts             # Lógica de reservas
├── useChannelManager.ts      # Channel manager
├── useRolesPermissions.ts    # Roles y permisos
└── useEmergencyData.ts       # Sistema de emergencias

Responsabilidades:

• Encapsular lógica reutilizable
• Gestión de efectos secundarios
• Integración con APIs

3. Capa de Servicios (API)

Servicios API

src/services/
├── adminApi.ts           # API de administración
├── emergencyApi.ts       # API de emergencias
├── bookmarkApi.ts        # API de favoritos
├── chatApi.ts            # API de mensajería
├── configApi.ts          # API de configuración
├── paymentService.ts     # Servicio de pagos
├── reviewService.ts      # Servicio de reseñas
└── tourismService.ts     # Servicios turísticos

ApiClient Class:

class ApiClient {
  - baseUrl: string
  - request<T>(endpoint, options): Promise<T>
  + get<T>(endpoint): Promise<T>
  + post<T>(endpoint, data): Promise<T>
  + put<T>(endpoint, data): Promise<T>
  + delete<T>(endpoint): Promise<T>
  + postForm<T>(endpoint, data): Promise<T>
}

Características:

• Interceptores de request/response
• Refresh token automático
• Manejo centralizado de errores
• Timeout configurable (30s)
• Retry logic para 401 errors

4. Capa de Validación

src/lib/validation.ts

Schemas Zod:

• loginSchema: Validación de login
• registerSchema: Validación de registro
• profileUpdateSchema: Actualización de perfil
• contactFormSchema: Formularios de contacto
• reviewSchema: Validación de reseñas
• searchSchema: Validación de búsquedas

Flujo de Datos

Flujo de Autenticación

┌─────────┐        ┌──────────────┐        ┌────────────┐
│ SignIn  │───────>│ AuthContext  │───────>│  adminApi  │
│  Form   │ submit │   .login()   │  POST  │ /auth/login│
└─────────┘        └──────────────┘        └────────────┘
                           │                       │
                           │                       ▼
                           │                ┌────────────┐
                           │<───────────────│  Backend   │
                           │   JWT Token    │    API     │
                           │                └────────────┘
                           ▼
                    ┌─────────────┐
                    │ localStorage │
                    │ - token      │
                    │ - user data  │
                    └─────────────┘

Flujo de Reservas

┌──────────┐        ┌──────────────┐        ┌────────────┐
│ Booking  │───────>│  useBooking  │───────>│ bookingApi │
│   Form   │ submit │    hook      │  POST  │/reservations│
└──────────┘        └──────────────┘        └────────────┘
                           │                       │
                           │                       ▼
                           │                ┌────────────┐
                           │<───────────────│  Backend   │
                           │  Confirmation  │    API     │
                           │                └────────────┘
                           ▼
                    ┌─────────────┐
                    │ TanStack    │
                    │   Query     │
                    │   Cache     │
                    └─────────────┘

Gestión de Estado

Estado Local (Component State)

const [formData, setFormData] = useState({...});

Uso: Estado temporal de componentes individuales

Estado Global (Context)

const { user, login, logout } = useAuth();

Uso: Estado compartido entre múltiples componentes

Estado del Servidor (TanStack Query)

const { data, isLoading } = useQuery({
  queryKey: ['users'],
  queryFn: () => adminApi.getAllUsers()
});

Uso: Cache y sincronización de datos del servidor

Patrones de Diseño

1. Container/Presentational Pattern

// Container (lógica)
const UsersContainer = () => {
  const { users, loading } = useAdminData();
  return <UsersList users={users} loading={loading} />;
};

// Presentational (UI)
const UsersList = ({ users, loading }) => {
  if (loading) return <Spinner />;
  return <div>{users.map(...)}</div>;
};

2. Compound Components Pattern

<Form>
  <Form.Field name="email">
    <Form.Label>Email</Form.Label>
    <Form.Input type="email" />
    <Form.Error />
  </Form.Field>
</Form>

3. Custom Hook Pattern

const useBooking = () => {
  const [bookings, setBookings] = useState([]);
  const createBooking = async (data) => {...};
  return { bookings, createBooking };
};

4. Higher-Order Component (HOC) Pattern

const ProtectedRoute = ({ children }) => {
  const { isAuthenticated } = useAuth();
  return isAuthenticated ? children : <Navigate to="/login" />;
};

Estrategia de Routing

Estructura de Rutas

/                          # Landing page
/sign-in                   # Login
/sign-up                   # Registro
/explore                   # Exploración pública
/listing-details/:id       # Detalles de listado

/dashboard                 # Dashboard principal (turista)
/dashboard/admin           # Panel de administración
/dashboard/admin?tab=...   # Tabs de administración

/dashboard/hotel/*         # Rutas hoteleras
/dashboard/restaurant/*    # Rutas de restaurante
/dashboard/commerce/*      # Rutas de comercio

/dashboard/roles-permissions  # Gestión de roles
/dashboard/crm/*          # CRM
/dashboard/commissions/*  # Comisiones

Protección de Rutas

<Route element={<ProtectedRoute />}>
  <Route path="/dashboard" element={<Dashboard />} />
</Route>

Optimizaciones de Performance

Code Splitting

const AdminDashboard = lazy(() => import('./pages/AdminDashboard'));

Memoization

const MemoizedComponent = memo(ExpensiveComponent);
const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);
const memoizedCallback = useCallback(() => doSomething(a, b), [a, b]);

Virtual Scrolling

Para listas largas de datos (usuarios, reservas, etc.)

Image Optimization

• Lazy loading con loading="lazy"
• Formatos modernos (WebP)
• Responsive images

Seguridad

Medidas Implementadas

1. Validación de Inputs: Todos los formularios usan Zod
2. Sanitización: Prevención de XSS
3. HTTPS Only: Todas las comunicaciones encriptadas
4. JWT Tokens: Autenticación stateless
5. Refresh Tokens: Rotación automática
6. CORS: Configurado en backend
7. Rate Limiting: En endpoints críticos

Consideraciones de Seguridad

⚠️ IMPORTANTE: La verificación de roles actual es client-side. Para producción se requiere:

• Tabla user_roles separada en la base de datos
• Verificación de permisos en cada endpoint del backend
• Row Level Security (RLS) policies

Escalabilidad

Preparación para Escala

1. Modularización: Código organizado en módulos independientes
2. Lazy Loading: Carga diferida de componentes
3. API Caching: TanStack Query con estrategias de cache
4. CDN Ready: Assets estáticos optimizados
5. Micro-frontends Ready: Arquitectura permite separación futura

Métricas de Performance

• First Contentful Paint: < 1.5s
• Time to Interactive: < 3.5s
• Bundle Size: ~500KB (gzipped)

Testing Strategy

Unit Tests

describe('useAuth', () => {
  it('should login successfully', async () => {
    // test implementation
  });
});

Integration Tests

describe('BookingFlow', () => {
  it('should complete booking', async () => {
    // test implementation
  });
});

E2E Tests (Cypress/Playwright)

describe('Complete User Journey', () => {
  it('should allow user to make a reservation', () => {
    // test implementation
  });
});

Monitoring y Observabilidad

Logs

• Console logs en desarrollo
• Sentry/LogRocket en producción

Analytics

• Google Analytics 4
• Custom events tracking
• User behavior analysis

Error Tracking

• Error boundaries en componentes críticos
• Reportes automáticos a Sentry

Deployment Pipeline

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│   Git    │───>│  Build   │───>│   Test   │───>│  Deploy  │
│  Commit  │    │  (Vite)  │    │ (Jest)   │    │(Lovable) │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

Roadmap Técnico

Corto Plazo (3 meses)

• Implementar testing completo
• Optimizar bundle size
• Mejorar accesibilidad (WCAG 2.1 AA)
• Implementar PWA completa

Medio Plazo (6 meses)

• Migrar a Server Components (React 19)
• Implementar GraphQL
• WebSockets para real-time
• Backend propio (Node.js/NestJS)

Largo Plazo (12 meses)

• Micro-frontends architecture
• Mobile apps (React Native)
• AI/ML integration
• Blockchain para pagos

---

Última actualización: 2025-01-12
Mantenedores: Equipo de Desarrollo Karibeo