# 📐 HLD - High Level Design

## Objetivo do Sistema

Centralizar integrações ITSM heterogêneas através de um middleware orientado a eventos que elimina polling direto, implementa governança completa e garante rastreabilidade ponta-a-ponta.

## Componentes Principais

### 1. Frontend
- **Tecnologia**: HTML5 + Bootstrap 5 + jQuery + Chart.js
- **Features**: Dashboard, CRUD modules, Dark Mode, Responsive
- **Segurança**: HTTPS, CSRF tokens, XSS prevention
- **Performance**: Minified assets, lazy loading, caching

### 2. API Gateway
- **Framework**: Laravel 12
- **Runtime**: PHP 8.3-FPM
- **Segurança**: JWT, CORS, Rate Limiting
- **Features**: Validation, Serialization, Error Handling

### 3. Event Processing
- **Queue**: RabbitMQ 3.13
- **Workers**: 2+ Supervisor processes
- **Features**: Retry logic, DLQ, Idempotency keys
- **Monitoring**: Horizon dashboard

### 4. Data Storage
- **Relational**: MySQL 8 (Events, Integrações, Users, Logs)
- **Cache**: Redis 7 (Sessions, Cache, Queue)
- **Search**: Logs table (future: Elasticsearch)

### 5. Integration Layer
- **REST API**: HTTP/S endpoints
- **SOAP**: XML over HTTP
- **Webhooks**: Push notifications
- **Transformations**: Payload mapping engine

### 6. Rules Engine
- **Conditions**: Flexible evaluation
- **Actions**: Route, classify, escalate, notify
- **Execution**: Transactional with rollback
- **Audit**: Completo com traces

## Fluxos Principais

### Fluxo 1: Recebimento de Evento

```
1. External System HTTP POST /api/events
   └─ Payload: {ticket_id, status, ...}

2. API Gateway Valida
   └─ Schema validation
   └─ Authentication check
   └─ Rate limit enforcement

3. Event Created
   └─ ID único gerado
   └─ Correlation ID criado
   └─ Timestamp registrado

4. Published to RabbitMQ
   └─ Mensagem no exchange
   └─ Binding automático

5. Response ao Cliente
   └─ 202 Accepted
   └─ Correlation ID retornado

6. Response Logging
   └─ Evento em DB
   └─ Status: 'received'
```

### Fluxo 2: Processamento de Evento

```
1. Worker Consome Mensagem
   └─ De RabbitMQ
   └─ Acknowledgement automático

2. Rules Engine Evalua
   └─ Carrega todas as rules
   └─ Avalia condições
   └─ Registra resultado

3. Determina Ações
   └─ Route: Para qual integração?
   └─ Priority: Qual prioridade?
   └─ Transform: Como transformar?

4. Executa Integrações
   └─ Chama endpoints
   └─ Valida respostas
   └─ Registra resultados

5. Publica Webhooks
   └─ Para cada subscriber
   └─ Com retry automático

6. Marca como Processado
   └─ Status: 'processed'
   └─ Processing time salvo
```

### Fluxo 3: Gerenciamento de Falhas

```
1. Erro Ocorre
   └─ Exception na integração
   └─ Timeout na API
   └─ Validação falha

2. Primeiro Retry
   └─ Aguarda 60 segundos
   └─ Reconecta
   └─ Tenta novamente

3. Segundo Retry
   └─ Aguarda 120 segundos
   └─ Última tentativa

4. Falha Final
   └─ Evento para DLQ
   └─ Alert disparado
   └─ Admin notificado

5. Resolução Manual
   └─ Admin analisa
   └─ Ajusta configuração
   └─ Reprocessa
```

## Modelo de Dados Simplificado

```
Users (N:M) Roles (N:M) Permissions
Integrations
  ├─ IntegrationCredentials
  ├─ IntegrationEndpoints
  └─ PayloadMappings
Events
  ├─ EventTraces (rastreamento)
  ├─ RuleExecutions
  ├─ IntegrationLogs
  └─ WebhookDeliveries
Rules
  ├─ RuleConditions
  └─ RuleActions
SLAPolicies
Webhooks
  └─ WebhookDeliveries
ApiKeys
QueueJobs
  └─ DeadLetterQueue
AuditLogs
SecurityLogs
```

