Skip to Content
UNIMAST
DocumentaciónDesarrollarArquitectura

Arquitectura del Sistema

UNIMAST ERP está construido con una arquitectura moderna y escalable basada en Next.js 15, siguiendo las mejores prácticas de desarrollo empresarial.

🏗️ Stack Tecnológico

Frontend

  • Next.js 15 con App Router para renderizado híbrido
  • React 19 con hooks modernos y concurrent features
  • TypeScript 5.7 para type safety completo
  • Tailwind CSS con tema personalizado para diseño consistente

Backend

  • Next.js API Routes para endpoints RESTful
  • Prisma ORM con PostgreSQL para persistencia de datos
  • BullMQ con Redis para colas de trabajo asíncronas
  • AWS S3 para almacenamiento de archivos

Infraestructura

  • PostgreSQL como base de datos principal
  • Redis para cache y colas de trabajo
  • Docker para containerización
  • Nginx como reverse proxy en producción

📁 Estructura de Directorios

app/
├── app/                    # Next.js App Router
│   ├── (dashboard)/       # Layout del dashboard principal
│   ├── api/               # Endpoints de API
│   │   ├── [env]/         # APIs por entorno (dev/cert/prod)
│   │   └── search/        # API de búsqueda global
│   ├── login/             # Página de autenticación
│   └── layout.tsx         # Layout raíz de la aplicación
├── components/            # Componentes reutilizables
│   ├── ui/               # Componentes base (shadcn/ui)
│   ├── forms/            # Componentes de formularios
│   └── dashboard/        # Componentes específicos del dashboard
├── lib/                  # Lógica de negocio y utilidades
│   ├── auth/            # Autenticación y autorización
│   ├── ecf/             # Integración con facturación electrónica
│   ├── queue/           # Sistema de colas (BullMQ)
│   ├── webhooks/        # Manejo de webhooks
│   └── utils/           # Utilidades generales
├── contexts/             # Contextos de React
├── prisma/               # Esquema de base de datos y migraciones
└── public/               # Archivos estáticos

🔐 Sistema de Autenticación y Autorización

Arquitectura de Seguridad

  • JWT tokens para autenticación stateless
  • Sistema de roles con permisos granulares
  • Scopes para control de acceso a nivel de funcionalidad
  • Middleware para protección de rutas

Modelo de Permisos

// Ejemplo de scope en constants.ts
export const SCOPE = {
  CREATE_USERS: 'users:create',
  READ_USERS: 'users:read',
  UPDATE_USERS: 'users:update',
  DELETE_USERS: 'users:delete',
  // ... más scopes
};
 
// Uso en componentes
const canCreateUser = hasScope(SCOPE.CREATE_USERS);

Protección de Rutas

// middleware.ts
export function middleware(request: NextRequest) {
  const token = request.cookies.get('accessToken');
  
  if (!token && !request.nextUrl.pathname.startsWith('/login')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  
  return NextResponse.next();
}

🗄️ Modelo de Datos

Entidades Principales

  • User: Usuarios del sistema con roles y permisos
  • Role: Roles con scopes específicos
  • CashTerminal: Terminales de punto de venta
  • Invoice: Facturas y documentos fiscales
  • PaymentMethod: Métodos de pago disponibles
  • Webhook: Suscripciones a eventos del sistema

Relaciones Clave

model User {
  id        String   @id @default(cuid())
  name      String?
  email     String   @unique
  roleId    String
  role      Role     @relation(fields: [roleId], references: [id])
  
  // Relaciones con otras entidades
  createdTerminals      CashTerminal[]
  createdInvoices       Invoice[]
  createdPaymentMethods PaymentMethod[]
}
 
model Role {
  id          String   @id @default(cuid())
  name        String
  description String?
  scopes      String[]  // Array de scopes permitidos
  
  users User[]
}

🔄 Flujo de Datos

Request/Response Flow

  1. Cliente → Middleware (validación de token)
  2. Middleware → API Route (manejo de request)
  3. API Route → Service Layer (lógica de negocio)
  4. Service Layer → Prisma (persistencia)
  5. Response → Cliente con datos o errores

Ejemplo de Flujo Completo

// 1. API Route
export async function POST(request: Request) {
  const { userId, amount } = await request.json();
  
  // 2. Validación de permisos
  if (!hasScope(SCOPE.CREATE_PAYMENTS)) {
    return Response.json({ error: 'Unauthorized' }, { status: 403 });
  }
  
  // 3. Lógica de negocio
  const payment = await createPaymentService({ userId, amount });
  
  // 4. Webhook si es necesario
  await dispatchWebhookEvent(WEBHOOK_EVENT.CREATE_PAYMENT, payment);
  
  return Response.json(payment);
}

⚡ Sistema de Colas (BullMQ)

Arquitectura de Jobs

  • Redis como broker de mensajes
  • Workers para procesamiento asíncrono
  • Retry policies para manejo de errores
  • Event handling para monitoreo

Ejemplo de Job

// lib/queue.ts
export const emailQueue = new Queue('email', {
  connection: redis,
  defaultJobOptions: {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 2000
    }
  }
});
 
