Guia de Desarrollo Local

1. Prerequisitos

Antes de comenzar, asegurate de tener instaladas las siguientes herramientas:

1.1 Verificar instalaciones

node --versión    # v20.x.x
npm --versión     # 10.x.x
docker --versión  # Docker versión 2x.x.x
git --versión     # git versión 2.x.x
eas --versión     # eas-cli/15.x.x
eas whoami        # Debe mostrar tu usuario de Expo

Asegurate de que Docker Desktop este en ejecución antes de continuar.

2. Setup Paso a Paso

2.1 Instalar bws CLI (Bitwarden Secrets Manager)

El proyecto utiliza Bitwarden Secrets Manager para gestionar secretos. El CLI bws inyecta variables de entorno en tiempo de ejecución sin necesidad de archivos .env con secretos reales.

# macOS (descarga directa)
curl -fsSL "https://github.com/bitwarden/sdk-sm/releases/latest/download/bws-aarch64-apple-darwin.zip" -o bws.zip
unzip bws.zip -d /tmp/bws && mv /tmp/bws/bws ~/.local/bin/bws && chmod +x ~/.local/bin/bws
rm bws.zip

# Agregar a ~/.zshrc
export BWS_ACCESS_TOKEN="<token del machine account local-dev>"
export BWS_PROJECT_LOCAL="<project ID de nvito-local>"

# Recargar shell y verificar
source ~/.zshrc
bws secret list

Solicita al administrador del proyecto el BWS_ACCESS_TOKEN y el BWS_PROJECT_LOCAL correspondientes al machine account local-dev.

2.2 Clonar los repositorios

Clona los seis repositorios en un mismo directorio padre para mantener la estructura organizada:

mkdir -p ~/desarrollo/Nvito && cd ~/desarrollo/Nvito

git clone <url-repo>/nvito-api.git
git clone <url-repo>/nvito-admin.git
git clone <url-repo>/nvito-invitations.git
git clone <url-repo>/nvito-client.git
git clone <url-repo>/nvito-pwa.git
git clone <url-repo>/nvito-landing.git

2.3 Instalar dependencias

Ejecuta npm install en cada proyecto:

cd ~/desarrollo/Nvito/nvito-api && npm install
cd ~/desarrollo/Nvito/nvito-admin && npm install
cd ~/desarrollo/Nvito/nvito-invitations && npm install
cd ~/desarrollo/Nvito/nvito-client && npm install
cd ~/desarrollo/Nvito/nvito-pwa && npm install
cd ~/desarrollo/Nvito/nvito-landing && npm install

2.4 Crear volumenes Docker (primera vez)

El docker-compose.yml del API utiliza volumenes externos. Deben crearse una sola vez:

docker volume create invitia-api_postgres_data
docker volume create invitia-api_redis_data
docker volume create invitia-api_minio_data

2.5 Levantar servicios Docker

Desde el directorio del API, levantar la infraestructura local:

cd ~/desarrollo/Nvito/nvito-api
npm run docker:up

Esto levanta los siguientes contenedores:

Verifica que todos los contenedores esten corriendo:

docker ps

2.6 Configurar variables de entorno

Cada proyecto tiene archivos de entorno preconfigurados para desarrollo local:

# En nvito-api
cd ~/desarrollo/Nvito/nvito-api
npm run env:dev

# En nvito-admin
cd ~/desarrollo/Nvito/nvito-admin
npm run env:dev

# En nvito-invitations
cd ~/desarrollo/Nvito/nvito-invitations
npm run env:dev

Estos comandos copian el archivo config/environments/.env.development a .env en la raiz de cada proyecto.

2.7 Ejecutar migraciones y seed (nvito-api)

cd ~/desarrollo/Nvito/nvito-api

# Generar el cliente Prisma
npm run db:generate

# Aplicar migraciones a la base de datos local
npm run db:migrate

