Arquitetura

O Oraculo segue uma arquitetura de microsservicos distribuidos com bancos de dados centralizados.

Visao Geral

graph TB
    subgraph Frontend
        APP[Next.js App<br/>:3000]
    end

    subgraph APIs
        PLAT[Platform API<br/>Java Spring Boot<br/>:8085]
        TRACK[Tracker API<br/>Go Fiber<br/>:8282]
        MODELS[Models API<br/>Python FastAPI<br/>:8000]
    end

    subgraph Dados
        PG[(PostgreSQL<br/>:5432)]
        MONGO[(MongoDB<br/>:27017)]
        MINIO[(MinIO S3<br/>:9000)]
    end

    subgraph Monitoramento
        PROM[Prometheus<br/>:9090]
        GRAF[Grafana<br/>:3001]
        LOKI[Loki<br/>:3100]
    end

    subgraph Landing Page
        LP[Pagina do Cliente]
        SDK[Tracker SDK JS]
    end

    APP -->|REST| PLAT
    LP --> SDK
    SDK -->|POST /assets| TRACK
    TRACK -->|POST /predict| MODELS
    TRACK -->|WebSocket| LP

    PLAT --> PG
    MODELS --> PG
    MODELS --> MONGO
    MODELS --> MINIO
    TRACK --> MONGO

    PLAT --> PROM
    TRACK --> PROM
    MODELS --> PROM
    PROM --> GRAF
    LOKI --> GRAF

Componentes

Platform API (Java Spring Boot)

Responsavel pelo gerenciamento da plataforma:

• Autenticacao - Login/registro com JWT (HS512)
• Usuarios - CRUD de usuarios
• Datasources - Gerenciamento de landing pages monitoradas
• Success Events - Configuracao de eventos de conversao (seletores CSS)
• Actions - Configuracao de modais e redirecionamentos

Tracker API (Go Fiber)

Motor de coleta de eventos em tempo real:

• Coleta de eventos - Recebe dados comportamentais do SDK a cada 5s
• WebSocket - Canal em tempo real para envio de modais
• Analytics - Endpoints de metricas e series temporais
• Integracao ML - Chama a Models API para predicoes quando sessionTime >= threshold

Models API (Python FastAPI)

Motor de Machine Learning:

• Predicao - Recebe features e retorna probabilidade de conversao
• Treinamento - Treina modelos XGBoost com dados historicos do MongoDB
• Versionamento - Gerencia versoes de modelos com rollback
• Storage - Armazena artefatos no MinIO (S3)
• Scheduler - Jobs automaticos de treinamento e retreinamento

Frontend (Next.js)

Dashboard de gerenciamento:

• Autenticacao - Login/registro via NextAuth.js
• Dashboard - Listagem e gerenciamento de datasources
• Configuracao - Setup de eventos de sucesso e acoes (modais)

Fluxo de Dados

1. Configuracao

sequenceDiagram
    participant U as Usuario
    participant FE as Frontend
    participant PA as Platform API
    participant DB as PostgreSQL

    U->>FE: Login
    FE->>PA: POST /auth/login
    PA-->>FE: JWT Token

    U->>FE: Cria Datasource
    FE->>PA: POST /api/datasources
    PA->>DB: INSERT datasource
    PA-->>FE: Datasource criado

    U->>FE: Configura Success Event
    FE->>PA: POST /api/datasources/{id}/success-events
    PA->>DB: INSERT success_event

    U->>FE: Configura Modal
    FE->>PA: POST /api/datasources/{id}/actions
    PA->>DB: INSERT action

2. Tracking e Predicao

sequenceDiagram
    participant LP as Landing Page + SDK
    participant TA as Tracker API
    participant MO as MongoDB
    participant MA as Models API
    participant PG as PostgreSQL
    participant S3 as MinIO

    LP->>TA: POST /assets (eventos a cada 5s)
    TA->>MO: Upsert sessao

    alt sessionTime >= threshold
        TA->>MA: POST /api/v1/predict
        MA->>PG: Verifica cache de predicao
        alt Primeira predicao da sessao
            MA->>S3: Carrega modelo XGBoost
            MA->>MA: Executa predicao
            MA->>PG: Salva no cache
        end
        MA-->>TA: {probability, should_trigger, modal_html}

        alt should_trigger = true
            TA->>LP: WebSocket: envia modal
        end
    end

3. Treinamento Automatico

sequenceDiagram
    participant CRON as Scheduler (APScheduler)
    participant MA as Models API
    participant PG as PostgreSQL
    participant MO as MongoDB
    participant S3 as MinIO

    CRON->>MA: Check initial training (6h)
    MA->>PG: Busca datasources com modelo nao treinado
    MA->>MO: Conta sessoes do datasource

    alt sessoes >= initial_checkpoint (10.000)
        MA->>MO: Busca dados de sessoes
        MA->>MA: Treina XGBoost
        MA->>S3: Salva artefato .pkl
        MA->>PG: Atualiza model + model_version
    end

    CRON->>MA: Check retrain (6h)
    MA->>PG: Busca modelos que precisam retreinar

    alt sessoes >= retrain_checkpoint (50.000)
        MA->>MO: Busca dados atualizados
        MA->>MA: Retreina modelo
        MA->>S3: Salva nova versao
        MA->>PG: Cria model_version + promove
    end

Portas e Servicos

Servico	Porta	Protocolo
Frontend (Next.js)	3000	HTTP
Platform API (Spring Boot)	8085	HTTP
Tracker API (Fiber)	8282	HTTP + WebSocket
Models API (FastAPI)	8000	HTTP
PostgreSQL	5432	TCP
MongoDB	27017	TCP
MinIO API	9000	HTTP
MinIO Console	9001	HTTP
Prometheus	9090	HTTP
Grafana	3001	HTTP
Loki	3100	HTTP