Saltar al contenido principal

🏗️ Arquitectura General

Visión General​

PuntoHack sigue una arquitectura modular en capas que separa claramente las responsabilidades:

  1. Capa de Presentación (Next.js App Router)
  2. Capa de Lógica de Negocio (Core + Modules)
  3. Capa de Datos (Prisma + Supabase)

Diagrama de Arquitectura General​

Capas del Sistema​

1. Capa de Presentación​

Tecnología: Next.js 16 App Router

  • Server Components: Fetching de datos, renderizado en servidor
  • Client Components: Interactividad, hooks de React
  • Server Actions: Mutaciones de datos, validaciones
  • Routing: File-based routing con App Router

Características:

  • ✅ Server Components por defecto
  • ✅ Client Components solo cuando es necesario
  • ✅ Server Actions para todas las mutaciones
  • ✅ Formularios HTML nativos

2. Capa de Lógica de Negocio​

Core Layer​

Infraestructura compartida por todos los módulos:

  • rbac.ts: Sistema de roles y permisos
  • auth.ts: Helpers de autenticación (Clerk)
  • db.ts: Singleton de Prisma Client
  • errors.ts: Manejo de errores + Sentry
  • validations.ts: Helpers de validación de fechas

Modules Layer​

Módulos de dominio siguiendo el patrón estándar:

modules/[domain]/
├── queries.ts      # Operaciones de lectura
├── actions.ts      # Server Actions (escritura)
├── types.ts        # TypeScript interfaces
└── validations.ts  # Zod schemas

Módulos implementados:

  • users/ - Gestión de usuarios y perfiles
  • hackathons/ - CRUD de hackathons, criterios, estados
  • teams/ - Formación de equipos, invitaciones
  • submissions/ - Envío y edición de proyectos
  • evaluation/ - Sistema de scoring, leaderboard
  • sponsors/ - Organizaciones, sponsorships, challenges
  • notifications/ - Sistema de notificaciones

3. Capa de Datos​

Tecnología: Prisma ORM + Supabase PostgreSQL

  • Prisma: ORM type-safe, migraciones, queries
  • Supabase PostgreSQL: Base de datos relacional
  • Supabase Realtime: Actualizaciones en tiempo real vía WebSockets

Características:

  • ✅ 17 modelos Prisma bien relacionados
  • ✅ Constraints y validaciones a nivel DB
  • ✅ Índices optimizados
  • ✅ Realtime habilitado en 6 tablas

Flujo de Datos​

Principios Arquitectónicos​

1. Separación de Responsabilidades​

  • Presentación: Solo UI y routing
  • Lógica: Validaciones, reglas de negocio, RBAC
  • Datos: Persistencia, queries, transacciones

2. Modularidad​

Cada módulo es independiente y sigue el mismo patrón:

  • Queries para lectura
  • Actions para escritura
  • Validations con Zod
  • Types para TypeScript

3. Type Safety​

  • TypeScript en todo el código
  • Zod para validación runtime
  • Prisma para type-safe queries

4. Seguridad​

  • RBAC en cada Server Action
  • Validaciones exhaustivas (nunca confiar en cliente)
  • RLS en Supabase para Realtime

5. Testing​

  • Tests unitarios para validaciones
  • Tests de integración para queries/actions
  • Coverage 80%+ del core

Estructura de Directorios​

src/
├── app/                    # Next.js App Router
│   ├── (routes)/           # Rutas públicas/privadas
│   └── api/               # API routes (cron, etc.)
├── core/                   # ⚡ CORE - Infraestructura
│   ├── rbac.ts
│   ├── auth.ts
│   ├── db.ts
│   ├── errors.ts
│   └── validations.ts
├── modules/                # ⚡ LÓGICA DE NEGOCIO
│   ├── users/
│   ├── hackathons/
│   ├── teams/
│   ├── submissions/
│   ├── evaluation/
│   ├── sponsors/
│   └── notifications/
├── components/             # UI Components
└── lib/                    # Utilities
    ├── realtime/
    └── supabase/

Decisiones Arquitectónicas Clave​

1. Next.js App Router​

Decisión: Usar App Router en lugar de Pages Router

Razón:

  • Server Components por defecto
  • Server Actions nativos
  • Mejor performance
  • Mejor DX

2. Prisma ORM​

Decisión: Prisma en lugar de TypeORM o Sequelize

Razón:

  • Type-safety completo
  • Migraciones automáticas
  • Excelente DX
  • Buen soporte para PostgreSQL

3. Supabase Realtime​

Decisión: WebSockets en lugar de polling

Razón:

  • Actualizaciones instantáneas (menos de 100ms)
  • Menor carga en servidor
  • Mejor UX
  • Escalable

4. Patrón Modular​

Decisión: Separar queries, actions, validations

Razón:

  • Código organizado y mantenible
  • Fácil de testear
  • Reutilizable
  • Escalable

Próximos Pasos​

Siguiente: System Architecture