# Poblar datos iniciales (Super Admin, Event Types, Packages, Templates)
npm run db:seed

Alternativamente, el comando setup ejecuta todo el flujo completo:

npm run setup
# Equivale a: env:dev -> docker:up -> (espera 5s) -> db:generate -> db:migrate -> db:seed

2.8 Iniciar los servicios

Abre varias terminales separadas y ejecuta cada servicio. Si los secretos se gestiónan via Bitwarden, utiliza los comandos dev:bws:

Terminal 1 -- API (NestJS):

cd ~/desarrollo/Nvito/nvito-api
npm run dev:bws
# O sin Bitwarden: npm run start:dev

Terminal 2 -- Admin (Next.js):

cd ~/desarrollo/Nvito/nvito-admin
npm run dev:bws
# O sin Bitwarden: npm run dev

Terminal 3 -- Invitations (Next.js):

cd ~/desarrollo/Nvito/nvito-invitations
npm run dev:bws
# O sin Bitwarden: npm run dev

Terminal 4 -- Client (React Native + Expo):

cd ~/desarrollo/Nvito/nvito-client
npx expo start --dev-client
# Escanear QR con el dev client instalado en el dispositivo/simulador

# Para simulador iOS (gratis):
eas build --platform ios --profile development-simulator

# Para iPhone fisico (requiere Apple Developer $99/año):
eas build --platform ios --profile development

# Para Android fisico:
eas build --platform android --profile development

npx expo start --dev-client

Terminal 5 -- PWA (Next.js):

cd ~/desarrollo/Nvito/nvito-pwa
npm run dev
# Puerto 3002

Terminal 6 -- Docs (Next.js):

cd ~/desarrollo/Nvito/nvito-docs
npm run dev
# Puerto 3333

Terminal 7 -- Landing (Astro):

cd ~/desarrollo/Nvito/nvito-landing
npm run dev
# Puerto 4321

2.9 Instalar hooks de Git (Husky)

Los 5 repositorios de código incluyen Husky con un pre-commit hook que detecta secrets automáticamente antes de cada commit. Se instala al ejecutar npm install (via prepare script).

Que detecta el hook:

• Claves de Stripe (sk_live_, sk_test_, pk_live_)
• Claves de OpenAI (sk-)
• Claves de Anthropic (sk-ant-)
• SIDs de Twilio (SK, AC)
• Claves privadas (-----BEGIN.*PRIVATE KEY-----)
• Tokens JWT hardcodeados
• Otros patrones de secrets comunes

Como funciona:

# Al hacer git commit, el hook se ejecuta automáticamente
git commit -m "feat: nueva funcionalidad"
# Si detecta un secret → bloquea el commit con mensaje de error

# Si es un falso positivo, se puede omitir el hook:
git commit -m "feat: nueva funcionalidad" --no-verify

Verificar que Husky está instalado:

ls .husky/pre-commit  # Debe existir en cada repo

Si el hook no existe, reinstalar:

npx husky install

3. Comandos Utiles

3.1 nvito-api (NestJS + Prisma)

3.2 nvito-admin (Next.js)

3.3 nvito-invitations (Next.js)

3.4 nvito-pwa (Next.js)

3.5 nvito-docs (Next.js)

3.6 nvito-landing (Astro)

4. URLs Locales

Una vez que todos los servicios estan corriendo, estás son las URLs disponibles:

4.1 Aplicaciones

4.2 Herramientas de infraestructura

4.3 Servicios internos (sin UI web)

5. Troubleshooting

5.1 Docker Compose falla al iniciar

Problema: Error volume "invitia-api_postgres_data" not found

Solución: Los volumenes son externos y deben crearse manualmente la primera vez:

docker volume create invitia-api_postgres_data
docker volume create invitia-api_redis_data
docker volume create invitia-api_minio_data

5.2 Puerto ya en uso

Problema: Error: listen EADDRINUSE: address already in use :::3000

