MSP-CAS/docs/arquitectura

Arquitectura del Sistema

Vision General

MSP Monitor Dashboard es una aplicacion web moderna construida con una arquitectura monolitica modular, diseñada para ejecutarse en una unica VM de Proxmox mientras mantiene una clara separacion de responsabilidades.

┌─────────────────────────────────────────────────────────────────┐
│                         NGINX (Proxy)                           │
│                    SSL/TLS + Rate Limiting                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                ┌───────────────┴───────────────┐
                ▼                               ▼
┌───────────────────────────┐   ┌───────────────────────────────┐
│     Next.js Dashboard     │   │     Background Workers        │
│  (Frontend + API Routes)  │   │       (BullMQ Jobs)          │
└───────────────────────────┘   └───────────────────────────────┘
                │                               │
                └───────────────┬───────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│  PostgreSQL   │       │     Redis     │       │   External    │
│   (Primary)   │       │ (Cache/Queue) │       │    APIs       │
└───────────────┘       └───────────────┘       └───────────────┘
                                                        │
                        ┌───────────────────────────────┼───────────────────────────────┐
                        ▼                               ▼                               ▼
                ┌───────────────┐               ┌───────────────┐               ┌───────────────┐
                │  MeshCentral  │               │   LibreNMS    │               │  Headwind MDM │
                │  (PC/Laptop)  │               │   (Network)   │               │   (Mobile)    │
                └───────────────┘               └───────────────┘               └───────────────┘

Componentes Principales

1. Frontend (Next.js + React)

Ubicacion: src/app/, src/components/

El frontend utiliza Next.js 14 con App Router, proporcionando:

• Server Components: Para renderizado del lado del servidor
• Client Components: Para interactividad en el navegador
• Tailwind CSS: Sistema de diseño con tema oscuro cyan/navy
• React Query: Cache y sincronizacion de estado del servidor

Estructura de paginas:

src/app/
├── (dashboard)/           # Grupo de rutas autenticadas
│   ├── layout.tsx         # Layout con sidebar y header
│   ├── page.tsx           # Dashboard principal
│   ├── equipos/           # Gestion de PCs/laptops/servidores
│   ├── celulares/         # Gestion de dispositivos moviles
│   ├── red/               # Gestion de dispositivos de red
│   ├── alertas/           # Centro de alertas
│   ├── reportes/          # Generacion de reportes
│   └── configuracion/     # Configuracion del sistema
└── api/                   # API Routes
    └── trpc/              # Endpoint tRPC

2. Backend (tRPC + Prisma)

Ubicacion: src/server/trpc/

El backend utiliza tRPC para APIs type-safe con validacion Zod:

// Ejemplo de router
export const equiposRouter = router({
  list: protectedProcedure
    .input(z.object({ clienteId: z.string().optional() }))
    .query(async ({ ctx, input }) => {
      return ctx.prisma.dispositivo.findMany({
        where: input.clienteId ? { clienteId: input.clienteId } : {},
      })
    }),
})

Routers disponibles:

• auth - Autenticacion y sesiones
• clientes - Gestion de clientes/tenants
• equipos - PCs, laptops, servidores
• celulares - Dispositivos moviles
• red - Dispositivos de red
• alertas - Sistema de alertas
• reportes - Generacion de reportes
• usuarios - Gestion de usuarios
• configuracion - Configuracion del sistema

3. Servicios de Integracion

Ubicacion: src/server/services/

Clientes para comunicacion con sistemas externos:

services/
├── meshcentral/
│   └── client.ts    # Cliente API REST + WebSocket
├── librenms/
│   └── client.ts    # Cliente API REST
└── headwind/
    └── client.ts    # Cliente API REST

Cada cliente proporciona:

• Autenticacion automatica
• Manejo de errores
• Tipado TypeScript
• Cache de conexiones

4. Sistema de Jobs (BullMQ)

Ubicacion: src/server/jobs/

Procesamiento asincronico con BullMQ y Redis:

jobs/
├── queue.ts              # Configuracion de colas
├── worker.ts             # Worker principal
├── sync-meshcentral.job.ts
├── sync-librenms.job.ts
├── sync-headwind.job.ts
├── alert-processor.job.ts
├── notification.job.ts
└── maintenance.job.ts

Colas:

Cola	Proposito	Frecuencia
sync	Sincronizacion con plataformas	Cada 5 min
alerts	Procesamiento de alertas	Bajo demanda
notifications	Envio de notificaciones	Bajo demanda
maintenance	Tareas de mantenimiento	Diario/Horario

