Banco de Dados

O Oraculo utiliza dois bancos de dados: PostgreSQL para dados relacionais e MongoDB para eventos de sessao.

PostgreSQL

Banco relacional principal, compartilhado entre Platform API (Java) e Models API (Python).

Diagrama ER

erDiagram
    users ||--o{ datasources : possui
    datasources ||--o{ success_events : tem
    datasources ||--o{ actions : tem
    datasources ||--o{ model : tem
    model ||--o{ model_version : tem
    model ||--o{ training_log : tem
    model ||--|| model_version : active_version

    users {
        uuid id PK
        string email UK
        string password
        string name
        timestamp created_at
        timestamp updated_at
    }

    datasources {
        uuid id PK
        uuid user_id FK
        string name
        string url
        enum type
        enum status
        int initial_checkpoint
        int retrain_checkpoint
    }

    success_events {
        uuid id PK
        uuid datasource_id FK
        string name
        enum selector
        string selector_value
    }

    actions {
        uuid id PK
        uuid datasource_id FK
        int seconds_exit
        int percentage_exit
        string action
        text action_value
    }

    model {
        uuid id PK
        uuid datasource_id FK
        string created_by
        timestamp created_at
        boolean trained
        boolean need_train
        timestamp last_train
        int last_session_count
        string name
        string artifact_path
        string algorithm
        json metrics
        json model_parameters
        uuid active_version_id FK
    }

    model_version {
        uuid id PK
        uuid model_id FK
        timestamp created_at
        timestamp trained_at
        enum status
        json metrics
        string artifact_path
        json deployment_info
    }

    training_log {
        uuid id PK
        uuid model_id FK
        timestamp started_at
        timestamp completed_at
        string status
        int session_count
        json metrics
    }

    prediction_cache {
        uuid id PK
        string session_id UK
        uuid datasource_id
        float probability
        boolean should_trigger
        boolean triggered
        uuid model_id
        string model_version
        timestamp created_at
        timestamp triggered_at
    }

Tabelas

users

Gerenciada pela Platform API (Hibernate).

Coluna	Tipo	Constraints	Descricao
id	UUID	PK	Identificador unico
email	VARCHAR	UNIQUE, NOT NULL	Email do usuario
password	VARCHAR	NOT NULL	Senha hashada (bcrypt)
name	VARCHAR	NOT NULL	Nome do usuario
created_at	TIMESTAMP	NOT NULL	Data de criacao
updated_at	TIMESTAMP		Data de atualizacao

---

datasources

Landing pages monitoradas. Gerenciada pela Platform API.

Coluna	Tipo	Constraints	Descricao
id	UUID	PK	Identificador unico
user_id	UUID	FK (users)	Proprietario
name	VARCHAR	NOT NULL	Nome da landing page
url	VARCHAR	NOT NULL	URL da pagina
type	ENUM	NOT NULL	VSL ou SVSL
status	ENUM	NOT NULL	Status atual
initial_checkpoint	INT	DEFAULT 10000	Sessoes para 1o treino
retrain_checkpoint	INT	DEFAULT 50000	Sessoes para retreino

Enum type:

Valor	Descricao
VSL	Video Sales Letter
SVSL	Short Video Sales Letter

Enum status:

Valor	Descricao
CREATED	Recem-criado
INSTALLED	SDK instalado
TESTED	Eventos de teste recebidos
DONE	Configuracao completa
ACTIVE	Ativo e coletando
INACTIVE	Desativado

---

success_events

Eventos que definem conversao. Gerenciada pela Platform API.

Coluna	Tipo	Constraints	Descricao
id	UUID	PK	Identificador unico
datasource_id	UUID	FK (datasources)	Datasource associado
name	VARCHAR	NOT NULL	Nome descritivo
selector	ENUM	NOT NULL	Tipo de seletor CSS
selector_value	VARCHAR	NOT NULL	Valor do seletor

Enum selector:

Valor	Exemplo	Descricao
CLASS	btn-comprar	Classe CSS do elemento
ID	checkout-button	ID do elemento
HREF	/checkout	Link href

---

actions

Intervencoes (modais/redirecionamentos). Gerenciada pela Platform API.

Coluna	Tipo	Constraints	Descricao
id	UUID	PK	Identificador unico
datasource_id	UUID	FK (datasources)	Datasource associado
seconds_exit	INT	NULLABLE	Tempo minimo antes do modal (s)
percentage_exit	INT	NULLABLE	Threshold de probabilidade (0-100)
action	VARCHAR	NOT NULL	MODAL ou REDIRECT
action_value	TEXT	NOT NULL	HTML do modal ou URL de redirect

---

model

Modelos de ML. Gerenciada pela Models API (SQLAlchemy).

Coluna	Tipo	Constraints	Descricao
id	UUID	PK	Identificador unico
datasource_id	UUID	FK (datasources)	Datasource associado
created_by	VARCHAR		Quem criou
created_at	TIMESTAMP		Data de criacao
trained	BOOLEAN	DEFAULT false	Se ja foi treinado
need_train	BOOLEAN	DEFAULT false	Se precisa retreinar
last_train	TIMESTAMP	NULLABLE	Ultimo treinamento
last_session_count	INT	DEFAULT 0	Sessoes no ultimo treino
name	VARCHAR		Nome da versao
artifact_path	VARCHAR		Caminho no MinIO
algorithm	VARCHAR		XGBClassifier
metrics	JSON		Metricas de treinamento
model_parameters	JSON		Hiperparametros
active_version_id	UUID	FK (model_version)	Versao em producao

---

model_version

Versoes de modelos treinados.

Coluna	Tipo	Constraints	Descricao
id	UUID	PK	Identificador unico
model_id	UUID	FK (model)	Modelo pai
created_at	TIMESTAMP		Data de criacao
trained_at	TIMESTAMP		Data de treinamento
status	ENUM		Status da versao
metrics	JSON		Metricas (accuracy, f1, etc.)
artifact_path	VARCHAR		Caminho do .pkl no MinIO
deployment_info	JSON		Info de deploy

Enum status:

Valor	Descricao
TRAINING	Treinamento em andamento
READY	Pronto para uso
DEPRECATED	Versao substituida
FAILED	Treinamento falhou

---

training_log

Historico de treinamentos.

Coluna	Tipo	Constraints	Descricao
id	UUID	PK	Identificador unico
model_id	UUID	FK (model)	Modelo
started_at	TIMESTAMP		Inicio do treinamento
completed_at	TIMESTAMP		Fim do treinamento
status	VARCHAR		Status (success/failed)
session_count	INT		Sessoes usadas
metrics	JSON		Metricas resultantes

---

prediction_cache

Cache de predicoes para idempotencia.

Coluna	Tipo	Constraints	Descricao
id	UUID	PK	Identificador unico
session_id	VARCHAR	UNIQUE, INDEX	ID da sessao
datasource_id	UUID	INDEX	Datasource
probability	FLOAT		Probabilidade predita
should_trigger	BOOLEAN		Se deve disparar modal
triggered	BOOLEAN	DEFAULT false	Se o modal foi exibido
model_id	UUID		Modelo usado
model_version	VARCHAR		Versao do modelo
created_at	TIMESTAMP		Data da predicao
triggered_at	TIMESTAMP	NULLABLE	Data do trigger

Indices compostos: (session_id, datasource_id)

---

MongoDB

Banco documental para armazenar eventos de sessao em alta velocidade.

Collection sessions

Campo	Tipo	Descricao
_id	ObjectId	ID interno do MongoDB
clientId	String	UUID do datasource
sessionId	String	Identificador da sessao
url	String	URL completa
path	String	Path da pagina
referrer	String	URL de origem
utm_source	String	UTM source
utm_medium	String	UTM medium
utm_campaign	String	UTM campaign
mouseX	Int	Posicao X do mouse
mouseY	Int	Posicao Y do mouse
mouseVelocity	Float	Velocidade do mouse
scrollVelocity	Float	Velocidade de scroll
maxScrollDepth	Int	Scroll maximo (0-100)
idleTime	Float	Tempo ocioso (s)
pageVisibility	String	visible / hidden
lastClickedTag	String	Tag do ultimo clique
sessionTime	Float	Tempo na pagina (s)
sessionOutcome	String	Resultado da sessao
targetClicked	String	Seletor do alvo clicado
sessionStartedAt	Int64	Timestamp inicio (ms)
modalDisplayedAt	Int64	Timestamp do modal (ms)
modalClosedAt	Int64	Timestamp fechar modal (ms)
modalInteraction	String	Tipo de interacao
windowFocused	Boolean	Janela em foco
focusChanges	Int	Trocas de foco
createdAt	Timestamp	Data de criacao

Upsert por sessionId

O Tracker API faz upsert (insert or update) usando sessionId como chave. Cada evento atualiza o documento existente da sessao ao inves de criar um novo.

---

MinIO (S3 Storage)

Armazena artefatos de modelos treinados (arquivos .pkl).

Bucket: oraculo-models

oraculo-models/
└── {datasource_id}/
    ├── {model_id}_XGBClassifier_20250115_020000.pkl
    ├── {model_id}_XGBClassifier_20250116_020000.pkl
    └── {model_id}_XGBClassifier_20250117_020000.pkl  (ativo)

Convencao de nomes: {model_id}_{algorithm}_{YYYYMMDD}_{HHMMSS}.pkl