Guía Del Desarrollador

Esta sección documenta cómo se trabaja el monorepo desde el lado del desarrollador: el conocimiento operativo que no está explícito en el código y que un dev nuevo necesita para hacer un feature o un fix, probarlo y llevarlo a producción sin tener que adivinar.

No describe la lógica de negocio (eso está en Procesos y Sistemas). Aquí va el toolchain, el flujo de git, cómo correr y probar cada app, y sobre todo cómo y dónde se despliega cada cosa, que es lo menos obvio del repositorio.

Estado actual verificado

Todo lo de esta guía fue contrastado contra el repo (scripts, railway.toml, wrangler.jsonc, eas.json, workflow de CI) a junio de 2026 y confirmado con el equipo. Lo que quede sin confirmar se marca ❓ Por confirmar; la deuda técnica o mejoras a futuro se marcan 🔧 Mejora pendiente.

El Monorepo En 30 Segundos

• Gestor: pnpm@10.10.0 + Turborepo. Workspaces en apps/* y packages/*.
• Node: 22.13.1 (ver .nvmrc). engines exige >=22 <25: Node 25 emite warning y puede romper el rango del engine.
• Lenguajes: TypeScript (la mayoría), Python 3.12 (engine), Deluge (Zoho, fuera del repo como deploy).
• Regla de oro: todo desde la raíz con pnpm --filter <workspace> <script>. No introducir npm/yarn.

# Setup mínimo
nvm use            # -> 22.13.1
corepack enable    # pnpm 10.10.0 viene fijado en packageManager
pnpm install       # instala todo el workspace
pnpm dev           # turbo run dev --parallel (levanta todo; normalmente se filtra)

Detalle completo en Setup Local.

Mapa De Despliegue (Lo Más Importante)

La trampa número uno del repo: no todo se despliega igual, y no todo se despliega solo. Mergear a main despliega los backends, pero los frontends y la app móvil son manuales.

App	Stack	Cómo se despliega	Destino
core-backend	Express / Node	🟢 Auto (CI) al push a main	Railway · servicio core-backend
drivers-backend	Express / Node	🟢 Auto (CI) al push a main	Railway · servicio rnb-drivers-api
engine-backend	FastAPI / Python (Docker)	🟢 Auto (CI) al push a main	Railway · servicio engine-backend
dash-web	Vite / React	🔴 Manual deploy:prod (wrangler)	Cloudflare Worker frontend-dash-rnb-logistics-prod
clients-web	Next.js (OpenNext)	🔴 Manual deploy:prod	Cloudflare Worker frontend-clients-rnb-logistics
client-tracking-view	Vite / React	🔴 Manual deploy:prod	Cloudflare Worker frontend-tracking-view-rnb-logistics
clients-backend	Hono / Worker + D1	🔴 Manual deploy:prod (+ migraciones D1)	Cloudflare Worker backend-clients-rnb-logistics
drivers-app	Expo / React Native	🔴 Manual OTA eas update	EAS · canal production
engine-web	Estático	No se usa — solo engine-backend (la API) está activo	—
zoho-app	Zoho Creator (Deluge)	🔴 Manual en consola Zoho · el repo es espejo/referencia	Zoho Creator
logistics-process-manual	VitePress	🟢 Auto — Cloudflare Pages buildea al merge a main	Cloudflare Pages
clients-mobile	Expo / RN	Fuera del pipeline de producción	—
demo-printer-scanner-expo	Expo / RN	Demo de hardware, no productivo	—
packages/core-shared	TS compartido	No se despliega; lo consumen core/drivers	—

El runbook con los comandos exactos y la verificación post-deploy está en Despliegue.

Cómo Está Organizada Esta Guía

Setup localToolchain, instalación, env/secrets, base de datos y cómo correr cada app.

Flujo de trabajoGit, worktrees, PRs, ClickUp y la deuda conocida de los checks.

Despliegue (runbook)Comando por comando: Railway/CI, Cloudflare manual, OTA y Zoho.

Referencia por appFicha rápida de cada workspace: dev, test, build, deploy y env.

GotchasDónde vive la lógica no obvia y las trampas que cuestan horas.