Onboarding Dev — Fundamental Playbooks

Setup del entorno

Llegar a tu primer PR debería tomarte menos de una mañana. Si algo de esta guía falla, no pierdas tiempo — avisá en #dev.

Prerrequisitos

Node.js ≥ 20 LTS

node --version ↗

Git ≥ 2.40

git --version ↗

Docker ≥ 24

docker --version ↗

PNPM ≥ 9

pnpm --version ↗

VS Code última stable

code --version ↗

GitHub CLI ≥ 2.40

gh --version ↗

Pasos

Cloná los repos

mkdir -p ~/fundamental && cd ~/fundamental
git clone git@github.com:fundamental-lat/api.git
git clone git@github.com:fundamental-lat/web.git

Pedí acceso a los repos si no los tenés. El lead tech te agrega al equipo de GitHub.

Instalá dependencias

cd api && pnpm install
cd ../web && pnpm install

Si falla por node-gyp o native modules, revisá que tengas build-essential (Linux) o XCode CLI tools (macOS).

Configurá variables de entorno

cp .env.example .env
# Editá .env con tus valores locales

Pedí el .env de desarrollo al lead. Nunca uses secrets de producción en local.

Levantá los servicios

docker compose up -d  # PostgreSQL, Redis, etc.
pnpm dev                   # API en :3000
# En otra terminal:
cd web && pnpm dev         # Frontend en :5173

Si los puertos están ocupados, cambiá en .env. Docker debe estar corriendo.

Corré migrations y seeds

cd api && pnpm db:migrate && pnpm db:seed

Esto crea la DB local con datos de prueba. Si falla, revisá que PostgreSQL esté corriendo en Docker.

Verificación — sabés que está bien cuando...

API responde en localhost:3000/health 200 OK con {"status":"ok"}

Frontend carga en localhost:5173 Pantalla de login sin errores en consola

Tests pasan: pnpm test Todos verdes, 0 failures

Linter no grita: pnpm lint 0 errors, 0 warnings

Podés crear un usuario de prueba POST /api/auth/register → 201

Arquitectura del sistema

Entender la estructura te ahorra horas de exploración. Cada capa tiene un propósito claro y una interfaz definida con las demás.

Frontend Astro + React

SSG con islas interactivas. Componentes en src/components, páginas en src/pages. Server-side donde se pueda, client-side solo donde sea necesario.

API Node.js + Fastify

REST en /api/v1. Autenticación con JWT. Validación con Zod. Patrón repository para acceso a datos.

Database PostgreSQL 16

Migrations con Drizzle ORM. Índices para búsquedas frecuentes. Nunca SQL raw — siempre a través del ORM o repositorios.

Cache Redis

Session store y cache de queries frecuentes. TTLs definidos por tipo de dato. No cachear datos de usuario por sesión.

Queue BullMQ + Redis

Jobs asíncronos: emails, webhooks, procesamiento de archivos. Retry con backoff exponencial.

Infra Docker + Fly.io

CI/CD con GitHub Actions. Staging automático por PR. Producción con deploy manual aprobado.

Decisiones clave — por qué elegimos lo que elegimos

¿Por qué Fastify y no Express?

Más rápido, schema validation nativo con JSON Schema, mejor soporte de TypeScript. Performance consistente bajo carga.

¿Por qué Astro y no Next.js?

El frontend es mayormente contenido estático con pocas islas interactivas. Astro manda 0KB de JS por defecto vs ~100KB de Next.

¿Por qué Drizzle y no Prisma?

Drizzle es más liviano (0 dependencias), las migraciones son archivos SQL que podés leer, y el rendimiento es cercano al SQL nativo.

¿Por qué PNPM y no NPM?

Instalación más rápida, node_modules estricto (no accedés a deps que no declaraste), ahorra disco.

Tu primer PR

Una guía paso a paso desde que agarrás un ticket hasta que tu código está en producción. Cada paso existe por un motivo — la disciplina temprana evita el caos futuro.

