# 🏗️ Arquitetura - Integration Hub

## Visão Geral

Integration Hub é um middleware enterprise que centraliza integrações entre múltiplos ITSMs, sistemas legados e parceiros. Implementa arquitetura orientada a eventos, desacoplamento completo entre sistemas e processamento assíncrono robusto.

## Princípios Arquiteturais

- **Orientado a Eventos**: Toda comunicação baseada em eventos, não polling
- **Desacoplamento Total**: Sistemas não se comunicam diretamente
- **Escalabilidade Horizontal**: Múltiplas instâncias de workers
- **Rastreabilidade Completa**: Correlation ID em todo evento
- **Segurança em Camadas**: RBAC, criptografia, auditoria
- **Resilience Patterns**: Retry, circuit breaker, timeout

## Stack Tecnológico

```
┌─────────────────────────────────────────────────┐
│             Frontend Enterprise                  │
│  Bootstrap 5 + jQuery + Chart.js + Dark Mode    │
└─────────────┬───────────────────────────────────┘
              │ HTTPS
┌─────────────┴───────────────────────────────────┐
│          API Gateway / Web Server                │
│    Laravel 12 + PHP 8.3 + Sanctum + JWT         │
└─────────────┬───────────────────────────────────┘
              │
    ┌─────────┼──────────┬──────────┐
    ▼         ▼          ▼          ▼
┌────────┐┌────────┐┌────────┐┌────────┐
│ MySQL  ││ Redis  ││Rabbit  ││ Logs   │
│  8.0   ││  7     ││  MQ    ││Elastic │
└────────┘└────────┘└────────┘└────────┘
```

## Módulos Principais

### 1. Authentication & Authorization
- **JWT Authentication**: Tokens com expiração
- **RBAC**: 5 roles pré-configurados (Super Admin, Admin, Integrator, Analyst, Viewer)
- **MFA Optional**: TOTP support
- **Session Security**: HttpOnly, Secure, SameSite cookies
- **Audit Trail**: Todos os logins/logouts rastreados

### 2. Event Processing
```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  ITSM Origem│────▶│ Event Receiver│────▶│ RabbitMQ    │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                  │
                                    ┌─────────────┼─────────────┐
                                    ▼             ▼             ▼
                            ┌──────────────┐ ┌──────────┐ ┌──────────┐
                            │ Rules Engine │ │ Webhooks │ │ Audit    │
                            └──────────────┘ └──────────┘ └──────────┘
```

### 3. Rules Engine
- **Conditional Routing**: Se X então Y
- **Classification**: Categorizar eventos
- **Escalation**: Escalar por SLA
- **Automation**: Executar ações automáticas
- **Priority-based**: Execução por prioridade

### 4. Queue Processing
- **RabbitMQ**: Message broker principal
- **Dead Letter Queue**: Mensagens que falharam
- **Retry Logic**: 3 tentativas com backoff
- **Idempotency**: Evitar duplicatas
- **Worker Pool**: Múltiplos processadores

### 5. Integration Management
- **REST API**: HTTP endpoints
- **SOAP/XML**: Web services legados
- **Webhooks**: Push events
- **Scheduler**: Tarefas agendadas
- **Payload Mapping**: Transformação de dados

### 6. Observability
- **Logs Centralizados**: Stack de logs
- **Metrics**: Prometheus-ready
- **Tracing**: Correlation ID end-to-end
- **Alerting**: Thresholds configuráveis
- **Dashboard**: Real-time KPIs

## Fluxo de Processamento Completo

```
1. ITSM Interno cria Ticket
   └─▶ POST /api/webhooks/itsm-internal/events
   
2. Middleware Recebe & Valida
   └─▶ Cria Event com correlation_id único
   
3. Rules Engine Avalia
   └─▶ Aplica regras condicionais
   └─▶ Define roteamento
   └─▶ Aplica SLA
   
4. Event vai para Fila
   └─▶ Publica em RabbitMQ
   
5. Workers Processam
   └─▶ Executa integrações
   └─▶ Transforma payload
   └─▶ Entrega para partners
   
6. Webhooks & Notificações
   └─▶ Notifica consumidores
   └─▶ Registra evento
   
7. Audit & Logs
   └─▶ Registra cada passo
   └─▶ Correlação completa
   
8. Dashboard Atualiza
   └─▶ Reflete estado em tempo real
```

## Camadas Arquiteturais

### Camada de Apresentação
```
├── Frontend (resources/views)
│   ├── Dashboard
│   ├── Integrações
│   ├── Regras
│   ├── Logs
│   └── Usuários
└── API (routes/api.php)
    ├── /api/v1/integrations
    ├── /api/v1/events
    ├── /api/v1/rules
    └── /api/v1/auth
```

### Camada de Aplicação
```
├── Controllers
│   ├── AuthController
│   ├── IntegrationController
│   ├── RuleController
│   └── WebhookController
├── Requests (Validation)
├── Resources (API Responses)
└── Middleware (Auth, CORS, etc)
```

