Saltar al contenido principal

📖 Introducción a PuntoHack

¿Qué es PuntoHack?​

PuntoHack es una plataforma completa de gestión de hackathons que permite:

  • 👥 Organizadores: Crear y gestionar hackathons con criterios de evaluación personalizados
  • 🎯 Participantes: Registrarse, formar equipos y enviar proyectos
  • ⚖️ Jueces: Evaluar proyectos con sistema de scoring ponderado
  • 🏆 Sponsors: Crear challenges y hacer shortlist de proyectos favoritos
  • 👨‍💼 Admins: Gestión completa del sistema

🎯 Propósito del Proyecto​

Este proyecto fue desarrollado como un MVP completo y funcional, enfocado en:

  1. Lógica de negocio robusta: RBAC, validaciones exhaustivas, Server Actions
  2. Base de datos bien diseñada: Prisma + Supabase con relaciones complejas
  3. Testing completo: 80%+ coverage del core
  4. Frontend funcional: Next.js estándar, sin librerías UI innecesarias

🏗️ Filosofía del MVP​

Principios de Diseño​

  • ✅ Arquitectura modular y escalable (Core + Modules)
  • ✅ Sistema de roles robusto (RBAC) - Autorización en cada acción
  • ✅ Type-safety completo (TypeScript + Zod)
  • ✅ Validaciones exhaustivas - Nunca confiar en el cliente
  • ✅ Testing desde el inicio - 80%+ coverage
  • ✅ Next.js estándar - App Router, Server Components, Server Actions
  • ⚠️ MVP Estricto - Solo lo documentado, sin extras

Enfoque del Frontend​

El frontend es profesional pero minimalista:

  • ✅ HTML nativo + Tailwind CSS
  • ✅ Formularios HTML con Server Actions
  • ✅ Server Components por defecto
  • ✅ Client Components solo cuando es necesario
  • ❌ Sin librerías UI complejas (Radix, shadcn/ui, etc.)

🛠️ Stack Tecnológico​

Core (Prioridad #1)​

  • Prisma 6.x - ORM para PostgreSQL
  • Supabase - Base de datos PostgreSQL + Realtime
  • Zod 3.x - Validación de esquemas
  • TypeScript 5.x - Seguridad de tipos
  • Vitest - Framework de testing

Frontend​

  • Next.js 16.x - Framework (App Router, Server Components)
  • Turbopack - Bundler por defecto (desarrollo rápido)
  • React 19.x - UI
  • Tailwind CSS 4.x - Styling

Authentication & Monitoring​

  • Clerk - Autenticación
  • Sentry - Monitoreo de errores

📊 Modelo de Datos​

El sistema utiliza 17 modelos Prisma principales:

  • Core: Profile, Hackathon, Criterion
  • Teams: Team, TeamMember, TeamInvitation
  • Submissions: Submission, SubmissionChallenge
  • Evaluation: Score, HackathonJudge, ChallengeEvaluation
  • Sponsors: Organization, Sponsorship, Challenge, ShortlistItem
  • Notifications: Notification
  • Participation: HackathonParticipation

Ver Database Schema para detalles completos.

🔐 Sistema RBAC​

El sistema implementa 5 roles con permisos bien definidos:

  1. ADMIN - Acceso completo, "Dios mode"
  2. ORGANIZER - Crear y gestionar hackathons
  3. JUDGE - Evaluar proyectos asignados
  4. SPONSOR - Crear challenges y shortlist
  5. PARTICIPANT - Participar en hackathons

Ver RBAC System para la matriz completa de permisos.

🎯 Funcionalidades Principales​

1. Landing Page Mejorada​

  • Hero Section: Presentación atractiva de la plataforma
  • Feature Cards: Destacado de funcionalidades principales
  • Featured Hackathons: Muestra hackathons disponibles públicamente
  • Call-to-Actions: Enlaces claros para registro y exploración
  • Navbar Dinámico: Enlaces públicos para usuarios no autenticados (Inicio, Hackathons, Iniciar Sesión, Registrarse)
  • Footer: Información de la plataforma, navegación y características

2. Autenticación Personalizada​

  • Componentes Custom: Sign-in y Sign-up completamente personalizados con diseño propio
  • OAuth Integration: Autenticación con Google y GitHub
  • SSO Callback: Manejo fluido de redirects OAuth
  • UI Consistente: Diseño que coincide con el resto de la aplicación

3. Gestión de Hackathons​

  • CRUD completo de hackathons
  • Sistema de estados automáticos (DRAFT → REGISTRATION → RUNNING → JUDGING → FINISHED)
  • Criterios de evaluación dinámicos (12 criterios estándar)
  • Gestión de fechas con validaciones estrictas

4. Sistema de Equipos​

  • Formación de equipos con códigos de invitación
  • Sistema de liderazgo
  • Restricciones temporales (hasta submissionDeadline)
  • Gestión de miembros

5. Sistema de Evaluación​

  • Scoring ponderado por criterio
  • 12 criterios estándar de evaluación técnica
  • Leaderboard normalizado a 100 puntos máximo
  • Evaluación de challenges por sponsors

6. Supabase Realtime​

  • Actualizaciones instantáneas (menos de 100ms)
  • Suscripciones a cambios de estado
  • Notificaciones en tiempo real

7. Sistema de Notificaciones​

  • Toasts globales para feedback
  • Notificaciones de invitaciones
  • Alertas de cambios de estado

📈 Estado Actual​

Versión: MVP Completo
Estado: ✅ Funcional y listo para producción
Tests: 94+ tests pasando
Coverage: 80%+ del core

Módulos Completados​

  • ✅ Core Layer (RBAC, DB, Auth, Errors, Validations)
  • ✅ Users Module
  • ✅ Hackathons Module
  • ✅ Teams Module
  • ✅ Submissions Module
  • ✅ Evaluation Module
  • ✅ Sponsors Module
  • ✅ Notifications Module

🚀 Próximos Pasos​

  1. Quick Start - Configuración inicial en 5 minutos
  2. Prerequisites - Requisitos y herramientas necesarias
  3. Project Overview - Estructura del proyecto

¿Listo para comenzar? → Quick Start