INTEGRATIONS SUMMARY

Sumário Executivo - Integrações do Sport Tech Club

Status das Integrações

Produção (2)

• ✅ Ziggy - Controle de Acesso (CRÍTICA)
• ✅ Keycloak - Identity & SSO (CRÍTICA)

Implementação Parcial (3)

• 🟡 Payment Gateways - Stripe, Mercado Pago, PagSeguro (CRÍTICA)
• 🟡 Communication - WhatsApp, Push, Email, SMS (ALTA)
• 🟡 IoT Devices - MQTT, Tablets, RFID (ALTA)

Planejadas (5)

• 🔴 Video System - Streaming, Highlights (MÉDIA)
• 🔴 Antóctica Ecosystem - Wallet, Cross-app (ALTA)
• 🔴 Analytics - GA4, Mixpanel, Amplitude (BAIXA)
• 🔴 CRM - HubSpot, RD Station (BAIXA)
• 🔴 ERP - Integração Financeira (BAIXA)

---

Mapa de Prioridades

CRITICIDADE ALTA (Implementar Primeiro)
├── Ziggy (Sistema de Acesso) ✅
├── Keycloak (Autenticação) ✅
├── Payment Gateways (Pagamentos) 🟡
├── Communication (Notificações) 🟡
└── IoT Devices (Dispositivos) 🟡

CRITICIDADE MÉDIA (Q1 2026)
├── Video System (Highlights)
└── Antóctica Ecosystem (Wallet)

CRITICIDADE BAIXA (Q2-Q3 2026)
├── Analytics
├── CRM
└── ERP

---

Padrões Arquiteturais Implementados

1. Anti-Corruption Layer (ACL)

Cada integração externa possui um Adapter que traduz:

• APIs externas → Modelo de domínio interno
• Protege o core de mudanças em sistemas externos

2. Port & Adapter Pattern

Domain (Port) → Infrastructure (Adapter) → External System

3. Circuit Breaker

• Protege contra falhas em cascata
• Threshold: 5 falhas
• Timeout: 60 segundos
• Estados: CLOSED, OPEN, HALF_OPEN

4. Retry Policy

• Max Attempts: 3
• Backoff: Exponential
• Retries apenas em erros 5xx e timeouts

5. Idempotency

• Cache de resultados (24h TTL)
• Previne duplicação de operações críticas

---

Integrações Detalhadas

ZIGGY - Controle de Acesso

Endpoints Principais:

• POST /access/checkin - Check-in em quadra
• POST /access/checkout - Check-out de quadra
• POST /consumption/record - Registrar consumo
• GET /access/sessions/active - Sessões ativas

Eventos Webhook:

• access.checkin - Entrada registrada
• access.checkout - Saída registrada
• consumption.recorded - Consumo registrado

Features:

• ✅ Check-in/Check-out
• ✅ Rastreamento de consumo
• ✅ Webhooks em tempo real
• ✅ Circuit breaker
• ✅ Retry policy

---

KEYCLOAK - Identity & SSO

Fluxos Suportados:

• Authorization Code Flow (Web/Mobile)
• Client Credentials Flow (Service-to-Service)
• Refresh Token Flow

Features:

• ✅ OAuth 2.0 / OpenID Connect
• ✅ SSO (Single Sign-On)
• ✅ Multi-tenant
• ✅ Social Login (Google, Facebook)
• ✅ Token validation (JWKS)
• ✅ Admin API (gestão de usuários)
• ✅ Event listeners

Realms:

• sport-tech-club - Realm principal
• Roles: member, admin, manager, staff

---

PAYMENT GATEWAYS

Providers:

1. Stripe (Internacional)

   • Cartões internacionais
   • Subscriptions
   • Webhooks avançados

2. Mercado Pago (Brasil)

   • PIX
   • Boleto
   • Cartões nacionais

3. PagSeguro (Brasil)

   • PIX
   • Boleto
   • Cartões

Strategy Pattern:

PaymentGatewayFactory.create('STRIPE' | 'MERCADO_PAGO' | 'PAGSEGURO')

Features:

• 🟡 Pagamentos únicos
• 🟡 Subscriptions (recorrência)
• 🟡 Refunds
• 🟡 Webhooks
• 🟡 PIX (Mercado Pago)
• ⏳ Split payments
• ⏳ Marketplace

---

COMMUNICATION CHANNELS

Canais Suportados:

1. WhatsApp Business API (Twilio)

   • Mensagens de texto
   • Template messages (HSM)
   • Mídia (imagens, vídeos)
   • Status de entrega

2. Push Notifications (Firebase FCM)

   • iOS (APNs)
   • Android
   • Topics
   • Multicast

3. Email (SendGrid)

   • Templates dinâmicos
   • Bulk sending
   • Analytics

4. SMS (Twilio)

   • Fallback para WhatsApp
   • OTPs

Fallback Strategy:

Push → WhatsApp → SMS → Email

---

VIDEO SYSTEM (Planejado)

Provider Sugerido: Mux.com

Features:

• ⏳ Live streaming de quadras
• ⏳ Gravação automática
• ⏳ Criação de highlights
• ⏳ Botão físico para highlight
• ⏳ Transcodificação (HLS)
• ⏳ Thumbnails automáticos
• ⏳ Player embeddable

IoT Integration:

Botão Físico → MQTT → Handler → Mux API → Highlight (10s antes + 20s depois)