### Camada de Domínio
```
├── Services
│   ├── IntegrationService
│   ├── EventProcessingService
│   ├── RuleEngine
│   └── WebhookService
├── Repositories
│   ├── IntegrationRepository
│   ├── EventRepository
│   └── RuleRepository
└── Actions (use cases)
```

### Camada de Infraestrutura
```
├── Database
│   ├── Migrations
│   ├── Seeders
│   └── Indexes
├── Queue Jobs
│   ├── ProcessEventJob
│   ├── SendWebhookJob
│   └── SyncIntegrationJob
├── Events (Laravel Events)
│   ├── EventProcessed
│   ├── IntegrationFailed
│   └── RuleExecuted
└── Listeners
    ├── LogEventListener
    ├── SendNotificationListener
    └── UpdateMetricsListener
```

## Padrões de Design Implementados

### 1. Repository Pattern
```php
interface IntegrationRepository {
    find($id);
    all();
    create(array $data);
    update($id, array $data);
}
```

### 2. Service Layer
```php
class IntegrationService {
    public function syncEvents(Integration $integration);
    public function executeIntegration(Integration $integration, $data);
    public function recordError(Integration $integration, $message);
}
```

### 3. Event Sourcing
Cada mudança importante registrada em `events` table com `correlation_id`

### 4. CQRS (Command Query Responsibility Segregation)
- **Commands**: Criar, atualizar rules/integrações
- **Queries**: Listar, buscar eventos/logs

### 5. Circuit Breaker
Desativa integração temporariamente se muitos erros

### 6. Retry with Exponential Backoff
```
Tentativa 1: imediato
Tentativa 2: +60s
Tentativa 3: +120s
```

## Segurança

### Autenticação
- JWT tokens com expiração configurável
- Refresh tokens
- MFA opcional (TOTP)

### Autorização
- RBAC com Spatie Permission
- Gate-based checks
- Policy-based authorization

### Dados
- Credenciais criptografadas (AES-256)
- Senhas com bcrypt
- Hash de tokens

### Comunicação
- HTTPS obrigatório
- CORS configurável
- Rate limiting por IP/API key

### Auditoria
- Todos os logins/logouts
- Alterações rastreadas
- IP e User Agent registrados
- Correlação end-to-end

## Performance & Escalabilidade

### Caching
- Redis para sessions
- Cache de configurações
- Cache de resultados

### Database
- Índices estratégicos
- Particionamento por data (logs)
- Connection pooling

### Queue
- Worker pool com Supervisor
- Processamento paralelo
- Auto-scaling possível

### API
- Rate limiting: 100 req/min por IP
- Pagination: 50 items default
- Response compression

## Monitoramento

### Métricas Coletadas
- Events recebidos/processados/falhados
- Tempo de resposta por integração
- Taxa de sucesso
- Queue depth
- Worker status

### Logs
- Estruturados (JSON)
- Níveis: DEBUG, INFO, WARNING, ERROR
- Rotação automática
- Retenção: 90 dias

### Alertas
- High error rate (>5%)
- Queue backup (>1000 msgs)
- Worker falha
- API timeout (>30s)

## Deployment

### Ambientes
- **Local**: Docker Compose
- **Staging**: Kubernetes
- **Production**: Kubernetes + LoadBalancer

### CI/CD
- GitHub Actions
- Testes antes do merge
- Migrations automáticas
- Rollback automático

## Diagrama de Fluxo de Dados

```
External System
      │
      │ POST /webhooks/events
      ▼
┌─────────────────────┐
│  API Gateway        │
│  - Validação        │
│  - Auth             │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Event Receiver     │
│  - Create Event     │
│  - Log              │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  RabbitMQ Queue     │
│  - Armazena Event   │
└──────────┬──────────┘
           │
    ┌──────┴──────┐
    ▼             ▼
 Worker1       Worker2
    │             │
    ▼             ▼
┌──────────────────────────┐
│  Event Processor         │
│  - Rules Engine          │
│  - Transformação         │
│  - Roteamento            │
└──────────┬───────────────┘
           │
    ┌──────┴──────┐
    ▼             ▼
[Partner A]  [Partner B]
```

## Componentes Críticos

### 1. Event Receiver
- Valida schema
- Cria Correlation ID
- Registra em DB
- Publica em queue

### 2. Rules Engine
- Avalia condições
- Define ações
- Registra execução
- Trata exceções

### 3. Integration Client
- REST/SOAP/Webhook
- Retry com backoff
- Timeout handling
- Logging detalhado

### 4. Webhook Dispatcher
- Pattern matching
- Delivery retry
- Signature validation
- Response handling

## Requisitos Não-Funcionais

| Requisito | Target | Implementação |
|-----------|--------|---------------|
| Throughput | 1000 events/min | RabbitMQ + Workers |
| Latência P95 | <5s | Cache + Async |
| Disponibilidade | 99.9% | HA + Failover |
| RPO | <1 min | Replicação |
| RTO | <15 min | Backup + Restore |
| Audit | 100% | Eventos + Logs |

## Evolução Futura

- [ ] GraphQL API
- [ ] Machine Learning para classification
- [ ] Advanced Analytics
- [ ] Blockchain para immutable audit
- [ ] Multi-tenancy
- [ ] Custom integration marketplace