5. Base de Datos (PostgreSQL + Prisma)

Ubicacion: prisma/schema.prisma

Modelo de datos multi-tenant:

┌─────────────┐     ┌─────────────────┐
│   Cliente   │────<│  Dispositivo    │
└─────────────┘     └─────────────────┘
       │                    │
       │            ┌───────┴───────┐
       │            ▼               ▼
       │    ┌───────────────┐ ┌───────────────┐
       │    │   Metrica     │ │   Software    │
       │    └───────────────┘ └───────────────┘
       │
       ├───<│ Usuario │
       │
       └───<│ Alerta  │

Tablas principales:

• clientes - Tenants del sistema
• dispositivos - Todos los tipos de dispositivos
• alertas - Alertas y eventos
• usuarios - Usuarios y permisos
• configuracion - Settings del sistema

Flujo de Datos

1. Sincronizacion de Dispositivos

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Plataforma  │────>│   Worker    │────>│  PostgreSQL │
│   Externa   │     │  (BullMQ)   │     │             │
└─────────────┘     └─────────────┘     └─────────────┘
       ▲                   │
       │                   ▼
       │            ┌─────────────┐
       │            │    Redis    │
       │            │   (Cache)   │
       │            └─────────────┘
       │                   │
       │                   ▼
       │            ┌─────────────┐
       └────────────│   Alerta    │
                    │  Processor  │
                    └─────────────┘

2. Consulta de Dispositivos

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Browser   │────>│   Next.js   │────>│    tRPC     │
│             │<────│   (SSR)     │<────│   Router    │
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
                                        ┌─────────────┐
                                        │   Prisma    │
                                        │   Client    │
                                        └─────────────┘
                                               │
                           ┌───────────────────┴───────────────────┐
                           ▼                                       ▼
                    ┌─────────────┐                         ┌─────────────┐
                    │    Redis    │                         │  PostgreSQL │
                    │   (Cache)   │                         │             │
                    └─────────────┘                         └─────────────┘

3. Sesion Remota

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Usuario   │────>│  Dashboard  │────>│ MeshCentral │
│             │     │             │     │   (iframe)  │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       │                   ▼                   │
       │            ┌─────────────┐            │
       │            │  Audit Log  │<───────────┘
       │            └─────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────┐
│              WebSocket (MeshCentral)                │
│         Desktop / Terminal / Files                  │
└─────────────────────────────────────────────────────┘

Seguridad

Autenticacion

• MeshCentral SSO: Integracion con autenticacion de MeshCentral
• JWT Sessions: Tokens firmados con expiracion de 24h
• Password Hashing: bcrypt con salt factor 12

Autorizacion

// Roles jerarquicos
enum RolUsuario {
  SUPER_ADMIN,  // Acceso total
  ADMIN,        // Admin de cliente
  TECNICO,      // Operaciones
  CLIENTE,      // Solo lectura
  VIEWER        // Vista limitada
}

Aislamiento de Datos

• Cada consulta filtra por clienteId
• Middleware verifica permisos en cada request
• Audit log de todas las acciones sensibles

Escalabilidad

Horizontal (futuro)

                    ┌─────────────┐
                    │   HAProxy   │
                    │    (LB)     │
                    └─────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
    ┌───────────┐   ┌───────────┐   ┌───────────┐
    │  Node 1   │   │  Node 2   │   │  Node 3   │
    │ (Next.js) │   │ (Next.js) │   │ (Worker)  │
    └───────────┘   └───────────┘   └───────────┘
           │               │               │
           └───────────────┼───────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
    ┌───────────┐   ┌───────────┐   ┌───────────┐
    │ PostgreSQL│   │   Redis   │   │   Redis   │
    │  Primary  │   │  Primary  │   │  Replica  │
    └───────────┘   └───────────┘   └───────────┘

Vertical (actual)

• CPU: Escalable segun carga
• RAM: Minimo 4GB recomendado
• Disco: SSD para BD, puede usar storage separado para backups

Monitoreo del Sistema

Health Checks

# Endpoints de health
GET /health         # Estado general
GET /api/health     # Estado de API

Metricas

• CPU/RAM/Disco del servidor
• Latencia de BD
• Tamano de colas
• Errores de sincronizacion

Logs

# Ver logs de contenedores
docker-compose logs -f dashboard
docker-compose logs -f worker