GoGoMap

Plataforma de Localización de Puntos de Interés Sostenibles en Málaga

Descripción • Características • Stack Tecnológico • Instalación • Documentación • Contribución

---

📋 Tabla de Contenidos

• Descripción
• Características
• Stack Tecnológico
• Arquitectura del Proyecto
• Instalación y Configuración
• Estructura del Proyecto
• Documentación
• Contribución
• Licencia

---

📖 Descripción

GoGoMap es una aplicación web y móvil responsiva que facilita a los ciudadanos de Málaga localizar puntos de interés vinculados con los 17 Objetivos de Desarrollo Sostenible (ODS) de Naciones Unidas. Mediante geolocalización en tiempo real, la plataforma identifica automáticamente los servicios públicos y espacios sostenibles más cercanos, permitiendo a los usuarios planificar rutas e interactuar con elementos gamificados para fomentar el compromiso cívico.

Misión

Promover el conocimiento y acceso a iniciativas sostenibles en Málaga, generando consciencia ciudadana sobre los ODS mediante una experiencia interactiva e intuitiva.

---

✨ Características

Funcionalidades Principales

• 🌍 Geolocalización en Tiempo Real: Seguimiento preciso de la ubicación del usuario mediante GPS o red
• 🗺️ Mapa Interactivo: Visualización dinámica de puntos ODS en tiempo real con clustering inteligente
• 🎯 Filtrado Avanzado: Búsqueda por ODS, rango de distancia y estado de favoritos
• 📍 Detalle de Puntos: Información completa con distancia, categorización y estado
• 🛣️ Generación de Rutas: Cálculo automático de rutas mediante OSRM (Open Source Routing Machine)
• ❤️ Sistema de Favoritos: Gestión personalizada de puntos de interés
• 🎮 Gamificación: Sistema de Karma Points, logros y ruleta diaria
• 👤 Perfil de Usuario: Dashboard con estadísticas, rankings y recompensas
• 🔐 Autenticación Segura: Registro, login y gestión de sesiones con JWT

Estándares Implementados

• Diseño responsive para escritorio, tablet y dispositivos móviles
• Interfaz accesible y conforme a WCAG 2.1 Level AA
• Performance optimizado con lazy loading y code splitting
• Progressive Web App (PWA) ready

---

🛠️ Stack Tecnológico

Backend

Componente	Tecnología
Lenguaje	Java 21
Framework	Spring Boot 3.5.14
Base de Datos	MySQL 8.0+
ORM	Hibernate (Spring Data JPA)
Seguridad	Spring Security + OAuth2 + JWT
Mapeo de Objetos	MapStruct
Build Tool	Maven 3.8+

Frontend

Componente	Tecnología
Lenguaje	TypeScript 6.0
Framework	React 19.2
Bundler	Vite 5.0
Estilos	Tailwind CSS 4.3
Componentes UI	shadcn/ui + Radix UI
Mapas	Leaflet + React-Leaflet
HTTP Client	Axios
Router	React Router v7
Validación	Zod (implícito)

Herramientas Comunes

• Linting: ESLint
• Type Checking: TypeScript
• Formateo: Prettier (recomendado)
• Testing: (Configuración disponible)

---

🏗️ Arquitectura del Proyecto

GoGoMap/
├── backend/                    # API RESTful (Java Spring Boot)
│   ├── src/main/java/
│   │   └── com/esplai/backendgogomap/
│   │       ├── auth/          # Autenticación y autorización
│   │       ├── controllers/   # Endpoints REST
│   │       ├── services/      # Lógica de negocio
│   │       ├── repositories/  # Acceso a datos
│   │       ├── models/        # Entidades JPA
│   │       ├── mappers/       # DTO mapping
│   │       ├── exceptions/    # Manejo de errores
│   │       └── config/        # Configuración
│   ├── src/main/resources/
│   │   ├── application.properties
│   │   └── data/              # Datasets GeoJSON (17 ODS)
│   ├── pom.xml
│   ├── mvnw / mvnw.cmd
│   └── README.md
│
├── frontend/                   # Aplicación React + TypeScript
│   ├── src/
│   │   ├── components/        # Componentes reutilizables
│   │   ├── pages/             # Páginas principales
│   │   ├── routes/            # Enrutamiento
│   │   ├── context/           # Context API (Auth, etc)
│   │   ├── api/
│   │   │   ├── services/      # Servicios API
│   │   │   ├── types/         # Tipos TypeScript
│   │   │   └── axiosConfig.ts # Configuración HTTP
│   │   ├── utils/             # Funciones auxiliares
│   │   ├── hooks/             # Custom React hooks
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── public/                # Assets estáticos
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   └── README.md
│
└── README.md                  # Este archivo

---

🚀 Instalación y Configuración

Requisitos Globales

• Node.js 18+ (para frontend)
• Java 21 (para backend)
• Maven 3.8+ (para backend)
• MySQL 8.0+ (base de datos)
• Git (control de versiones)

Paso 1: Clonar el Repositorio

git clone https://github.com/tu-organizacion/gogomaps.git
cd gogomaps

Paso 2: Configurar Backend

Véase backend/README.md para:

• Instalación de dependencias Maven
• Configuración de base de datos MySQL
• Variables de entorno (JWT, DB credentials)
• Ejecución del servidor

Paso 3: Configurar Frontend

Véase frontend/README.md para:

• Instalación de dependencias Node
• Configuración de variables de entorno (.env)
• Servidor de desarrollo
• Build de producción

