ORBIT Platform

Arquiteto principal, engenheiro sênior e operador do ORBIT — plataforma de inteligência aplicada agentiva. Use quando: (1) construindo ou expandindo o aplicativo ORBIT (backend Node.js/TypeScript + Fastify, frontend React/Vite/Tailwind, agentes OpenAI SDK, Supabase); (2) implementando qualquer agente especializado (Orquestrador, Pesquisa Web, Social, Acadêmica, Análise, Dossiê, Apresentação, Qualidade); (3) trabalhando com o schema Supabase do projeto (jobs, research_reports, dossiers, presentations, execution_traces, evidence_store, quality_gates, etc.); (4) conectando Telegram webhook ao pipeline; (5) construindo o Dashboard/Studio React; (6) depurando falhas no pipeline agentivo; (7) criando migrations SQL para o Supabase; (8) implementando quality gates e tracing de execução. Triggers: "construir ORBIT", "implementar agente", "fase A/B/C/D/E/F/G", "Supabase schema", "webhook Telegram", "dashboard ORBIT", "pipeline pesquisa", "dossiê", "apresentação HTML".

ORBIT Platform — Skill Operacional

Contexto do Projeto

ORBIT é uma plataforma agentiva de inteligência aplicada. Recebe comandos via Telegram ou Dashboard Web, aciona agentes especializados e entrega dossiês analíticos + apresentações HTML premium.

Credenciais e stack: Ver /workspace/projeto/backend/.env e /workspace/projeto/decisoes/2026-03-24-credenciais-finais.md

---

Stack Técnica

Camada	Tecnologia
Backend	Node.js + TypeScript + Fastify
Agentes	OpenAI Agents SDK (JS/TS) + GPT-4o
Banco	Supabase (projeto umwqxkggzrpwknptwwju)
Frontend	React + Vite + TypeScript + Tailwind CSS
Entrada	Telegram Bot API (webhook)
Filas	pgmq via RPCs do Supabase

---

Arquitetura em Camadas

text

Telegram / Dashboard
  → Webhook Handler (Fastify)
  → Command + Job criados no Supabase
  → Worker faz pop da fila (pop_intent_job_from_queue)
  → Orquestrador interpreta e distribui
      → Pesquisa Web + Social + Acadêmica (paralelo)
      → Análise
      → Dossiê
      → Apresentação HTML
      → Quality Review
  → Resultado persistido no Supabase
  → Notificação ao usuário (Telegram)
  → Dashboard atualizado (Realtime)

---

Agentes — Referência Rápida

Agente	Missão	Output
Orquestrador	Interpreta intenção, distribui handoffs	orchestration_result
Pesquisa Web	Busca + evidências de fontes web	research_result
Pesquisa Social	Discussões Reddit e fóruns	social_research_result
Pesquisa Acadêmica	Papers, DOI, OpenAlex	scholarly_research_result
Análise	Cruza evidências, gera SWOT	analysis_result
Dossiê	Documento estruturado analítico	dossier_result
Apresentação	HTML premium autocontido	presentation_result
Qualidade	Valida todos os outputs (score ≥ 7/10)	quality_review_result

Para contratos de dados completos: ver references/contratos-dados.md Para perfis detalhados dos agentes: ver references/perfis-agentes.md

---

Schema Supabase — Tabelas Principais

O banco (umwqxkggzrpwknptwwju) já tem 26 tabelas criadas e limpas. Não criar novas — usar as existentes.

Grupo	Tabelas
Core	commands, jobs, job_events
Pesquisa	research_reports, research_sources, research_branches, research_conflicts, evidence_store
Dossiês	dossiers, dossier_sources
Apresentações	presentations, studio_outputs
Rastreabilidade	execution_traces, execution_checkpoints, handoff_log
Qualidade	quality_gates, quality_evaluations
Inteligência	conversation_memory, knowledge_base, semantic_entities
Usuários	user_profiles, user_preferences
Config	directives, intent_patterns, pipeline_configs
Utilitários	notifications, calendar_events, tasks

RPCs prontos: pop_intent_job_from_queue, push_intent_job, log_trace, log_quality_eval, evaluate_quality_gates, get_conversation_context, match_intent_pattern, get_dashboard_stats, etc.

Para schema completo com campos: ver references/schema-supabase.md

---

Plano de Implementação

Fase	Objetivo	Status
A	Backend + Telegram webhook + criação de jobs	Próxima
B	Orquestrador + Pesquisa + Análise + Dossiê + Qualidade	Aguardando A
C	Pesquisa Social + Acadêmica	Aguardando B
D	Apresentações HTML	Aguardando B
E	Dashboard + Studio React	Paralelo com B/C
F	Robustez: retry, dead letter, tracing, testes	Após B
G	Refinamento visual e UX	Por último

---

Padrões de Código

Supabase Client (backend)

typescript

import { createClient } from '@supabase/supabase-js'
const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_KEY!
)

Criar job no Supabase

typescript

const { data: job } = await supabase
  .from('jobs')
  .insert({ command_id: cmdId, chat_id: chatId, status: 'pending' })
  .select().single()

Pop da fila

typescript

const { data } = await supabase.rpc('pop_intent_job_from_queue')

Log de trace

typescript

await supabase.rpc('log_trace', {
  p_job_id: jobId, p_agent: 'orchestrator', p_version: '1.0.0',
  p_step: 'intent_parsed', p_input: input, p_output: output,
  p_duration: durationMs, p_tokens: tokensUsed, p_status: 'ok'
})

Agente OpenAI SDK

typescript

import { Agent, run } from '@openai/agents'
const agent = new Agent({
  name: 'Orquestrador',
  model: 'gpt-4o',
  instructions: '...',
  tools: [...],
  handoffs: [researchAgent, analysisAgent]
})
const result = await run(agent, input)

Para exemplos completos de cada agente: ver references/exemplos-agentes.md

---

Regras de Execução

1. Nunca codifique sem entender o fluxo — verifique os contratos e o schema
2. Use sempre a service_role key do projeto umwqxkggzrpwknptwwju
3. Respeite as foreign keys ao deletar dados (filhos antes dos pais)
4. Quality gate obrigatório antes de qualquer entrega — score mínimo 7/10
5. Logs estruturados via log_trace RPC — nunca console.log em produção
6. HTML das apresentações deve ser autocontido — sem CDN externo
7. Idioma padrão: Português do Brasil em toda comunicação com o usuário
8. Nunca expor credenciais no código — sempre via variáveis de ambiente

---

Quality Gates

Tipo	Critério Mínimo
research_result	≥ 5 fontes, ≥ 3 ângulos do tema
analysis_result	Convergências + Divergências + Gaps + SWOT + Implicações
dossier_result	≥ 800 palavras, todas as seções obrigatórias
presentation_result	HTML autocontido, SWOT visual, responsivo
quality_review_result	Score geral ≥ 7/10

---

Referências Adicionais

• Contratos de dados JSON: references/contratos-dados.md
• Perfis completos dos agentes: references/perfis-agentes.md
• Schema Supabase completo: references/schema-supabase.md
• Exemplos de código por agente: references/exemplos-agentes.md
• Metodologia de trabalho: /workspace/projeto/metodologia/METODOLOGIA.md
• Workflows reutilizáveis: /workspace/projeto/workflows/WORKFLOWS.md
• Plano mestre: /workspace/projeto/PLANO-MESTRE.md