Saltar al contenido principal

🏗️ Arquitectura del Sistema

Visión General​

PuntoHack sigue una arquitectura modular en capas que separa claramente las responsabilidades y facilita el mantenimiento y escalabilidad.

Diagrama de Arquitectura Completo​

Capas de la Arquitectura​

1. Capa de Presentación (Frontend)​

Tecnología: React 19, Next.js 16 App Router

Componentes:

  • Server Components: Renderizado en servidor, sin JavaScript
  • Client Components: Interactivos, con estado y efectos
  • Shared Components: Reutilizables entre páginas

Características:

  • ✅ Server Components por defecto
  • ✅ Client Components solo cuando es necesario
  • ✅ Optimistic updates para mejor UX
  • ✅ Supabase Realtime para actualizaciones instantáneas

2. Capa de Aplicación (App Router)​

Tecnología: Next.js Server Actions, API Routes

Responsabilidades:

  • Server Actions: Mutaciones de datos (INSERT, UPDATE, DELETE)
  • API Routes: Endpoints REST para casos especiales (cron jobs, webhooks)
  • Route Handlers: Manejo de rutas y redirecciones

Características:

  • ✅ Type-safe con TypeScript
  • ✅ Validación automática con Zod
  • ✅ RBAC integrado
  • ✅ Manejo de errores centralizado

3. Capa Core (Infraestructura)​

Componentes:

Auth (src/core/auth.ts)​

  • Integración con Clerk
  • Helpers para obtener usuario actual
  • Verificación de autenticación

RBAC (src/core/rbac.ts)​

  • Sistema de roles y permisos
  • Funciones hasRole y requireRole
  • Validación de permisos

DB (src/core/db.ts)​

  • Singleton de Prisma Client
  • Configuración de conexión
  • Helpers de transacciones

Errors (src/core/errors.ts)​

  • Integración con Sentry
  • Captura de errores con contexto
  • Logging estructurado

Validations (src/core/validations.ts)​

  • Validaciones de negocio reutilizables
  • Validación de fechas de hackathons
  • Validación de extensiones de fechas

4. Capa de Módulos (Dominio)​

Estructura: Un módulo por entidad de negocio

Patrón:

modules/[domain]/
├── queries.ts      # Lectura
├── actions.ts      # Escritura
├── validations.ts  # Validación
└── types.ts        # Tipos

Módulos:

  • 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

5. Capa de Datos (Data Layer)​

Tecnología: Supabase PostgreSQL + Prisma ORM

Características:

  • ✅ Type-safe con Prisma
  • ✅ Migraciones automáticas
  • ✅ Row Level Security (RLS)
  • ✅ Realtime con WebSockets

Flujo de Datos​

Lectura (Query)​

Escritura (Action)​

Patrones Arquitectónicos​

1. Modular Architecture​

Principio: Separar código por dominio de negocio

Ventajas:

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

2. Layered Architecture​

Principio: Separar responsabilidades en capas

Ventajas:

  • ✅ Separación clara de concerns
  • ✅ Fácil de entender
  • ✅ Fácil de modificar

3. Server Actions Pattern​

Principio: Mutaciones directamente desde componentes

Ventajas:

  • ✅ Menos código boilerplate
  • ✅ Type-safe end-to-end
  • ✅ Mejor performance
  • ✅ Mejor UX

4. RBAC Pattern​

Principio: Control de acceso basado en roles

Ventajas:

  • ✅ Seguridad centralizada
  • ✅ Fácil de auditar
  • ✅ Escalable

Integraciones​

Clerk Authentication​

Ubicación: src/core/auth.ts

Uso:

import { getCurrentUser } from '@/core/auth';

const user = await getCurrentUser();
if (!user) throw new Error('Unauthorized');

Supabase Realtime​

Ubicación: src/lib/realtime/

Uso:

import { useHackathonsRealtime } from '@/lib/realtime/hooks/use-hackathons-realtime';

const hackathons = useHackathonsRealtime();

Sentry Monitoring​

Ubicación: src/core/errors.ts

Uso:

import { captureError } from '@/core/errors';

try {
  // código
} catch (error) {
  captureError(error, { context: 'functionName' });
}

Seguridad​

Autenticación​

  • ✅ Clerk maneja autenticación
  • ✅ Verificación en cada Server Action
  • ✅ Middleware para rutas protegidas

Autorización​

  • ✅ RBAC en cada acción crítica
  • ✅ Verificación de propiedad cuando aplica
  • ✅ Row Level Security en Supabase

Validación​

  • ✅ Zod schemas en cada input
  • ✅ Validación de tipos
  • ✅ Validación de negocio

Performance​

Optimizaciones​

  • ✅ Server Components por defecto
  • ✅ Realtime en lugar de polling
  • ✅ Revalidación selectiva de cache
  • ✅ Índices en base de datos

Caching​

  • ✅ Next.js cache automático
  • ✅ Revalidación con revalidatePath
  • ✅ Cache de queries con Prisma

Escalabilidad​

Horizontal Scaling​

  • ✅ Stateless Server Actions
  • ✅ Base de datos externa (Supabase)
  • ✅ Servicios externos (Clerk, Sentry)

Vertical Scaling​

  • ✅ Optimizaciones de queries
  • ✅ Índices en base de datos
  • ✅ Caching estratégico

Próximos Pasos​

Siguiente: Module Structure