## Fluxo de Autorização

```
1. Usuário faz requisição
   └─ Headers: Authorization: Bearer <token>

2. JWTAuthenticate Middleware
   └─ Valida token
   └─ Extrai user_id
   └─ Injeta user em request

3. Route Protection
   └─ middleware('auth:sanctum')
   └─ middleware('role:admin')
   └─ middleware('permission:rules.edit')

4. Policy Check
   └─ $this->authorize('update', $rule)
   └─ Valida ownership
   └─ Verifica permissões

5. Ação Executada
   └─ Com auditoria
   └─ Logged to AuditLog
```

## Operações Críticas

### 1. Criar Integração
```
POST /api/integrations
├─ Validações
├─ Criptografa credenciais
├─ Cria endpoints
├─ Cria payload mappings
├─ Registra em audit
└─ Retorna integração completa
```

### 2. Processar Evento
```
Event Received
├─ Validate schema
├─ Create Event record
├─ Publish to queue
├─ Return 202
└─ Queue Worker
    ├─ Load rules
    ├─ Evaluate conditions
    ├─ Execute actions
    ├─ Call integrations
    ├─ Publish webhooks
    └─ Mark as processed
```

### 3. Aplicar Regra
```
Apply Rule
├─ Load conditions
├─ Evaluate data against conditions
├─ If matches:
│   ├─ Execute actions
│   ├─ Call endpoints
│   ├─ Transform payload
│   └─ Log result
└─ Record execution
```

## Configurações Principais

### RabbitMQ
```
- Exchanges: events, webhooks, notifications
- Queues: default, failed, dlq
- Bindings: event_type -> queue
- Prefetch: 1 (fair dispatch)
```

### Redis
```
- DB 0: Cache
- DB 1: Session
- DB 2: Queue
- TTL: Configurável por tipo
```

### MySQL
```
- Charset: utf8mb4
- Collation: utf8mb4_unicode_ci
- InnoDB engine
- Max connections: 500
```

## Considerações de Performance

| Operação | Latência Target | Como Atingir |
|----------|-----------------|-------------|
| Login | <500ms | Cache de permissões |
| Dashboard | <2s | Índices + Redis cache |
| Event Processing | <5s | Async + Queue |
| API Call | <30s | Timeout + Retry |
| Webhooks | <10s | Async delivery |

## Segurança em Camadas

```
┌─────────────────────────────────────────┐
│ Camada 1: Network                       │
│ HTTPS, Firewall, DDoS Protection        │
├─────────────────────────────────────────┤
│ Camada 2: Application                   │
│ JWT, CORS, Rate Limit, Input Validation │
├─────────────────────────────────────────┤
│ Camada 3: Data                          │
│ Encryption, Hashing, Secrets Management │
├─────────────────────────────────────────┤
│ Camada 4: Audit                         │
│ Logging, Tracing, Alerts, Dashboards    │
└─────────────────────────────────────────┘
```

## Escalabilidade

### Horizontal
- **Frontend**: Load balancer + múltiplas instâncias
- **API**: Load balancer + PHP-FPM workers
- **Workers**: Múltiplos containers + Supervisor
- **DB**: Read replicas (future)

### Vertical
- **Memory**: Aumentar php memory_limit
- **CPU**: Aumentar worker processes
- **Disk**: Aumentar storage, archiving

## Backup & Recovery

### Backup
- **Daily**: Full DB backup to S3
- **Hourly**: Incremental backups
- **Logs**: 7-day retention
- **Configs**: Versionados no Git

### Recovery
- **RTO**: <15 min
- **RPO**: <1 min
- **Teste mensal**: Restore practice

## Roadmap Técnico

- **Q1**: MVP core (Auth, Events, Basic Rules)
- **Q2**: Advanced Rules, Webhooks, APIs
- **Q3**: Dashboard, Monitoring, Scale testing
- **Q4**: HA, DR, Multi-tenancy