428 lines
15 KiB
Markdown
428 lines
15 KiB
Markdown
# 🏗️ 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 |