Ejecución Combinada (Desarrollo)

# Terminal 1: Backend
cd backend
./mvnw spring-boot:run

# Terminal 2: Frontend
cd frontend
pnpm dev

La aplicación estará disponible en http://localhost:5173 (Vite)
API disponible en http://localhost:8080 (Spring Boot)

---

📁 Estructura del Proyecto

Cada módulo cuenta con su propia documentación:

• Backend Documentation: API, endpoints, guías de desarrollo
• Frontend Documentation: Componentes, páginas, configuración

---

📚 Documentación

Backend

• Endpoints de API
• Modelos de datos
• Manejo de errores
• Seguridad y autenticación
• Guía de desarrollo

Ver: backend/README.md

Frontend

• Estructura de componentes
• Páginas y rutas
• Gestión de estado
• Integración con API
• Build y deployment

Ver: frontend/README.md

---

🤝 Contribución

Las contribuciones son bienvenidas. Para contribuir:

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

Estándares de Código

• Código limpio y legible
• Tipos TypeScript completos
• JavaDoc en métodos públicos
• Commits semánticos
• Tests unitarios (cuando sea aplicable)

---

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

---

📞 Contacto y Soporte

Para preguntas, sugerencias o reportar problemas:

• Issues: Crear un issue
• Email: contacto@gogomaps.dev
• Documentación: Wiki

---

Desarrollado con ❤️ por el equipo de GoGoMap

Promoviendo ciudadanía sostenible en Málaga

Estructura de componentes

src/components/onboarding/
  GoGomapOnboarding.tsx     ← Componente raíz, ensambla todos los bloques
  components/
    Navbar.tsx              ← Barra de navegación fija con scroll effect
    Hero.tsx                ← Sección principal con CTA
    Features.tsx            ← 4 tarjetas de funcionalidades
    OdsShowcase.tsx         ← Chips con iconos oficiales ODS
    HowItWorks.tsx          ← 3 pasos de uso con CTA
    KarmaCallout.tsx        ← Sección de gamificación con CTA
    Footer.tsx              ← Pie de página con links
    Button.tsx              ← Componente de botón reutilizable

Secciones

Sección	Componente	Descripción
Navbar	Navbar.tsx	Fija en la parte superior, transparente al cargar y semiopaca al hacer scroll. Incluye logo y botón de acceso
Hero	Hero.tsx	Titular, subtítulo, badge con tagline, dos botones CTA y foto de Málaga con halo verde
Funcionalidades	Features.tsx	Cuatro tarjetas glassmorphism explicando las funciones principales de la app
ODS	OdsShowcase.tsx	Fila horizontal con los iconos oficiales de los 6 ODS más relevantes para Málaga
Cómo funciona	HowItWorks.tsx	Tres pasos conectados por una línea vertical explicando el flujo de uso
Karma	KarmaCallout.tsx	Tarjeta destacada con ejemplo de perfil de usuario, barra de progreso y Eco Points
Footer	Footer.tsx	Links de navegación interna y copyright

Diseño

• Fondo: degradado verde animado from-[#1B6D24] via-[#6DBD6A] to-[#A3F69C] con blobs, rejilla y partículas flotantes
• Estilo de tarjetas: glassmorphism (bg-white/10 backdrop-blur-md border border-white/10)
• Botón primario: glow verde (bg-emerald-600 con shadow verde exterior)
• Botón secundario: glassmorphism (bg-white/10 backdrop-blur-md border border-white/20)
• Iconos: Lucide React
• Tipografía: Inter

Componente Button

El componente Button.tsx es reutilizable en toda la landing. Acepta las siguientes props:

interface ButtonProps {
  label: string
  href?: string
  onClick?: () => void
  variant?: 'primary' | 'secondary'
  icon?: ReactNode
}

Uso:

<Button label="Entrar a la App" href="/login" variant="primary" icon={<Leaf className="w-4 h-4" />} />
<Button label="¿Cómo funciona?" href="#how-it-works" variant="secondary" />

Convención de estilos

La landing aplica un patrón de extracción de clases fuera del JSX, denominado extraTailwind. Todas las clases de Tailwind se definen como constantes con nombres descriptivos antes del componente, manteniendo el JSX limpio y legible:

// ✅ Correcto
const section = "relative px-6 py-8 flex flex-col items-center gap-8"

export default function MiComponente() {
  return <section className={section}>...</section>
}

// ❌ Incorrecto
export default function MiComponente() {
  return <section className="relative px-6 py-8 flex flex-col items-center gap-8">...</section>
}

⚠️ Este patrón extraTailwind se aplica en todos los componentes del proyecto, no solo en la landing.

Iconos ODS

Los iconos se cargan dinámicamente desde public/assets/ods/ usando el formato oficial de Naciones Unidas:

S-WEB-Goal-01.png
S-WEB-Goal-06.png
...

La función helper odsImg construye la ruta automáticamente:

function odsImg(num: number): string {
  const padded = String(num).padStart(2, '0')
  return `/assets/ods/S-WEB-Goal-${padded}.png`
}

---

Páginas de error

El proyecto cuenta con dos páginas de error independientes que comparten el mismo estilo visual que el resto de la app (fondo #F5F5EE, colores verdes, tipografía oscura sobre fondo claro).

Rutas

Ruta	Componente raíz	Descripción
/error	ErrorPage.tsx	Error genérico con botones Reintentar y Volver
/*	Error404Page.tsx	Error 404 con botón Volver al Mapa

Estructura de component