Arquitectura de alto nivel

Este manual es de usuario, pero entender la arquitectura ayuda a ubicar cada funcionalidad en la capa correcta. La documentación técnica canónica vive en ARCHITECTURE.md del repositorio.

Dos codebases independientes

HUMAE NEW/
├── humae_backend/          Laravel 12 · PHP 8.3 · MySQL 8
│   ├── API REST v1         /api/v1/*
│   ├── Auth: Sanctum       tokens + SPA cookies
│   ├── Auth: Spatie        roles + permissions
│   ├── Policies            autorización por recurso
│   ├── Services            lógica de negocio
│   └── Jobs + Queues       ExpireMembershipsJob, mailers
│
├── humae_frontend/         Next.js 16 · React 19 · TypeScript
│   ├── App Router          server + client components
│   ├── TanStack Query      data fetching server state
│   ├── Zustand             session + UI state
│   ├── shadcn/ui           design system
│   └── Tailwind v4         estilos + tokens HUMAE
│
├── humae_docs/             VitePress · Markdown · Vue 3
│   └── Este manual
│
└── ARCHITECTURE.md         Documento técnico canónico

Contrato de API

Todas las respuestas del backend siguen el mismo envelope:

{
  "success": true,
  "message": "OK",
  "data": { /* payload */ },
  "meta": { "page": 1, "total": 42 }
}

En caso de error:

{
  "success": false,
  "message": "Validation failed",
  "errors": { "email": ["El correo ya está registrado"] }
}

Códigos HTTP semánticos: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Validation, 429 Too Many Requests, 500 Internal Error.

Flujo de autenticación

HUMAE soporta dos modos de autenticación Sanctum:

Modo 1 · SPA (cookie-based) — frontend web

Cliente (localhost:3000)          Backend (localhost:8000)
         │                                  │
         │  POST /sanctum/csrf-cookie       │
         │ ──────────────────────────────▶  │
         │                                  │
         │ ◀──── Cookie: XSRF-TOKEN ─────── │
         │                                  │
         │  POST /api/v1/auth/login         │
         │  { email, password }             │
         │  X-XSRF-TOKEN: ...               │
         │ ──────────────────────────────▶  │
         │                                  │
         │ ◀──── Cookie: humae_session ──── │
         │                                  │
         │  Todas las requests siguientes   │
         │  llevan la cookie automáticamente│

Modo 2 · Token — mobile / integraciones

POST /api/v1/auth/login           → { token: "1|abc...", user: {...} }
Authorization: Bearer 1|abc...    en cada request

Capas del backend

┌────────────────────────────────────────────────┐
│  Routes (routes/api.php)                       │
│  • Agrupadas por prefijo + middleware de rol   │
└──────────────────┬─────────────────────────────┘
                   ▼
┌────────────────────────────────────────────────┐
│  Middleware                                    │
│  • auth:sanctum                                │
│  • role:candidate / role:recruiter / ...       │
│  • rate limits por endpoint                    │
└──────────────────┬─────────────────────────────┘
                   ▼
┌────────────────────────────────────────────────┐
│  FormRequest (validación)                      │
│  • reglas Zod-like, mensajes en español        │
│  • autoriza con Policies antes de correr       │
└──────────────────┬─────────────────────────────┘
                   ▼
┌────────────────────────────────────────────────┐
│  Controller                                    │
│  • Thin: valida, delega, responde              │
│  • Usa trait ApiResponse para envelope         │
└──────────────────┬─────────────────────────────┘
                   ▼
┌────────────────────────────────────────────────┐
│  Service (lógica de negocio)                   │
│  • MembershipService, PipelineService, ...     │
│  • Transacciones DB                            │
│  • State Machines                              │
└──────────────────┬─────────────────────────────┘
                   ▼
┌────────────────────────────────────────────────┐
│  Models (Eloquent)                             │
│  • Relaciones                                  │
│  • Casts a enums / carbon / json               │
│  • Scopes y atributos calculados               │
└──────────────────┬─────────────────────────────┘
                   ▼
┌────────────────────────────────────────────────┐
│  API Resource (transformación de salida)       │
│  • CandidateProfileResource, VacancyResource   │
└────────────────────────────────────────────────┘

Capas del frontend

app/                          Rutas (Next App Router)
  (auth)/                     Layout auth: login, register, forgot
  dashboard/                  Layout autenticado
  recruiter/                  Protegido por rol
  admin/                      Protegido por rol
  api/                        Opcional, proxy a backend

components/
  ui/                         shadcn/ui primitives
  shared/                     SiteHeader, Logo, NotificationBell
  motion/                     Variantes de animación

features/<módulo>/            Feature folders: hooks + components + api + types
  auth/
  profile/
  membership/
  directory/
  pipeline/
  interviews/
  psychometric/
  notifications/
  reports/

hooks/                        Custom hooks cross-feature
lib/
  api.ts                      Axios client + ApiError
  query-client.ts             TanStack factory
stores/
  auth-store.ts               Zustand auth session
schemas/                      Zod forms
types/                        TypeScript contracts

Persistencia

• MySQL 8 (producción + dev). Estructura en 55+ tablas de dominio.
• SQLite in-memory (tests). Automático vía phpunit.xml.
• Redis (opcional): cache de queries pesadas, sesiones y queue.

Los índices están optimizados para las consultas del directorio, pipeline y reportes. Ver PERFORMANCE.md del repo.

Observabilidad

• Logs: channel diario Laravel (storage/logs/laravel-YYYY-MM-DD.log).
• Errores de API: mapeados uniformemente por ApiExceptionHandler (nunca exponen traza en producción).
• Health endpoint: GET /api/v1/health devuelve estado DB + cache.
• Reportes ejecutivos: dashboard /admin/reportes con métricas en tiempo real.

Deploy

• Backend: servidor PHP 8.3 + MySQL 8 + Redis. Supervisor para queues + cron para scheduler (ver Cronjobs y tareas programadas).
• Frontend: Vercel / Netlify / cualquier host estático compatible con Next.js (SSR + SSG).
• Docs: cualquier host estático (Cloudflare Pages, Vercel, Netlify, GitHub Pages).

Detalles completos en el README.md del monorepo.

Siguiente

Entra a la sección que corresponda a tu rol:

• Candidato: Registro y verificación →
• Reclutador: Directorio →
• Empresa: Dashboard →
• Admin: Catálogos →