Skip to content
Boost CRM

Estrategia de Despliegue Web, Native y Docs

Integración Zauru por ambiente

Section titled “Integración Zauru por ambiente”

La selección dev|prod para Zauru ya no la decide el monorepo. Esa decisión vive en BoostAPI y se controla desde su .env/runtime.

Notas:

  1. Infraestructura puede seguir teniendo previews/PR deploys.
  2. El monorepo no deriva URLs Zauru para graphql.json ni para GraphQL runtime.
  3. Si el equipo necesita cambiar ambiente Zauru, se hace desde backend, no desde apps/web ni apps/native.

Web (Vercel)

Section titled “Web (Vercel)”
  • Preview por PR a nivel de hosting.
  • Producción al merge en main.
  • Variables de entorno por ambiente.
  • BFF mobile vive en apps/web/app/api/mobile/auth/*.
  • Auth mobile y secretos de integración permanecen del lado web.
  • La capa server de web también puede servir como amortiguador de BoostAPI:
    • caché corta
    • agregación
    • deduplicación
    • traducción de errores browser-safe
  • Web ya no lee graphql.json; solo usa zauru_session, GET /api/auth/zauru-session y POST /api/auth/zauru-session/sync.

Native (Expo/EAS)

Section titled “Native (Expo/EAS)”
  • Canales EAS pueden seguir siendo development, preview, production.
  • En dev físico el modo oficial actual es manual-bff:
    • Cloudflare solo para el BFF web
    • Metro en LAN por defecto
  • El flujo automático con @repo/dev-mobile-bff queda como legacy opcional.
  • En dev físico usar base HTTPS estable (EXPO_PUBLIC_WEB_BFF_BASE_URL o EXPO_PUBLIC_WEB_BFF_DEV_BASE_URL), nunca localhost.
  • apps/native sigue BFF-first y no hace graphql.json ni GraphQL directo en esta fase.
  • La salida de mocks a consumo real debe hacerse por slices, después de que el mismo módulo ya esté validado en web.
  • En producción no se usa cloudflared, ni Expo tunnel, ni EXPO_PUBLIC_WEB_BFF_DEV_BASE_URL.

Docs (Astro)

Section titled “Docs (Astro)”
  • apps/docs despliegue estático.
  • Build bloqueado si sanitización detecta contenido prohibido.
  • Publicación solo de documentos visibility: both o visibility: external.
  • La doctrina de auth/Zauru debe mantenerse alineada entre docs internas y Astro; no debe existir un modelo “ligero” distinto para público.

Matriz operativa mobile

Section titled “Matriz operativa mobile”
Contexto redirect_uri registrado BFF mobile
Dev (simulador/dispositivo) com.turbo.example://auth/callback https://<tunnel-web>.trycloudflare.com o dominio dev HTTPS
Producción <scheme-prod>://auth/callback https://crm.roo.com.gt

Notas:

  1. client_secret nunca sale del backend web.
  2. En dev-client iOS, el panel para ingresar URL de bundle es esperado y no existe en producción.
  3. EXPO_PUBLIC_WEB_BFF_DEV_BASE_URL es solo URL base HTTPS del BFF dev, sin secrets.
  4. En dev mobile hay dos dependencias distintas:
    • BFF tunnel (cloudflared)
    • Metro LAN (default) o Expo tunnel/ngrok (solo opcional)

Backend (BoostAPI) en Render

Section titled “Backend (BoostAPI) en Render”

BoostAPI se despliega como web service en Render, independiente del monorepo frontend.

Comandos de build/start

Section titled “Comandos de build/start”
Configuración Valor Nota
Build Command yarn build:render Fuerza devDependencies aunque NODE_ENV=production
Start Command yarn start:render Arranca desde dist/src/main

RENDER_EXTERNAL_URL

Section titled “RENDER_EXTERNAL_URL”

Render inyecta automáticamente RENDER_EXTERNAL_URL con la URL pública del servicio. BoostAPI la usa para derivar la URL del webhook de Communications cuando BOOST_PUBLIC_BASE_URL no está definida.

Tres modos de runtime

Section titled “Tres modos de runtime”
Modo APP_RUNTIME_MODE Zauru apunta a Uso
dev dev zauru.herokuapp.com Desarrollo local, CORS permisivo
preview preview zauru.herokuapp.com (forzado) Preview/staging, protege datos prod
prod prod app.zauru.com Producción real

Regla crítica de preview: Si NODE_ENV=preview, BoostAPI fuerza Zauru a Heroku aunque ZAURU_ENV=prod. Esto evita escrituras accidentales en Zauru de producción desde ambientes de staging.

Swagger

Section titled “Swagger”

Documentación interactiva disponible en {BOOST_API_URL}/api.

  • Producción: https://<render-url>/api
  • Local: http://localhost:3003/api

Orden de release recomendado

Section titled “Orden de release recomendado”
  1. Contratos (shared-types).
  2. Normalización y servicios de dominio (api-client + crm-services).
  3. Backend (BoostAPI) si hay cambios de API, esquema de BD o integraciones. Desplegar en Render y verificar Swagger antes de que web/native consuman los nuevos endpoints.
  4. Web consumidor productivo con BFF/orquestación cuando aplique.
  5. Native consumidor del mismo contrato compartido, después del aprendizaje real de web.
  6. Documentación y skills sincronizadas.