turo-clone/README.md

# Turo Clone

Plataforma de alquiler de vehículos entre particulares inspirada en Turo.com. Aplicación web completa desarrollada con arquitectura modular basada en principios SOLID.

## Descripción

Este proyecto es un clon funcional de Turo.com que permite a los usuarios buscar, reservar y gestionar alquileres de vehículos. Los propietarios pueden listar sus vehículos y los arrendatarios pueden buscar y reservar vehículos disponibles.

## Características Principales

### Funcionalidades Core

- **Búsqueda y Filtrado**: Búsqueda avanzada de vehículos por ubicación, fechas, tipo y precio con visualización en mapa estilo Airbnb (integración con Google Maps)
- **Gestión de Vehículos**: Sistema completo para que los propietarios gestionen sus vehículos
- **Sistema de Reservas**: Calendario de disponibilidad y gestión completa de reservas
- **Pagos**: Procesamiento seguro de transacciones
- **Reseñas y Calificaciones**: Sistema de feedback entre usuarios
- **Mensajería**: Comunicación en tiempo real entre propietarios y arrendatarios
- **Notificaciones**: Sistema de alertas y notificaciones para mantener a los usuarios informados

### Flujos Críticos

**Onboarding Host**

Creación de perfil → KYC upload documento → Listar vehículo → Subir fotos → Publicar

**Reserva Guest**

Buscar → Elegir vehículo → Ver calendario → Seleccionar fechas → Ver precio final → Pagar → Notificación host → (Si no instantBook) Host acepta → Reserva confirmada y calendario bloqueado

**Mensajería**

Hilo por booking con notificaciones email/push

**Check-in / Check-out**

Host confirma entrega, marca inicio y fin; posibilidad de añadir "confirmation photos"

**Claims**

Subir fotos y formulario, admin procesa o simula pago de seguro

### Alcance Mínimo Viable (MVP)

#### Prioridad Alta - Funciones Imprescindibles

**Registro / Autenticación**
- Autenticación de usuarios con email
- OAuth: Google y Apple
- Implementado con Appwrite Auth

**Perfiles de Usuarios**
- Roles: Guest (huésped) y Host (anfitrión)
- KYC light para hosts: datos personales y datos del vehículo

**Gestión de Vehículos**
- Crear/editar listado de vehículo
- Campos: título, descripción, fotos, atributos (marca, modelo, año, asientos, transmisión, features)
- Precio base por día
- Reglas de viaje
- Ubicación y calendario de disponibilidad
- Fotos almacenadas en Appwrite Storage

**Búsqueda y Filtros**
- Búsqueda por ubicación, fechas, precio
- Visualización en mapa estilo Airbnb con integración de Google Maps
- Búsqueda interactiva en mapa con marcadores de vehículos disponibles
- Filtros por tipo de vehículo, features
- Filtro por distancia de entrega
- Opciones de entrega/pickup

**Página de Detalle del Vehículo**
- Galería de fotos
- Mapa de ubicación
- Precio diario con desglose
- Políticas del vehículo
- Reseñas
- Calendario de disponibilidad
- Botón reservar/solicitar

**Flujo de Reservas**
- Seleccionar fechas
- Ver precio total (impuestos + fees + protección opcional)
- Pago con Stripe
- Confirmación de reserva

**Mensajería**
- Mensajería en-app para coordinación huésped-anfitrión
- Hilos de conversación por booking

**Calendario y Disponibilidad**
- Calendario de disponibilidad
- Bloqueo automático por reservas

**Panel Host**
- Ver reservas
- Aceptar/rechazar reservas (si no es instant booking)
- Administrar listado de vehículos
- Gestionar protección del vehículo

**Panel Admin**
- Moderación de listados
- Gestión de usuarios
- Transacciones y reportes

#### Funciones Avanzadas (Post-MVP)

- Integración de seguros/planes de protección con distintos planes y deducibles
- Pricing dinámico, "boosts" y reglas de descuentos
- Entrega en aeropuerto con fees incluidos en precio diario
- Calendar sync con Google Calendar
- Integración de telemetría (opcional)
- Ratings & reviews completos
- Claims flow y soporte al cliente

### Roles y Permisos

#### Roles del Sistema

**Guest (Huésped)**
- Puede reservar vehículos
- Realizar pagos
- Dejar reseñas y calificaciones
- Comunicarse con hosts mediante mensajería

**Host (Anfitrión)**
- Crear y gestionar listados de vehículos
- Recibir pagos
- Elegir plan de protección
- Gestionar reservas (aceptar/rechazar)
- Administrar calendario de disponibilidad

**Super-admin / Moderador**
- Gestionar usuarios
- Moderar listados
- Gestionar transacciones
- Acceso a reportes y analytics

#### Implementación

- RBAC implementado en Appwrite con custom claims
- Guards en la capa de frontend para protección de páginas
- Permisos configurados en Appwrite Console por colección

## Stack Tecnológico

- **Frontend**: Next.js 16 con Cache Components
- **Lenguaje**: TypeScript
- **Estilos**: Tailwind CSS
- **UI Library**: Shadcn/ui
- **Validación**: Zod v4
- **Backend**: Appwrite v18
- **Arquitectura**: SOLID con módulos que simulan microservicios

