Total Archivos
847
3 apps + shared packages
Lenguajes
4
TS principal (412 files)
Config detectados
6
turbo · pnpm · docker · CI
Setup estimado
~8m
En entorno limpio
Arquitectura del Sistema
Monorepo Turborepo · apps/web + apps/api + packages/shared
🌐 Browser / Mobile
↓
HTTPS
▲ Next.js 14
apps/web · Vercel
apps/web · Vercel
→→→
⚡ Fastify API
apps/api · Railway
apps/api · Railway
↓
🐘 PostgreSQL 16
Railway Managed
Railway Managed
🔴 Redis 7
Sessions + Queue
Sessions + Queue
⚙️ GitHub Actions CI/CD · lint → test → deploy
| Capa | Tecnología | Versión | Por qué se eligió | Deploy |
|---|---|---|---|---|
| Frontend | Next.js + Tailwind + shadcn/ui | 14.2 | SSR + App Router + RSC para dashboards de datos en tiempo real | Vercel |
| API | Fastify + Zod + Prisma | 4.28 | 3× más rápido que Express; type-safety end-to-end con Zod schemas | Railway |
| Base de datos | PostgreSQL + Prisma ORM | 16.2 | JSON columns para datos nutricionales variables + JSONB queries | Railway |
| Cache/Queue | Redis + BullMQ | 7.4 | Sesiones, rate limiting, y jobs de cálculo de macros asíncronos | Railway |
| Build | pnpm workspaces + Turborepo | 1.13 | Cache inteligente de builds; pipeline paralelo 60% más rápido | — |
Quick Start — Setup en ~8 minutos
Entorno local completo con Docker, base de datos y seed de datos
| Herramienta | Versión mínima | Instalación | Verificar |
|---|---|---|---|
| Node.js | 20 LTS | nvm install 20 |
node -v |
| pnpm | 8+ | npm i -g pnpm |
pnpm -v |
| Docker Desktop | 24+ | docker.com/get-started | docker ps |
| Git | 2.40+ | Sistema (brew / apt) | git --version |
# 1. Clonar y entrar al repo
git clone git@github.com:nutritrack/nutritrack-pro.git
cd nutritrack-pro
# 2. Instalar dependencias (Turborepo gestiona todo el monorepo)
pnpm install
# 3. Levantar servicios (PostgreSQL 16 + Redis 7)
docker compose up -d
docker compose ps # verificar: nutritrack-db y nutritrack-redis en "running"
# 4. Variables de entorno
cp .env.example .env
# Edita .env → solo DATABASE_URL y REDIS_URL son obligatorias para local
# 5. Migrar y poblar la base de datos
pnpm db:migrate
pnpm db:seed # carga 50 usuarios demo + 200 alimentos USDA
# 6. Arrancar en desarrollo
pnpm dev # web → :3000, api → :4000 (Turborepo en paralelo)
# 7. Verificar
pnpm test # unit + integration tests (Vitest)
Checklist post-setup: App en localhost:3000 · API health en localhost:4000/health devuelve
{"status":"ok"} · Login con demo@nutritrack.dev / password123 funciona · Tests en verde.
Apple Silicon (M1/M2/M3): Añadir
platform: linux/arm64 en docker-compose.yml si los contenedores no levantan. Ver docs/macos-arm.md para pasos completos.
Variables de Entorno
Detectadas en .env.example — requeridas y opcionales para desarrollo local
| Variable | Ejemplo | Requerida | Descripción |
|---|---|---|---|
| DATABASE_URL | postgresql://user:pass@localhost:5432/nutritrack | Sí | Conexión PostgreSQL (Docker local o Railway prod) |
| REDIS_URL | redis://localhost:6379 | Sí | Sessions y BullMQ jobs |
| NEXTAUTH_SECRET | openssl rand -hex 32 | Sí | JWT secret para NextAuth |
| NEXTAUTH_URL | http://localhost:3000 | Sí | Base URL para callbacks OAuth |
| API_URL | http://localhost:4000 | Sí | Fastify API — Next.js la consume en SSR |
| USDA_API_KEY | abc123... (demo key incluida) | Dev incluida | FoodData Central API (límite 1000 req/día en dev key) |
| STRIPE_SECRET_KEY | sk_test_... | Solo billing | Solo necesaria para desarrollar módulo de pagos |
| S3_BUCKET | nutritrack-dev-uploads | Solo uploads | Cloudflare R2 para fotos de alimentos (localstack en dev) |
Archivos Clave del Codebase
Los más importantes detectados por el analyzer · empieza aquí
turbo.json
Pipeline de Turborepo: define qué apps se compilan en paralelo y qué outputs se cachean. Modificar aquí si añades una nueva app al monorepo.
pnpm-workspace.yaml
Define los workspaces: apps/*, packages/*. Añadir un nuevo package aquí primero antes de crearlo.
apps/api/src/routes/nutrition.ts
El archivo más grande (48KB). Contiene todos los endpoints del core: calcular macros, registrar comidas, historial. Aquí está la lógica de negocio principal.
packages/shared/types/index.ts
Tipos TypeScript compartidos entre web y api (31KB). Cambios aquí afectan ambas apps. Siempre regenerar types tras modificar Prisma schema.
apps/api/prisma/schema.prisma
Schema de la base de datos. Después de cualquier cambio: pnpm db:generate && pnpm db:migrate. Los modelos principales: User, FoodLog, NutrientProfile.
apps/web/app/(dashboard)/
App Router de Next.js: todas las páginas del dashboard SaaS. layout.tsx maneja auth guard y sidebar. Organizado por feature (nutrition/, reports/, settings/).
docker-compose.yml
Stack local completo: postgres, redis, localstack (S3 mock). En producción se usan los servicios Railway equivalentes.
.github/workflows/ci.yml
Pipeline CI: lint (ESLint + Prettier) → type-check (tsc) → tests (Vitest) → build. Cada PR debe pasar los 4 pasos. Deploy automático solo en merge a main.
Guía por Perfil
Onboarding adaptado a tu rol y nivel de acceso al sistema
👶
Junior Frontend
apps/web · UI components
- Empieza en
apps/web/app/(dashboard)/nutrition/ - Sigue los tests como documentación ejecutable
- Usa shadcn/ui para todos los componentes nuevos
- No toques apps/api hasta semana 3
- Primer PR: corregir un bug etiquetado good-first-issue
- Pregunta en #dev-frontend antes de crear nuevos hooks
Primera tarea: Añadir campo "notas" al formulario de registro de comida · issue #247
🎓
Senior Backend
apps/api · arquitectura
- Lee
docs/ADR/antes de proponer cambios estructurales - Revisa las queries de Prisma en
nutrition.ts(N+1 latentes) - Monitoriza slow queries en Railway Metrics
- BullMQ workers en
apps/api/src/workers/ - Rate limiting con Redis en
src/plugins/rateLimit.ts - Proponer mejoras de performance en #dev-backend
Primera tarea: Optimizar endpoint GET /food-logs (actualmente 340ms p95) · issue #301
🔌
Contratista Integraciones
Módulo USDA + Stripe
- Scope:
apps/api/src/integrations/únicamente - Usa wrappers existentes en
src/lib/http-client.ts - No modificar Prisma schema sin aprobar con CTO
- Credenciales de terceros: solicitar en #ops con justificación
- Todos los webhooks deben tener idempotency keys
- Tests obligatorios para cada integration (mocks en fixtures/)
Primera tarea: Implementar webhook de Stripe para upgrade de plan · issue #389
Plan de Rampa — Primeros 30 días
Hitos compartidos para todos los perfiles · ajustar según área
Días 1–3
Setup y lectura del código
- Entorno local levantado y verificado (todos los checks en verde)
- Leer este documento y los ADRs relevantes a tu área
- Primera sesión 1:1 con la CTO (30 min)
- Acceso confirmado: GitHub, Railway, Vercel, Linear, Slack
Días 4–10
Primer PR de valor
- Elegir issue etiquetado good-first-issue de tu área
- Hacer pair programming con alguien del equipo core
- PR merged con CI verde y review aprobada
- Documentar cualquier gap o inconsistencia encontrada en la wiki
Días 11–30
Ownership de un módulo
- Responsable de un área técnica específica (asignada en sprint planning)
- Revisar PRs de compañeros en tu área
- Proponer al menos una mejora de DX o performance
- Retrospectiva de onboarding: feedback sobre este documento
Checklist de Contribución
Requisitos para que un PR sea aprobado y mergeado a main
-
CI Pipeline completo en verdelint + tsc + vitest deben pasar. Consultar .github/workflows/ci.yml para los pasos exactos.
-
Tests actualizados o añadidosCoverage no puede bajar del 80% en el módulo afectado. Vitest en apps/api/tests/ y apps/web/__tests__/
-
PR description con el "por qué"Usar template en .github/PULL_REQUEST_TEMPLATE.md. Incluir screenshot si hay cambios de UI.
-
Self-review completoRevisar el diff completo tú mismo antes de solicitar review. Reducir el ruido para los reviewers.
-
Convención de commits (Conventional Commits)feat(nutrition): · fix(auth): · docs: · chore: — sin emojis en el título del commit.
-
Migraciones de BD incluidas si aplicapnpm db:generate después de cambiar schema.prisma. Nunca editar archivos de migración existentes.
-
Variables de entorno documentadasSi añades una variable nueva, actualizar .env.example y este documento.
Guía de Debugging
Errores más comunes en setup y desarrollo day-to-day
Regla de oro: Antes de escalar al equipo, comprueba en orden: (1) variables de entorno, (2) docker compose ps, (3) pnpm db:migrate pendiente, (4) pnpm install tras un git pull.
| Error | Causa probable | Solución |
|---|---|---|
PrismaClientInitializationError |
DATABASE_URL no configurada o DB no levantada | docker compose up -d · verificar .env |
ECONNREFUSED :6379 |
Redis no corriendo | docker compose restart redis |
NextAuthError: No secret |
NEXTAUTH_SECRET vacía en .env | Generar: openssl rand -hex 32 |
Cannot find module '@nutritrack/shared' |
Workspace no linkado | pnpm install en raíz del monorepo |
Migration drift detected |
Cambios de schema sin migrar | pnpm db:migrate --name fix |
| Tests lentos (>60s) | Cache de Turborepo invalidada | pnpm turbo clean && pnpm test |