# 🏗️ 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
```typescript
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
```typescript
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
```typescript
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**:
```typescript
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

```typescript
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)
```typescript
const [formData, setFormData] = useState({...});
```
**Uso**: Estado temporal de componentes individuales

### Estado Global (Context)
```typescript
const { user, login, logout } = useAuth();
```
**Uso**: Estado compartido entre múltiples componentes

### Estado del Servidor (TanStack Query)
```typescript
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

```typescript
// 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

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

### 3. Custom Hook Pattern

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

### 4. Higher-Order Component (HOC) Pattern

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

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

## Optimizaciones de Performance

### Code Splitting
```typescript
const AdminDashboard = lazy(() => import('./pages/AdminDashboard'));
```

### Memoization
```typescript
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
```typescript
describe('useAuth', () => {
  it('should login successfully', async () => {
    // test implementation
  });
});
```

### Integration Tests
```typescript
describe('BookingFlow', () => {
  it('should complete booking', async () => {
    // test implementation
  });
});
```

### E2E Tests (Cypress/Playwright)
```typescript
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