Plataforma ORBIT — Habilidade Operacional

Contexto do Projeto

ORBIT é uma plataforma agêntica 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

Telegram / Dashboard
→ Webhook Handler (Fastify)
→ Command + Job criados no Supabase
→ Worker faz pop da fila (popintentjobfromqueue)
→ 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	orchestrationresult
Pesquisa Web

Busca + evidências de fontes web | researchresult |
| Pesquisa Social | Discussões Reddit e fóruns | socialresearchresult |
| Pesquisa Acadêmica | Papers, DOI, OpenAlex | scholarlyresearchresult |
| 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) | qualityreviewresult |

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, jobevents
Pesquisa

researchreports, researchsources, researchbranches, researchconflicts, evidencestore |
| Dossiês | dossiers, dossier_sources |
| Apresentações | presentations, studio_outputs |
| Rastreabilidade | executiontraces, executioncheckpoints, handoff_log |
| Qualidade | qualitygates, qualityevaluations |
| Inteligência | conversationmemory, knowledgebase, semantic_entities |
| Usuários | userprofiles, userpreferences |
| Config | directives, intentpatterns, pipelineconfigs |
| Utilitários | notifications, calendar_events, tasks |

RPCs prontos: popintentjobfromqueue, pushintentjob, logtrace, logquality_eval,
evaluatequalitygates, getconversationcontext, matchintentpattern, getdashboardstats, 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.SUPABASESERVICEKEY! )

Criar job no Supabase

typescript const { data: job } = await supabase .from(jobs) .insert({ commandid: cmdId, chatid: chatId, status: pending }) .select().single()

Pop da fila

typescript const { data } = await supabase.rpc(popintentjobfromqueue)

Log de trace

typescript await supabase.rpc(log_trace, { pjobid: jobId, pagent: orchestrator, pversion: 1.0.0, pstep: intentparsed, pinput: input, poutput: output, pduration: durationMs, ptokens: 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. 1. Nunca codifique sem entender o fluxo — verifique os contratos e o schema
2. Use sempre a servicerole 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 logtrace 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
researchresult	≥ 5 fontes, ≥ 3 ângulos do tema
analysisresult

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 | | qualityreviewresult | 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