# 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:

```typescript
// 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

```typescript
// 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

```bash
# 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

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