Arquitectura estado_turismo: Backend + Múltiples Rutas Frontend

Fecha: 2026-09-18
Proyecto: ~/nef/estado_turismo
Contexto: Sistema de recomendación turística con visualización de rutas por región

---

Stack deployado

Backend

• Worker: engine → https://engine.nef.workers.dev
• Función: Motor de recomendaciones personalizadas con Qwen (Workers AI)
• Input: POST / con {"usuario": "sarah"|{...}, "destino": "Bacalar"}
• Output: Ranking de establecimientos basado en perfil de usuario
• Config: engine/wrangler.jsonc

Frontend (Pages)

• Proyecto inicial: ruta-maya-staging → https://ruta-maya-staging.pages.dev
• Función: Visualización interactiva del Tren Maya (MapLibre + datos estáticos)
• Estructura:

  ruta-maya/
  ├── index.html
  ├── tren-maya-quintana-roo.geojson
  └── src/
      ├── tren-maya-api.js       # Datos hardcodeados
      ├── place-store.js
      ├── places-panel.js
      └── maplibre-adapter.js
  

---

Estrategia: Una carpeta por ruta

Decisión: Duplicar la estructura de ruta-maya/ para cada nueva ruta geográfica.

Ventajas

• Cada ruta es independiente (deploy, iteración, datos)
• Sin overhead de router/framework
• Datos estáticos = rápido, sin dependencia del backend
• Fácil A/B testing por ruta

Estructura objetivo

estado_turismo/
├── engine/                    # Worker (backend común)
├── ruta-maya/                 # Tren Maya Quintana Roo
├── ruta-pacifico/             # Nueva: costa Pacífico
├── ruta-colonial/             # Nueva: ciudades coloniales
└── spab-retrieval/            # Pipeline de datos (no deploy)

Cada carpeta de ruta contiene

• index.html: App autocontenida
• {ruta}.geojson: Geometrías (corredor + estaciones + lugares)
• src/{ruta}-api.js: Datos de lugares y metadata
• src/place-store.js: Lógica común (copiar)
• src/places-panel.js: UI común (copiar)
• DEPLOY.md: Instrucciones específicas

Comando de deploy por ruta

cd ruta-{nombre}
export CLOUDFLARE_API_TOKEN="cfat_..."
wrangler pages deploy . --project-name=ruta-{nombre}-staging --branch=main --commit-dirty=true

---

Futuras integraciones

Conectar frontend → engine (cuando se requiera)

Modificar src/{ruta}-api.js:

async getRecommendations(usuario, destino) {
  const res = await fetch('https://engine.nef.workers.dev', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ usuario, destino })
  });
  return res.json();
}

Multi-ruta dinámica (futuro)

Crear un Pages principal con índice de rutas:

rutas-turismo/
├── index.html              # Índice de todas las rutas
├── viewer/                 # Visor genérico
└── data/
    ├── tren-maya.json
    ├── pacifico.json
    └── colonial.json

---

Tokens y permisos

• Account ID: 162ab69a40524314530193e8a3e8f414
• API Token (en spab-retrieval/.env): Con permisos:
  • Workers Scripts > Edit
  • Pages > Edit
  • Account Settings > Read
• Token en shell: Actualizar ~/.zshrc si cambia

---

Próximos pasos por ruta nueva

1. Duplicar ruta-maya/ → ruta-{nombre}/
2. Reemplazar GeoJSON con nueva geometría
3. Actualizar datos en src/{nombre}-api.js
4. Modificar metadata en index.html (title, description)
5. Deploy: wrangler pages deploy . --project-name=ruta-{nombre}-staging
6. URL → https://ruta-{nombre}-staging.pages.dev