TravelPal

Planifica, reserva y controla tus viajes
Una plataforma completa para itinerarios, gastos, presupuestos y analíticas.

Instalación · Características · Documentación · Roadmap

📋 Descripción

TravelPal es una aplicación web para gestionar todo el ciclo de un viaje: itinerarios, control de gastos, presupuestos y analíticas. El backend es InsForge (Postgres + Auth + Storage) y el hosting es Cloudflare Workers con @opennextjs/cloudflare.

🚀 Características

• ✅ Gestión completa de viajes: crear, editar y organizar itinerarios
• 💸 Control de gastos por viaje con categorías y métricas
• 💼 Presupuestos y seguimiento financiero
• 📊 Dashboard analítico con visualizaciones interactivas
• 🔐 Autenticación con InsForge (server actions; refresh token httpOnly)
• 🧩 Logger centralizado y notificaciones toast
• 📱 Diseño responsive y accesible

---

🗂️ Estructura del Proyecto

app-viajes/
├── src/
│   ├── app/                 # Rutas, páginas y API routes (App Router)
│   ├── components/          # UI y componentes por dominio
│   ├── lib/                 # Clientes (insforge), auth, utilidades
│   └── contexts/            # Contextos de React
├── migrations/              # Esquema InsForge (fuente de verdad, ver ADR-004)
├── docs/                    # Documentación colaborativa
├── .github/                 # Workflows, plantillas y labels
├── CONTEXT.md               # Contexto de dominio para agentes
└── README.md

---

⚙️ Instalación y Uso

Prerrequisitos

• Node.js 22.22.3+ (o 24.8+)
• pnpm 12.3.4 (versión fijada en package.json)
• Un proyecto de InsForge (URL + anon key + API key)

Instalación

git clone https://github.com/PabloJustDevelops/TravelPal.git
cd TravelPal
npm install --global pnpm@12.3.4 # solo si todavía no tienes pnpm
pnpm install --frozen-lockfile

Configuración

# Copiar variables de entorno
cp .env.example .env.local

Variables de .env.local (nunca se versionan):

NEXT_PUBLIC_INSFORGE_URL=https://<appkey>.<region>.insforge.app
NEXT_PUBLIC_INSFORGE_ANON_KEY=<anon key>
INSFORGE_API_KEY=<api key de proyecto, solo servidor>

Ejecución

pnpm run dev          # Desarrollo (http://localhost:3000)
pnpm run lint         # ESLint
pnpm run type-check   # TypeScript
pnpm run test:ci      # Jest
pnpm run test:e2e     # Playwright (ver docs/TESTING.md)
pnpm run test:tester  # Tester Army: acceso publico, escritorio y viewport estrecho
pnpm run storybook    # Catálogo de componentes: http://localhost:6006
pnpm run test:storybook # Interacciones y axe de las stories en Chromium
pnpm run build        # next build

Despliegue (Cloudflare Workers)

pnpm run preview      # Build de OpenNext + wrangler dev local
pnpm run deploy       # Build de OpenNext + deploy a Cloudflare

INSFORGE_API_KEY es un secreto de runtime: se sube con wrangler secret put INSFORGE_API_KEY.

📖 Documentación

• CONTEXT.md: contexto de dominio (stack, comandos, modelo de datos, glosario)
• docs/ARCHITECTURE.md: arquitectura y flujo de datos
• docs/DECISIONS/: ADRs (InsForge, Cloudflare, esquema)
• docs/TECHNICAL.md: guía técnica
• docs/TESTING.md: tests unitarios y E2E (Playwright)
• docs/TESTER-ARMY.md: suite complementaria y evaluación de Tester Army
• docs/CONTRIBUTING.md: cómo contribuir
• docs/COMMITS.md / docs/PR_PROCESS.md: flujo de trabajo

---

🔧 Tecnologías

• Frontend: Next.js 16 (App Router), React 19, TypeScript
• Estilos: Tailwind CSS
• Backend: InsForge (Postgres, Auth, Storage) vía @insforge/sdk
• Hosting: Cloudflare Workers con @opennextjs/cloudflare
• Testing: Jest + Testing Library, Playwright (flujos con datos) y Tester Army (acceso público)
• CI/CD: GitHub Actions; build, Worker y E2E antes del deploy, y E2E contra producción después

📋 Roadmap

• Internacionalización (i18n)
• Integración con más APIs de viajes
• Sistema de colaboración en viajes
• App móvil (React Native)

👥 Contribuidores

• Pablo Rodríguez Garijo - Desarrollador principal
• Alejandro García Redondo - Desarrollador ayudante

🤝 Contribuir

1. Crea una rama para tu cambio
2. Commit con Conventional Commits (ver docs/COMMITS.md)
3. Abre un Pull Request (ver docs/PR_PROCESS.md)

📄 Licencia

MIT.

📞 Contacto

Pablo Rodríguez Garijo - @PabloJustDevelops