# CLAUDE.md — Gotagig

Marketplace geolocalizado tipo Uber pero para contratar **músicos** (mariachis, saxofón, gaitas
venezolanas, solistas, guitarristas, duetos, tambores…). Ver `README.md` para el concepto completo.

## Convenciones (heredadas del estilo del usuario)

- **Idioma:** español para lo humano (comentarios, mensajes de error al usuario, UI), inglés para lo
  técnico (identificadores, funciones, tablas, columnas). Los comentarios explican el **porqué**, no el qué.
- **Backend:** FastAPI 0.137.1 + SQLAlchemy 2.0.50 (estilo declarativo `Mapped[...]`) + Pydantic 2.13.4.
- **DB:** PostgreSQL + PostGIS. La geolocalización usa columnas `Geography(POINT, 4326)` y se consulta con
  `ST_DWithin` (radio en metros) + `ST_Distance` (orden por cercanía). No romper esto con haversine manual.
- **Frontend:** Next.js 16.2.10 + TypeScript + Tailwind. Diseño minimalista, moderno, a la vanguardia.
  Sin shadcn — componentes primitivos propios + helper `cn()`.
- **Auth:** JWT stateless. Token en `Authorization: Bearer`. Nunca guardar secretos en el repo (usar `.env`).

## Multi-país

Toda entidad geolocalizada lleva `country` (ISO-2: `VE`, `CL`, `IE`). El MVP arranca con esos tres pero la
arquitectura no debe hardcodear ninguno — se agregan países agregando datos, no código.

## Cómo correr el proyecto en dev

Usar `python run_dev.py` desde la raíz del repo — levanta DB (Docker) + backend (FastAPI) + frontend
(Next.js) juntos, multiplataforma (Linux/Windows). Ctrl+C corta los tres procesos.
No arrancar los tres servicios manualmente por separado salvo pedido explícito del usuario.

## Reglas de oro del usuario

- **Preguntar antes de cambios no solicitados.** No tocar código no pedido aunque parezca bug latente.
- No agregar contenido redundante.
- Imágenes públicas: generar con IA (Replicate), nunca stock ni emojis como placeholder.