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