1️⃣

Agarrá un ticket

Buscá en GitHub Issues algo con label good first issue. Asignátelo y movelo a In Progress en el board.

2️⃣

Creá tu branch

git checkout -b feat/mi-primer-feature. Seguí la convención de branches del Git Playbook.

3️⃣

Escribí el código

Empezá por los tests si la feature lo permite (TDD). Mantené las funciones chicas, los nombres claros. Si tocás más de 3 archivos, preguntá.

4️⃣

Corré tests y lint local

pnpm test && pnpm lint. Si algo falla, arreglalo antes de pushear. No delegues eso al CI.

5️⃣

Commiteá con Conventional Commits

git add -p (revisá cada cambio antes de stagggear). Commits atómicos con mensajes que expliquen el porqué.

6️⃣

Abrí el PR

Usá el template de PR. Describí qué, por qué y cómo probarlo. Agregá screenshots si es UI. Asigná reviewers.

7️⃣

Respondé al review

Los comentarios no son personales. Cada sugerencia es una oportunidad de aprender. Si no entendés algo, preguntá — es esperado.

8️⃣

Mergeá

Squash and merge (default). Si tu PR tiene commits valiosos individualmente, hacé rebase. Si dudás, preguntá.

9️⃣

Celebrá y verificá en staging

Tu código ya está en staging. Verificá que funcione como esperabas. Cerrá el issue. Actualizá el board.

Errores comunes de primerizo

❌ Pushear sin correr tests locales

✅ Corré pnpm test siempre antes de pushear. El CI tarda más y el feedback es más lento.

❌ PR con 40 archivos y 3 features distintas

✅ Dividí en PRs chicos. Un PR = una responsabilidad. Si el ticket es muy grande, pedí que lo partan.

❌ No leer el .env.example completo

✅ Leelo entero. Cada variable tiene un comentario explicando qué hace y qué valores posibles tiene.

❌ Commitear node_modules o .env

✅ Revisá el .gitignore. Si algo que no debería se commiteó, avisá rápido.

❌ Pasar 3 días sin pushear ni preguntar

✅ Hacé push de WIP al final del día. Preguntá en el canal #dev apenas te trabás. No existe la pregunta tonta a los 3 días.

A quién preguntar qué

La pregunta correcta a la persona correcta ahorra horas. No le preguntes al tech lead dónde está el Figma — para eso está esta tabla.

Tech Lead

Arquitectura, decisiones técnicas, code review bloqueante, permisos de repo

Frontend Lead

Componentes, diseño, accesibilidad, performance del cliente

Backend Lead

Endpoints, base de datos, queues, workers

DevOps

CI/CD roto, staging caído, Docker, secrets, dominios

Product Owner

Requerimientos, prioridad de tickets, criterios de aceptación

Design

Figma, componentes de diseño, flujos de usuario, copy

Casos de prueba, datos de test, bugs en staging

Links importantes

Repositorio API github.com/fundamental-lat/api Repositorio Web github.com/fundamental-lat/web Staging API api.staging.fundamental.lat Staging Web staging.fundamental.lat Documentación interna docs.fundamental.lat Figma del proyecto figma.com/fundamental CI / GitHub Actions github.com/fundamental-lat/api/actions Monitoreo status.fundamental.lat 1Password (secrets) fundamental.1password.com

Canales de comunicación

# #dev Slack

Dudas técnicas del día a día. Código, bugs, PRs.

# #general Slack

Anuncios del equipo, demos, planning.

# #alerts Slack

Incidentes en producción. Solo para emergencias.

# Daily (9:30 AM) Google Meet

Qué hice, qué voy a hacer, qué me bloquea. 15 min máx.

# Sprint Planning Google Meet

Lunes cada 2 semanas. Planificamos el sprint.

# Retro Google Meet

Viernes al final del sprint. Qué salió bien, qué mejorar.