## Arquitectura

El proyecto sigue una arquitectura modular basada en principios SOLID donde cada módulo es autocontenido con sus propios componentes, hooks, servicios y tipos. Esta estructura simula microservicios permitiendo que cada módulo sea independiente y fácil de mantener.

### Estructura de Módulos

Cada módulo contiene:
- Componentes de presentación
- Hooks personalizados para lógica de estado
- Servicios con lógica de negocio
- Tipos TypeScript y schemas de validación Zod

## Módulos del Sistema

1. **Autenticación** - Login, registro y gestión de sesiones
2. **Usuarios** - Perfiles y gestión de usuarios
3. **Vehículos** - CRUD completo y gestión de vehículos
4. **Búsqueda** - Búsqueda avanzada y filtrado
5. **Reservas** - Sistema completo de reservas con calendario
6. **Pagos** - Procesamiento de pagos
7. **Reseñas** - Sistema de calificaciones y feedback
8. **Mensajería** - Chat en tiempo real entre usuarios
9. **Notificaciones** - Sistema de alertas y notificaciones

## Configuración Inicial

### Requisitos Previos

- Node.js instalado
- Cuenta de Appwrite configurada
- Variables de entorno configuradas

### Variables de Entorno

Configurar las siguientes variables en un archivo `.env.local`:

- Endpoint de Appwrite
- ID del proyecto de Appwrite
- ID de la base de datos de Appwrite

### Instalación

Instalar las dependencias del proyecto y ejecutar el servidor de desarrollo.

### Configuración de Appwrite

El proyecto utiliza Appwrite SDK directamente desde el frontend sin necesidad de API routes intermedias. La autenticación y autorización son manejadas por Appwrite, y los permisos se configuran en Appwrite Console.

### Base de Datos

Se requiere crear las siguientes colecciones en Appwrite:
- Usuarios
- Vehículos
- Reservas
- Pagos
- Reseñas
- Mensajes
- Notificaciones

## Estructura del Proyecto

El proyecto está organizado en módulos independientes dentro de la carpeta `modules/`, cada uno con su propia estructura de componentes, hooks, servicios y tipos. Los componentes compartidos se encuentran en `components/`, y las configuraciones y utilidades en `lib/`.

### Estructura de Directorios

```
turo-clone/
├── app/                          # Next.js App Router
│   ├── (auth)/                  # Grupo de rutas de autenticación
│   │   ├── login/
│   │   ├── register/
│   │   └── layout.tsx
│   ├── (public)/                 # Rutas públicas
│   │   ├── page.tsx             # Homepage
│   │   ├── search/
│   │   ├── vehicles/
│   │   │   └── [id]/
│   │   └── layout.tsx
│   ├── (dashboard)/              # Rutas protegidas
│   │   ├── dashboard/
│   │   │   ├── vehicles/
│   │   │   │   ├── create/
│   │   │   │   └── [id]/
│   │   │   └── page.tsx
│   │   ├── reservations/
│   │   ├── profile/
│   │   └── layout.tsx
│   ├── api/                      # API Routes (solo para webhooks o integraciones externas)
│   ├── error.tsx                 # Manejo de errores global
│   ├── global-error.tsx          # Manejo de errores críticos
│   ├── not-found.tsx             # Página 404 global
│   ├── loading.tsx               # Estado de carga global
│   ├── layout.tsx
│   └── globals.css
│
├── modules/                      # Módulos del sistema (microservicios simulados)
│   ├── auth/
│   │   ├── components/          # Componentes de UI
│   │   ├── hooks/               # Custom hooks
│   │   ├── services/            # Lógica de negocio
│   │   ├── types/               # Tipos TypeScript
│   │   └── index.ts             # Barrel exports
│   │
│   ├── users/
│   ├── vehicles/
│   ├── search/
│   ├── reservations/
│   ├── payments/
│   ├── reviews/
│   ├── messaging/
│   └── notifications/
│
├── components/                   # Componentes compartidos
│   ├── ui/                      # Componentes de shadcn/ui
│   ├── layout/                  # Componentes de layout
│   └── common/                  # Componentes comunes
│
├── lib/                         # Utilidades y configuraciones
│   ├── utils.ts
│   ├── appwrite/                # Configuración de Appwrite
│   └── constants/
│
├── hooks/                       # Hooks compartidos
├── types/                       # Tipos globales
├── public/                      # Archivos estáticos
├── config/                      # Configuraciones
└── docs/                        # Documentación del proyecto
```

### Estructura de un Módulo

Cada módulo sigue esta estructura estándar:

```
modules/[module-name]/
├── components/          # Componentes de presentación
│   └── [Component].tsx
├── hooks/               # Custom hooks para lógica de estado
│   └── use[Feature].ts
├── services/            # Servicios de negocio (lógica pura)
│   └── [feature].service.ts
├── types/               # Definiciones de tipos TypeScript y schemas Zod
│   ├── [feature].types.ts    # Tipos TypeScript
│   └── [feature].schemas.ts  # Schemas de validación Zod
└── index.ts             # Barrel exports para importaciones limpias
```