Saltar al contenido principal

📋 Project Overview

Estructura del Proyecto​

puntohack/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (routes)/           # Rutas organizadas por rol
│   │   │   ├── admin/          # Panel de administración
│   │   │   ├── dashboard/      # Dashboard principal
│   │   │   ├── hackathons/     # Rutas públicas de hackathons
│   │   │   ├── judge/          # Panel de juez
│   │   │   ├── organizer/      # Panel de organizador
│   │   │   ├── participant/    # Panel de participante
│   │   │   └── sponsor/        # Panel de sponsor
│   │   ├── api/                # API routes
│   │   │   ├── cron/           # Cron jobs
│   │   │   ├── hackathons/     # API de hackathons
│   │   │   └── ...
│   │   └── ...
│   ├── core/                   # ⚡ Infraestructura Core
│   │   ├── rbac.ts             # Sistema de roles y permisos
│   │   ├── auth.ts             # Helpers de autenticación
│   │   ├── db.ts               # Singleton de Prisma Client
│   │   ├── errors.ts           # Manejo de errores + Sentry
│   │   └── validations.ts      # Helpers de validación
│   ├── modules/                # ⚡ Lógica de Negocio
│   │   ├── users/              # Gestión de usuarios
│   │   ├── hackathons/         # CRUD de hackathons
│   │   ├── teams/              # Formación de equipos
│   │   ├── submissions/        # Envío de proyectos
│   │   ├── evaluation/         # Sistema de evaluación
│   │   ├── sponsors/           # Gestión de sponsors
│   │   └── notifications/      # Sistema de notificaciones
│   ├── components/             # UI Components
│   │   ├── navbar.tsx
│   │   ├── toast/              # Sistema de toasts
│   │   └── ...
│   └── lib/                    # Utilities
│       ├── realtime/           # Hooks de Supabase Realtime
│       └── supabase/           # Cliente de Supabase
├── prisma/
│   ├── schema.prisma           # Schema de base de datos
│   ├── seed.ts                # Seed principal
│   └── seed-users.ts          # Seed de usuarios
├── scripts/                    # Scripts de utilidad
│   ├── create-clerk-users.ts
│   ├── seed-hackathons.ts
│   └── ...
├── tests/                      # Tests
│   ├── modules/                # Tests por módulo
│   └── setup.ts               # Configuración de tests
└── docs/                       # Documentación (legacy)

Tecnologías Principales​

Frontend​

  • Next.js 16: App Router, Server Components, Server Actions
  • React 19: UI library
  • Tailwind CSS 4: Styling utility-first
  • TypeScript 5: Type safety

Backend​

  • Next.js Server Actions: Mutaciones sin API routes
  • Prisma ORM: Type-safe database client
  • Zod: Runtime validation

Base de Datos​

  • Supabase PostgreSQL: Base de datos relacional
  • Supabase Realtime: Actualizaciones en tiempo real

Autenticación y Monitoreo​

  • Clerk: Authentication as a Service
  • Sentry: Error tracking y monitoring

Testing​

  • Vitest: Test framework
  • Coverage: 80%+ del core

Filosofía del Proyecto​

MVP Estricto​

  • ✅ Solo lo documentado
  • ❌ Sin features extra
  • ❌ Sin optimizaciones prematuras
  • ❌ Sin sobreingeniería

Prioridades​

  1. Core funcional: RBAC, validaciones, lógica de negocio
  2. Base de datos: Bien diseñada, relaciones correctas
  3. Testing: 80%+ coverage del core
  4. Frontend: Funcional, sin librerías UI innecesarias

Principios​

  • Type Safety: TypeScript estricto + Zod
  • Security: RBAC en cada acción, validaciones exhaustivas
  • Modularity: Código organizado por dominio
  • Testing: Tests desde el inicio
  • Documentation: Código autodocumentado

Convenciones​

Naming​

  • Archivos: kebab-case.ts
  • Componentes: PascalCase.tsx
  • Funciones: camelCase
  • Constantes: SCREAMING_SNAKE_CASE
  • Tipos: PascalCase

Estructura de Módulos​

Cada módulo sigue el mismo patrón:

modules/[domain]/
├── queries.ts      # Lectura
├── actions.ts      # Escritura (Server Actions)
├── types.ts        # TypeScript
└── validations.ts  # Zod schemas

Scripts Disponibles​

Desarrollo​

pnpm dev              # Servidor de desarrollo
pnpm dev:turbo        # Con Turbopack (más rápido)
pnpm type-check       # Verificar tipos
pnpm lint             # Linting

Base de Datos​

pnpm db:generate      # Generar Prisma Client
pnpm db:push          # Aplicar schema
pnpm db:studio        # Abrir Prisma Studio
pnpm db:seed          # Seed completo

Testing​

pnpm test             # Ejecutar tests
pnpm test:coverage    # Con coverage

Próximos Pasos​

Siguiente: Architecture Overview