---

IOT DEVICES

Protocolos:

• MQTT (principal)
• HTTP REST (fallback)
• WebSocket (real-time)

Dispositivos:

1. Tablets de Quadra

   • Check-in/out
   • Status de quadra
   • Comandos remotos
   • Display customizado

2. Leitores RFID/NFC

   • Cartões de membro
   • Acesso rápido
   • Feedback visual (LED)

3. Botões de Highlight

   • Trigger via MQTT
   • Bateria (anos)
   • Feedback tátil

4. Sensores (Futuro)

   • Temperatura
   • Luminosidade
   • Ocupação
   • Qualidade do ar

MQTT Topics:

court/+/checkin
court/+/checkout
court/+/button/pressed
tablet/+/status
rfid/+/scan
court/+/sensors/#

---

ANTÓCTICA ECOSYSTEM (Planejado)

Shared Wallet:

• Saldo unificado entre apps
• Transferências inter-app
• Histórico consolidado
• Transações idempotentes

Cross-Application Events:

antoctica.*.user.* - Eventos de usuário
antoctica.*.wallet.* - Eventos de wallet
antoctica.sport-tech-club.* - Eventos publicados

Service-to-Service Auth:

• Client Credentials Flow (Keycloak)
• Token caching (5 min antes de expirar)

---

Segurança

Autenticação

• User-to-Service: OAuth 2.0 / OIDC (Keycloak)
• Service-to-Service: Client Credentials
• Webhooks: HMAC SHA-256 signature

Secrets Management

• AWS Secrets Manager
• Rotação automática
• Cache em memória

Rate Limiting

• Por IP: 100 req/min
• Por usuário: 1000 req/hour
• Por service: 10000 req/hour

Encryption

• TLS 1.3 em todas as conexões
• Dados sensíveis encrypted at rest
• PCI DSS compliance (pagamentos)

---

Resiliência

Circuit Breaker

CLOSED (normal) → 5 failures → OPEN (block requests)
                              ↓ after 60s
                         HALF_OPEN (test)
                              ↓ success
                         CLOSED (recovery)

Retry Policy

Attempt 1: immediate
Attempt 2: +1s
Attempt 3: +2s (exponential backoff)

Fallback Strategies

• Communication: Push → WhatsApp → SMS
• Payment: Stripe → Mercado Pago → PagSeguro
• Storage: Primary DB → Replica → Cache

Dead Letter Queue

• Failed integrations salvos para retry
• Alert em falhas críticas
• Max 5 tentativas
• Manual intervention após 5 falhas

---

Monitoramento

Métricas (Prometheus)

integration_request_duration_seconds{integration, operation, status}
integration_requests_total{integration, operation}
integration_errors_total{integration, operation, error_type}
integration_circuit_breaker_state{integration}

Health Checks

GET /health/integrations

{
  "status": "healthy" | "degraded",
  "integrations": [
    {
      "name": "ziggy",
      "status": "healthy",
      "latency": 45
    }
  ]
}

Logging

• Structured logging (JSON)
• Sensitive data sanitization
• Correlation IDs
• Request/Response logging

Alerting

• Integration failures > 10/min → PagerDuty
• Circuit breaker OPEN → Slack
• High latency (> 5s) → Email

---

Roadmap de Implementação

Q4 2025 (Concluído)

• ✅ Ziggy integration
• ✅ Keycloak setup
• ✅ Circuit breaker
• ✅ Retry policy

Q1 2026 (Em Progresso)

• 🟡 Payment gateways (Stripe, Mercado Pago)
• 🟡 WhatsApp Business API
• 🟡 Push notifications (FCM)
• 🟡 Email (SendGrid)
• 🟡 MQTT broker setup
• 🟡 RFID readers

Q2 2026

• ⏳ Video system (Mux)
• ⏳ Highlight buttons
• ⏳ Antóctica wallet integration
• ⏳ Analytics (Segment/Mixpanel)

Q3 2026

• ⏳ CRM integration (HubSpot)
• ⏳ ERP integration
• ⏳ Advanced sensors (temperature, light)
• ⏳ Wearables integration

---

Custos Estimados (Mensal)

Integração	Provider	Custo Mensal (USD)
Ziggy	Ziggy	$500 - $1000
Keycloak	Self-hosted	$200 (infra)
Stripe	Stripe	2.9% + $0.30/tx
Mercado Pago	Mercado Pago	4.99%/tx
WhatsApp	Twilio	$0.005/msg
Push	Firebase	Free (< 10M)
Email	SendGrid	$15 (40k/month)
SMS	Twilio	$0.0075/msg
Video	Mux	$200 - $500
MQTT	AWS IoT	$50 - $200
TOTAL		$1,000 - $2,500

---

Compliance & Standards

• ✅ LGPD - Lei Geral de Proteção de Dados
• ✅ PCI DSS Level 1 - Pagamentos (via Stripe/MP)
• ✅ OAuth 2.0 / OIDC - Authentication
• ✅ REST API Best Practices
• ✅ Webhook Security (HMAC signatures)
• 🟡 ISO 27001 - Information Security (em progresso)

---

Links Úteis

• Documentação Completa
• Architecture Decision Records
• API Documentation
• Runbooks

---

Mantido por: Time de Arquitetura - Sport Tech Club
Contato: arquitetura@sporttechclub.com
Última Atualização: 2026-01-09