🛠️ Guía de Setup Completo

Visión General

Esta guía te llevará paso a paso para configurar el entorno de desarrollo completo de PuntoHack.

Requisitos Previos

Ver Prerequisites para requisitos detallados.

Paso 1: Clonar y Configurar

1.1 Clonar Repositorio

git clone <repository-url>
cd puntohack

1.2 Instalar Dependencias

pnpm install

1.3 Configurar Variables de Entorno

Crea .env.local en la raíz:

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard

# Database (Supabase)
DATABASE_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres?pgbouncer=true
DIRECT_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres

# Supabase Realtime
NEXT_PUBLIC_SUPABASE_URL=https://[PROJECT_ID].supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Sentry (Opcional)
SENTRY_DSN=https://...@sentry.io/...
SENTRY_AUTH_TOKEN=tu-token-de-sentry

# UploadThing (Opcional, para uploads de archivos)
UPLOADTHING_TOKEN=tu-token
UPLOADTHING_APP_ID=tu-app-id

# Cron Job
CRON_SECRET=tu-secret-super-seguro-aqui

Paso 2: Configurar Base de Datos

2.1 Generar Prisma Client

pnpm db:generate

2.2 Aplicar Schema

pnpm db:push

2.3 (Opcional) Abrir Prisma Studio

pnpm db:studio

Esto abre una interfaz visual en http://localhost:5555 para explorar la base de datos.

Paso 3: Configurar Supabase Realtime

3.1 Habilitar Realtime

1. Ve a Supabase Dashboard
2. Database → Replication
3. Habilita Realtime para:
   • Hackathon
   • Submission
   • Score
   • ChallengeEvaluation
   • Notification
   • Team

3.2 Configurar RLS

Ejecuta las políticas SQL desde Supabase Realtime Configuration.

Paso 4: Seed de Datos (Opcional)

4.1 Seed de Usuarios

pnpm db:seed:users

4.2 Seed de Hackathons

pnpm db:seed:hackathons

4.3 Seed Completo

pnpm db:seed

Paso 5: Ejecutar en Desarrollo

5.1 Iniciar Servidor

Por defecto, PuntoHack usa Turbopack para un desarrollo más rápido:

pnpm dev

Esto ejecuta next dev --turbo automáticamente.

Alternativas:

• pnpm dev:turbo - Explícitamente con Turbopack
• pnpm dev:webpack - Usar Webpack (si necesitas compatibilidad)

La aplicación estará en http://localhost:3000

5.2 Verificar Instalación

1. Visita http://localhost:3000
2. Deberías ver la página de inicio
3. Intenta registrarte en /sign-up
4. Completa el onboarding
5. Deberías ser redirigido al dashboard

Paso 6: Configurar Usuario Admin

Opción A: Desde Prisma Studio

1. Abre pnpm db:studio
2. Ve a tabla Profile
3. Busca tu perfil
4. Cambia role a ADMIN
5. Guarda

Opción B: Desde Script

# Crear script temporal
cat > scripts/set-admin.ts << 'EOF'
import { db } from '../src/core/db';

async function setAdmin(email: string) {
  const profile = await db.profile.update({
    where: { email },
    data: { role: 'ADMIN' },
  });
  console.log(`✅ ${profile.name} es ahora ADMIN`);
}

setAdmin('tu-email@example.com');
EOF

# Ejecutar
pnpm exec tsx scripts/set-admin.ts

Estructura del Proyecto

puntohack/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (routes)/           # Rutas públicas/privadas
│   │   ├── api/                # API routes
│   │   └── ...
│   ├── core/                   # Infraestructura core
│   │   ├── rbac.ts
│   │   ├── auth.ts
│   │   ├── db.ts
│   │   ├── errors.ts
│   │   └── validations.ts
│   ├── modules/                # Módulos de dominio
│   │   ├── users/
│   │   ├── hackathons/
│   │   ├── teams/
│   │   └── ...
│   ├── components/             # UI Components
│   └── lib/                    # Utilities
├── prisma/
│   └── schema.prisma           # Schema de base de datos
├── tests/                      # Tests
└── scripts/                    # Scripts de utilidad

Comandos Útiles

Desarrollo

# Iniciar servidor de desarrollo (Turbopack por defecto)
pnpm dev

# Iniciar explícitamente con Turbopack
pnpm dev:turbo

# Iniciar con Webpack (alternativa)
pnpm dev:webpack

# Type checking
pnpm type-check

# Linting
pnpm lint

Base de Datos

# Generar Prisma Client
pnpm db:generate

# Aplicar schema
pnpm db:push

# Abrir Prisma Studio
pnpm db:studio

# Seed de datos
pnpm db:seed

Testing

# Ejecutar tests
pnpm test

# Tests con coverage
pnpm test:coverage

# Tests en watch mode
pnpm test --watch

Build

# Build para producción
pnpm build

# Iniciar servidor de producción
pnpm start

Verificación de Setup

Checklist

• Node.js >= 20.0 instalado
• pnpm instalado
• Variables de entorno configuradas
• Base de datos conectada
• Prisma Client generado
• Schema aplicado
• Supabase Realtime habilitado
• Servidor de desarrollo funcionando
• Usuario admin creado
• Tests pasando

Test Rápido

# 1. Verificar conexión a DB
curl http://localhost:3000/api/test-db

# 2. Ejecutar tests
pnpm test

# 3. Verificar tipos
pnpm type-check

Troubleshooting

Error: "Prisma Client not generated"

pnpm db:generate

Error: "Database connection failed"

1. Verifica DATABASE_URL en .env.local
2. Verifica que Supabase esté activo
3. Verifica credenciales

Error: "Clerk authentication failed"

1. Verifica keys de Clerk en .env.local
2. Verifica que sean del mismo proyecto
3. Reinicia el servidor

Error: "Supabase Realtime not configured"

1. Verifica variables NEXT_PUBLIC_SUPABASE_*
2. Verifica que Realtime esté habilitado en Supabase
3. Verifica políticas RLS

Próximos Pasos

• Coding Standards - Estándares de código
• Module Guide - Cómo crear módulos
• Testing Guide - Guía de testing

---

¿Problemas? → Troubleshooting