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#

CamadaTecnologiaBackendNode.js + TypeScript + FastifyAgentesOpenAI Agents SDK (JS/TS) + GPT-4oBancoSupabase (projeto umwqxkggzrpwknptwwju)FrontendReact + Vite + TypeScript + Tailwind CSSEntradaTelegram Bot API (webhook)Filaspgmq 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#

AgenteMissãoOutputOrquestradorInterpreta intenção, distribui handoffsorchestration_resultPesquisa WebBusca + evidências de fontes webresearch_resultPesquisa SocialDiscussões Reddit e fórunssocial_research_resultPesquisa AcadêmicaPapers, DOI, OpenAlexscholarly_research_resultAnáliseCruza evidências, gera SWOTanalysis_resultDossiêDocumento estruturado analíticodossier_resultApresentaçãoHTML premium autocontidopresentation_resultQualidadeValida 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.

GrupoTabelasCorecommands, jobs, job_eventsPesquisaresearch_reports, research_sources, research_branches, research_conflicts, evidence_storeDossiêsdossiers, dossier_sourcesApresentaçõespresentations, studio_outputsRastreabilidadeexecution_traces, execution_checkpoints, handoff_logQualidadequality_gates, quality_evaluationsInteligênciaconversation_memory, knowledge_base, semantic_entitiesUsuáriosuser_profiles, user_preferencesConfigdirectives, intent_patterns, pipeline_configsUtilitáriosnotifications, 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#

FaseObjetivoStatusABackend + Telegram webhook + criação de jobsPróximaBOrquestrador + Pesquisa + Análise + Dossiê + QualidadeAguardando ACPesquisa Social + AcadêmicaAguardando BDApresentações HTMLAguardando BEDashboard + Studio ReactParalelo com B/CFRobustez: retry, dead letter, tracing, testesApós BGRefinamento visual e UXPor ú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#

TipoCritério Mínimoresearch_result≥ 5 fontes, ≥ 3 ângulos do temaanalysis_resultConvergências + Divergências + Gaps + SWOT + Implicaçõesdossier_result≥ 800 palavras, todas as seções obrigatóriaspresentation_resultHTML autocontido, SWOT visual, responsivoquality_review_resultScore 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