Skip to main content

​
Referências oficiais de desenvolvimento

Esta página reúne as fontes oficiais que devem ser consultadas antes de implementar ou alterar dependências, APIs e integrações da Orquena.
A documentação interna da Orquena define o que o produto deve fazer, seus limites e invariantes. A documentação oficial de cada fornecedor define como sua API, SDK ou ferramenta funciona na versão utilizada.
O catálogo técnico detalhado está versionado em:

​
Regra para humanos e agentes

Antes de implementar uma integração ou componente:
  1. Leia o PRD, ADR e contrato interno aplicável.
  2. Consulte a documentação oficial atual da ferramenta.
  3. Confira versão suportada, changelog e requisitos de runtime.
  4. Escolha o menor conjunto de permissões e capacidades necessário.
  5. Implemente atrás de um contrato pertencente à Orquena.
  6. Registre no pull request as versões e páginas oficiais consultadas.
Nunca trate snippets antigos, respostas de fórum, posts de terceiros ou memória do modelo como fonte principal quando houver documentação oficial.

​
Integrações principais do MVP

​
Google Login e Google Calendar

Use estas referências para criar o projeto OAuth, configurar consentimento, registrar redirect URIs e sincronizar appointments: Na Orquena, Google Login e Google Calendar continuam sendo consentimentos separados. A primeira sincronização é Orquena → Google, e a Orquena permanece a fonte da verdade.

​
WAHA

Use estas referências para configurar o provider de WhatsApp, sessões, QR Code, eventos e proteção da API: WAHA é infraestrutura substituível. Domínios, Inbox, Scheduling e AI Runtime não chamam o SDK ou a API do provider diretamente.

​
Mastra

Use estas referências para construir o AI Runtime, agentes e tools tipadas: Na Orquena, Mastra fica atrás de contratos próprios. Agentes utilizam tools controladas e nunca acessam Prisma ou tabelas de domínio diretamente.

​
Better Auth

Use estas referências para identidade, sessão, Google Login e migrations do framework: Better Auth cuida da mecânica de autenticação. CustomerAccount, Organization, memberships, autorização e integração com Calendar pertencem à Orquena.

​
Monorepo e aplicações

​
pnpm e Nx

O pnpm administra dependências e workspaces. O Nx administra o grafo de projetos, tarefas, cache, affected e limites arquiteturais.

​
Next.js

Valores NEXT_PUBLIC_* são públicos e nunca podem conter segredos.

​
NestJS e Fastify

​
Dados, jobs e observabilidade

​
Prisma e PostgreSQL

A versão do Prisma deve ser verificada antes do bootstrap, porque requisitos de runtime, configuração e adapters podem mudar entre versões principais.

​
BullMQ e Valkey

BullMQ e Valkey são transporte e coordenação. PostgreSQL e o transactional outbox preservam a autoridade e durabilidade do negócio.

​
OpenTelemetry e Grafana

​
OpenAI

Chaves da API são backend-only. Tools devem ter schemas explícitos, autorização tenant-aware, timeout, auditoria e idempotência quando produzirem efeitos.

​
Fontes preparadas para agentes

Quando disponíveis, prefira índices e formatos oficiais destinados a ferramentas de IA: Essas fontes ajudam na descoberta, mas não substituem os contratos internos da Orquena nem a validação da versão realmente instalada.

​
Manutenção

  • Verifique os links e versões antes de cada bootstrap ou upgrade importante.
  • Fixe versões de packages e imagens de container.
  • Leia changelogs e migration guides antes de atualizar versões principais.
  • Atualize esta página quando uma ferramenta for selecionada, substituída ou removida.
  • Não copie integralmente documentação externa para o repositório; registre apenas decisões, limites e links oficiais.