// Envío de job
await emailQueue.add('send-welcome', {
  to: user.email,
  template: 'welcome',
  data: { name: user.name }
});

🌐 Webhooks y Integraciones

Sistema de Webhooks

  • Suscripciones por usuario y evento
  • Headers personalizados (X-Unimast-*)
  • Retry automático en caso de fallo
  • Logging completo de eventos

Eventos Disponibles

export const WEBHOOK_EVENT = {
  CREATE_USER: 'users:create',
  UPDATE_USER: 'users:update',
  CREATE_INVOICE: 'invoices:create',
  CREATE_PAYMENT: 'payments:create',
  // ... más eventos
};

🎨 Patrones de UI/UX

Componentes Base

  • shadcn/ui para componentes fundamentales
  • Radix UI para primitivos accesibles
  • Tailwind CSS para estilos y responsive design
  • Framer Motion para animaciones

Patrón de Layouts

// Layout anidado con providers
export default function DashboardLayout({ children }) {
  return (
    <SessionProvider>
      <SidebarProvider>
        <div className="flex h-screen">
          <Sidebar />
          <main className="flex-1 overflow-auto">
            {children}
          </main>
        </div>
      </SidebarProvider>
    </SessionProvider>
  );
}

🔧 Configuración y Entorno

Variables de Entorno

# Base de datos
DATABASE_URL="postgresql://user:pass@localhost:5432/unimast"
 
# Redis
REDIS_URL="redis://localhost:6379"
 
# AWS S3
AWS_ACCESS_KEY_ID="your-key"
AWS_SECRET_ACCESS_KEY="your-secret"
AWS_REGION="us-east-1"
AWS_S3_BUCKET="unimast-files"
 
# eCF (Facturación electrónica)
ECF_ENV="DEV"  # DEV, CERT, PROD

Configuración de Next.js

// next.config.ts
const nextConfig = {
  experimental: {
    instrumentationHook: true
  },
  webpack: (config) => {
    config.plugins.push(
      new CopyWebpackPlugin({
        patterns: [
          {
            from: 'node_modules/dgii-ecf/schemas',
            to: 'schemas'
          }
        ]
      })
    );
    return config;
  }
};

📊 Monitoreo y Logging

Sistema de Logging

  • Structured logging con niveles configurables
  • Context tracking para debugging
  • Performance monitoring con métricas clave
  • Error tracking con stack traces completos

Métricas Clave

  • Tiempo de respuesta de APIs
  • Uso de memoria y CPU
  • Tasa de errores por endpoint
  • Estado de colas de trabajo

🚀 Escalabilidad y Performance

Estrategias de Optimización

  • Code splitting automático con Next.js
  • Image optimization con next/image
  • Database indexing estratégico
  • Caching en múltiples niveles

Consideraciones de Producción

  • Load balancing para alta disponibilidad
  • Database connection pooling
  • Redis clustering para escalabilidad
  • CDN para assets estáticos

¿Quieres profundizar en algún aspecto específico? Continúa con Setup del Repositorio para comenzar a trabajar con el proyecto.

Setup del RepositorioAPIs y Endpoints