Refactor: Analyze project documentation
This commit is contained in:
gpt-engineer-app[bot]
428
docs/ARCHITECTURE.md
Normal file
428
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# 🏗️ 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
|
||||
Reference in New Issue
Block a user