Onboarding para nuevos

Esta guía asume que eres un desarrollador (frontend o backend) que va a colaborar. Si solo necesitas entender el producto a alto nivel, anda a visión.

1. Accesos a pedir (antes de tocar código)

Pídele al dueño del proyecto que te dé acceso a:

Servicio	Para qué	Quién lo provee
GitHub yoeldtrujillo	Repos tcgcards-web, tcgcards-api, tcgcards-docs	Yoel
Vercel team	Deploys y env vars del frontend	Yoel
GCP project api-cards-prod	Cloud Run, Cloud Scheduler, Secret Manager	Yoel
MongoDB Atlas	BD productiva (read-only para empezar)	Yoel
Cloudflare team	DNS, Email Routing, Pages, Access	Yoel
Cloudinary	Storage de imágenes	Yoel
Resend	Email outbound	Yoel
Mercado Pago	Pagos (panel)	Yoel
Sentry	Errores	Yoel
PostHog	Eventos	Yoel
Google Cloud Console (OAuth)	Configuración del login Google	Yoel

Tu email tiene que estar en el whitelist de Cloudflare Access también para acceder a este sitio de docs.

2. Herramientas a instalar

Lista mínima para trabajar:

# Node 20+ (recomendado: nvm o asdf para manejar versiones)
node --version  # debería ser >= 20

# Git (probablemente ya tienes)
git --version

# Google Cloud SDK
brew install --cask google-cloud-sdk
gcloud auth login
gcloud config set project api-cards-prod

# (opcional) Vercel CLI si vas a manejar el frontend desde CLI
npm install -g vercel
vercel login

# MongoDB tools (para backups/restores)
brew tap mongodb/brew
brew install mongodb-database-tools
brew install mongodb-community  # opcional, para Mongo local

Editor recomendado: VS Code o Cursor con la extensión Astro (para este repo de docs) y la oficial de TS.

3. Clonar los repos

mkdir -p ~/Documents/Repos && cd ~/Documents/Repos

git clone git@github.com:yoeldtrujillo/tcgcards-web.git
git clone git@github.com:yoeldtrujillo/tcgcards-api.git
git clone git@github.com:yoeldtrujillo/tcgcards-docs.git

4. Levantar tcgcards-api local

cd ~/Documents/Repos/tcgcards-api

# Instalar dependencias
npm install

# Copiar .env.example a .env
cp .env.example .env

# Editar .env y llenar valores. Opciones:
# a) Para los secrets reales: leer desde GCP Secret Manager
#    gcloud secrets versions access latest --secret=MONGODB_URI --project=api-cards-prod
# b) Para Mongo: usar tu Mongo local o un cluster Atlas tuyo de dev
# c) Para Cloudinary/Resend/MP: crear cuentas free de prueba

# Build + tests + dev
npm run build  # verifica que typecheck pase
npm test       # corre tests (con mongodb-memory-server)
npm run dev    # arranca en http://localhost:3000

Lista de envs requeridas: ver variables de entorno.

5. Levantar tcgcards-web local

cd ~/Documents/Repos/tcgcards-web

npm install
cp .env.example .env.local

# Editar .env.local:
# - TCGCARDS_API_URL=http://localhost:3000  (o la URL de tu api local)
# - NEXT_PUBLIC_API_URL=http://localhost:3000
# - NEXT_PUBLIC_SITE_URL=http://localhost:3000
# - AUTH_SECRET=$(openssl rand -hex 32)
# - AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET = pedir a Yoel un set de dev en Google Cloud Console
# - INTERNAL_JWT_SECRET y INTERNAL_AUTH_SECRET = el MISMO valor que tu tcgcards-api local

npm test
npm run dev    # arranca en http://localhost:3000

# (NOTA: tcgcards-api también default es 3000. Si vas a levantar ambos, cambia el PORT
# del api a 3001 y ajusta TCGCARDS_API_URL en tcgcards-web a http://localhost:3001.)

Abre http://localhost:3000 en el browser. Login con Google debería funcionar contra tu credencial de dev.

6. Levantar tcgcards-docs local (este sitio)

cd ~/Documents/Repos/tcgcards-docs

npm install
npm run dev    # arranca en http://localhost:4321

No requiere env vars.

7. Conceptos clave que tienes que entender

Antes de tocar código, lee en este orden:

1. Visión del producto — qué hacemos
2. Stack y arquitectura — cómo está armado
3. Servicios — los repos y cómo se relacionan
4. Glosario — términos del dominio (no inventes sinónimos)
5. Decisiones técnicas — por qué hicimos las cosas así
6. CLAUDE.md y AGENTS.md de cada repo — convenciones del codebase

8. Tu primer cambio

Recomendaciones para empezar suave:

• Frontend: arreglar algún string de copy en una página estática. Editas → npm run dev → ves el cambio → commit → push → Vercel deploya automáticamente.
• Backend: corregir un mensaje de log o agregar un campo opcional a un endpoint existente. Editas → npm test → push → pídele a Yoel que deploye con gcloud run deploy.

Nunca hagas un deploy a producción sin OK explícito. Vercel deploya automático en push, pero revisas antes de mergear a main.

9. Convenciones que NO puedes violar

Regla	Por qué
No usar voseo argentino (querés/podés/iniciá)	Audiencia chilena
No hardcodear hex de colores en componentes UI	Tokens shadcn solo
Backend usa CLP cents (integer)	Aritmética de floats da errores
import 'server-only' en archivos con secrets	Falla en build si filtran al client
Schemas Mongoose nullable = default: null (no required: true)	Inserts fallan con bug raro si están desalineados
Switch sobre kind exhaustivo (default: const _exhaustive: never)	Bug histórico con bulk listings
Stock-dependent reads sin cache	Mostrar stock viejo lleva a “no hay stock” en checkout
No deployar prod sin OK	tcgcards está productivo con MP integrado

10. ¿Dónde busco cuando no sé?

• Este sitio primero. Search arriba a la derecha.
• CLAUDE.md / AGENTS.md del repo correspondiente.
• docs/superpowers/specs/ y docs/superpowers/plans/ en tcgcards-api para decisiones detalladas históricas.
• Sentry para errores en prod.
• Yoel para decisiones de producto / negocio.

11. Comandos útiles del día a día

# Frontend
npm run dev                 # arranca local
npm test                    # tests
npm run build               # typecheck + build prod

# Backend
npm run dev                 # arranca local (con tsx watch)
npm test                    # tests (incluye integration con mongo in-memory)
npm run build               # tsc
npm run sync:initial        # rebuilds catalog desde TCGplayer (cuidado)
npm run sync:incremental    # syncs catalog cambios incrementales

# Cloud Run
gcloud run services describe tcgcards-api --region us-central1 --project api-cards-prod
gcloud run services logs read tcgcards-api --region us-central1 --project api-cards-prod --limit 100

# Cloud Scheduler (crons)
gcloud scheduler jobs list --project api-cards-prod --location us-central1
gcloud scheduler jobs run <job-name> --project api-cards-prod --location us-central1

# Mongo (si vas a inspeccionar prod directo)
mongosh "<MONGODB_URI>"

# Secrets
gcloud secrets versions access latest --secret=MONGODB_URI --project api-cards-prod

Cualquier duda, abrir issue en el repo correspondiente o preguntar directo a Yoel.