Introdução

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Integradores, Parceiros Técnicos e Arquitetura

Esta documentação apresenta a SOFIA sob a perspectiva de integração técnica.

O foco é permitir que parceiros entendam:

Como os dados fluem
Onde cada componente atua
Como consumir sinais e eventos de forma previsível e segura

1. O que é a SOFIA

A SOFIA é uma plataforma de apoio à decisão e disciplina operacional para roleta online.

Do ponto de vista técnico, a SOFIA fornece:

Processamento de contexto
Geração de sinais estruturados
Entrega em tempo real ou assíncrona
Modelos de integração adaptáveis (iframe, webhook, API Pull, WebSocket)

Esta documentação cobre exclusivamente a camada de integração.

2. Arquitetura Geral

A arquitetura da SOFIA é desacoplada por responsabilidade.

2.1 UIs (Edge – Vercel)

app.v1sofia.com — produto do usuário final
admin.v1sofia.com — painel do parceiro
pay.v1sofia.com — checkout e billing
www.v1sofia.com — aquisição
docs.v1sofia.com — documentação técnica
blog.v1sofia.com — conteúdo
compliance.v1sofia.com — documentação jurídica

2.2 Serviços (Vultr)

api.v1sofia.com — backend principal
ws.v1sofia.com — entrega em tempo real
worker.v1sofia.com — jobs, reconciliação e tarefas assíncronas

2.3 Dados (Supabase)

Autenticação
Persistência operacional
Histórico de spins
Estratégias
Billing e configurações

3. Fluxo de Dados

Pipeline simplificado:


Fontes de dados
   ↓
API (ingestão + normalização)
   ↓
Banco de Dados
   ↓
Strategy Engine
   ↓
Distribuição (Webhook / WebSocket / Iframe / API Pull)
   ↓
Aplicação do parceiro

4. Conceitos Fundamentais

Mesa (Table)

Identificador lógico da roleta (table_id).

Spin

Evento atômico (resultado da roleta + timestamp).

Histórico

Janela de spins recentes usada para cálculo e auditoria.

Estratégia

Conjunto de regras que gera decisão operacional.

Sinal

Saída estruturada da estratégia contendo:

seleção
validade
contexto
metadados

Parceiro

Entidade que integra a SOFIA ao seu próprio produto.

Ambientes

sandbox
production

Separação obrigatória de credenciais e URLs.

5. Modelos de Integração

A SOFIA suporta múltiplos modelos:

Iframe — integração rápida na UI.
postMessage — comunicação tempo real no navegador.
Webhook — recomendado para produção (robusto).
API Pull — controle total pelo parceiro.
WebSocket — canal contínuo em tempo real.

Detalhes em:

6. Fluxo Macro de Integração

1) Onboarding

Cadastro no Admin
Geração de credenciais

2) Escolha do Modelo

Definição do canal de consumo

3) Consumo de Eventos

Implementação idempotente
Validação de origem e assinatura

4) Observabilidade

Monitoramento de erros
Controle de retry
Alertas

7. Boas Práticas Iniciais

Antes de ir para produção:

Implementar idempotência
Validar assinaturas
Configurar timeout adequado
Separar sandbox de produção
Monitorar 4xx / 5xx