Solución: Identificar y detener el proceso que ocupa el puerto:

# Buscar el proceso
lsof -i :3000

# Terminar el proceso
kill -9 <PID>

Puertos comunes que pueden entrar en conflicto: 3000 (API), 5050 (Admin), 3001 (Invitations), 3002 (PWA), 3333 (Docs), 4321 (Landing), 5432 (PostgreSQL), 6379 (Redis), 8080 (Adminer).

5.3 Prisma: migraciones fallan

Problema: Error: P3009 — migrate found failed migrations

Solución: Reiniciar la base de datos desde cero:

npm run docker:clean    # Elimina contenedores y volumenes
# Recrear volumenes
docker volume create invitia-api_postgres_data
docker volume create invitia-api_redis_data
docker volume create invitia-api_minio_data
npm run setup           # Levanta todo de nuevo con datos limpios

5.4 Error de conexión a PostgreSQL

Problema: Error: P1001 — Can't reach database server at localhost:5432

Solución: Verificar que el contenedor de PostgreSQL este corriendo y saludable:

docker ps | grep nvito-postgres
docker logs nvito-postgres

Si el contenedor no aparece, levantar los servicios de nuevo:

npm run docker:up

5.5 bws: comando no encontrado

Problema: zsh: command not found: bws

Solución: Verificar que bws este en el PATH:

# Verificar ubicación
ls ~/.local/bin/bws

# Si existe pero no está en PATH, agregar a ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
source ~/.zshrc

5.6 bws: token inválido o expirado

Problema: Error: Unauthorized al ejecutar bws secret list

Solución: Solicitar un nuevo access token al administrador del proyecto y actualizar la variable BWS_ACCESS_TOKEN en ~/.zshrc.

5.7 MinIO: buckets no se crean automáticamente

Problema: El contenedor nvito-minio-client sale con error.

Solución: Verificar que MinIO este saludable antes de que el client intente conectarse:

docker logs nvito-minio-client
# Si fallo, reiniciar solo el client:
docker restart nvito-minio-client

Los buckets que deben existir son: nvito-uploads, nvito-assets, nvito-private, nvito-templates.

5.8 Emails no aparecen en MailDev

Problema: Al enviar un email desde el API, no aparece en http://localhost:1080.

Solución: Verificar que el .env del API tenga la configuración SMTP apuntando a MailDev:

SMTP_HOST=localhost
SMTP_PORT=1025

MailDev no requiere autenticación. Si las variables SMTP_USER y SMTP_PASSWORD estan vacias, nodemailer omite la autenticación automáticamente.

5.9 Next.js: cambios en variables NEXT_PUBLIC no se reflejan

Problema: Después de modificar una variable NEXT_PUBLIC_*, el frontend sigue usando el valor anterior.

Solución: Las variables con prefijo NEXT_PUBLIC_ se inyectan en build time. Es necesario reiniciar el servidor de desarrollo:

# Detener el proceso (Ctrl+C) y volver a iniciar
npm run dev

6. Tips de Desarrollo

6.1 Hot Reload

Los seis proyectos soportan hot reload en modo desarrollo:

• nvito-api: nest start --watch recompila automáticamente al detectar cambios en archivos .ts. Se activa con npm run start:dev.
• nvito-admin: Next.js Fast Refresh actualiza la página sin perder el estado de React.
• nvito-invitations: Mismo comportamiento de Fast Refresh de Next.js.
• nvito-pwa: Next.js Fast Refresh.
• nvito-docs: Next.js Fast Refresh. Cambios en MDX se reflejan automáticamente.
• nvito-landing: Astro hot reload nativo con Vite.

Nota: Los cambios en el schema de Prisma (prisma/schema.prisma) requieren regenerar el cliente manualmente:

npm run db:generate

Si se agregan nuevas migraciones, ejecutar también:

npm run db:migrate

6.2 Debugging del API

Para depurar el backend con breakpoints desde VS Code:

