- name
- orbit-platform
- description
- >
- Triggers
- construir ORBIT", "implementar agente", "fase A/B/C/D/E/F/G", "Supabase schema",
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
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)
import { createClient } from '@supabase/supabase-js'
const supabase = createClient(
process.env.SUPABASE_URL!,
process.env.SUPABASE_SERVICE_KEY!
)Criar job no Supabase
const { data: job } = await supabase
.from('jobs')
.insert({ command_id: cmdId, chat_id: chatId, status: 'pending' })
.select().single()Pop da fila
const { data } = await supabase.rpc('pop_intent_job_from_queue')Log de trace
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
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
- Nunca codifique sem entender o fluxo — verifique os contratos e o schema
- Use sempre a service_role key do projeto
umwqxkggzrpwknptwwju - Respeite as foreign keys ao deletar dados (filhos antes dos pais)
- Quality gate obrigatório antes de qualquer entrega — score mínimo 7/10
- Logs estruturados via
log_traceRPC — nunca console.log em produção - HTML das apresentações deve ser autocontido — sem CDN externo
- Idioma padrão: Português do Brasil em toda comunicação com o usuário
- 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