1. Iniciar el API en modo debug:

   npm run start:debug
   # O con Bitwarden: npm run dev:bws:debug
   

2. En VS Code, abrir la paleta de comandos y seleccionar Debug: Attach to Node Process.
3. Seleccionar el proceso de NestJS (puerto 9229).

Alternativamente, agregar esta configuración a .vscode/launch.json:

{
  "type": "node",
  "request": "attach",
  "name": "Attach NestJS",
  "port": 9229,
  "restart": true,
  "sourceMaps": true
}

6.3 Herramientas para la base de datos

Hay tres opciones para explorar y modificar datos en la base de datos local:

6.4 Inspeccionar colas de trabajo (Bull)

El API utiliza Bull (basado en Redis) para procesar trabajos en segundo plano (emails, imagenes, etc.). Para inspeccionar las colas:

# Conectarse a Redis
docker exec -it nvito-redis redis-cli

# Ver todas las colas de Bull
KEYS bull:*

# Ver trabajos pendientes en una cola
LRANGE bull:<nombre-cola>:wait 0 -1

6.5 Probar uploads de archivos

MinIO funciona como reemplazo local de Cloudflare R2. Los archivos subidos son accesibles via:

• MinIO Console (http://localhost:9001): navegar visualmente por los buckets.
• URL directa: http://localhost:9000/<nombre-bucket>/<ruta-archivo>.

Los buckets nvito-uploads, nvito-assets y nvito-templates tienen politica de acceso público. El bucket nvito-private requiere autenticación.

6.6 Ejecutar tests antes de hacer push

Para evitar fallos en el pipeline CI/CD, ejecutar estos comandos antes de cada push:

# En nvito-api
cd ~/desarrollo/Nvito/nvito-api
npm run format          # Auto-corrige formato con Prettier
npm run lint:fix        # Auto-corrige errores de ESLint
npm run lint            # Verifica que no queden errores
npm run test            # Ejecuta tests unitarios

# En nvito-admin y nvito-invitations
npm run lint

# En nvito-pwa
cd ~/desarrollo/Nvito/nvito-pwa
npm run lint
npm run test:run

# En nvito-client
cd ~/desarrollo/Nvito/nvito-client
npx tsc --noEmit
npm run test:run

6.7 Resetear el entorno completo

Si el entorno local queda en un estado inconsistente, es posible reiniciar todo desde cero:

cd ~/desarrollo/Nvito/nvito-api
npm run dev:reset
# Equivale a: docker:clean -> setup (env:dev -> docker:up -> db:generate -> db:migrate -> db:seed)

Advertencia: Este comando elimina todos los datos de la base de datos, Redis y MinIO. Solo usarlo cuando sea necesario.

API Interactiva (Scalar)

Nvito incluye documentación interactiva de la API usando Scalar (basada en OpenAPI/Swagger). Esta herramienta permite probar los endpoints directamente desde el navegador.

Como acceder

1. Asegurate de que nvito-api está corriendo localmente (npm run start:dev)
2. Abre en tu navegador: http://localhost:3000/api/docs
3. La interfaz Scalar te permite:
   • Ver todos los endpoints organizados por modulo
   • Probar requests con datos de ejemplo
   • Ver schemas de request/response
   • Autenticarte con JWT para endpoints protegidos

Autenticación en Scalar

Para probar endpoints protegidos:

1. Obtener un token JWT de Clerk (desde nvito-admin → DevTools → Application → Cookies)
2. En Scalar, click en "Authorize" → pegar el token como Bearer
3. Ahora puedes hacer requests a endpoints autenticados

Nota: Scalar solo está disponible en desarrollo local. No se expone en ambientes DEV/TEST/Producción.

Referencias

• Infraestructura y Ambientes -- Configuración de ambientes remotos DEV y TEST
• Arquitectura del Sistema -- Arquitectura del sistema
• API Backend -- Documentación del API backend