Skip to main content

​
Sistema de plugins

O sistema de plugins é a principal estratégia de extensibilidade da Orquena.
O kernel fornece mecanismos. Plugins fornecem capacidades. Verticais compõem experiências. Providers traduzem infraestrutura externa.

​
Tipos de plugin

​
Domain plugins

Implementam capacidades de negócio e fontes de verdade:
  • Contacts.
  • Scheduling.
  • Inbox.
  • CRM.
  • Knowledge Base.
  • Notifications.
  • Automations.

​
Provider plugins

Adaptam infraestrutura substituível:
  • WAHA e Meta Cloud API.
  • Google e Microsoft Calendar.
  • Storage S3-compatible.
  • Model providers.
  • Email e pagamentos.

​
AI packs

Instalam templates, ferramentas, políticas e configurações para recepção, agendamento, vendas ou suporte.

​
External app connectors

Integram aplicações independentes por APIs, webhooks, SSO e mapeamento de IDs:
  • Twenty.
  • EspoCRM.
  • Chatwoot.
  • Cal.com.
  • Activepieces.

​
Verticals

Combinam plugins, defaults, onboarding e AI packs para um segmento. O primeiro vertical atende negócios baseados em agendamento.

​
Manifesto

Todo plugin deverá declarar:
IDs e exemplos novos usam Orquena, incluindo o reference plugin orquena.example. O namespace planejado para packages é @orquena/*. A instalação falha antes de produzir efeitos quando capabilities ou versões forem incompatíveis.

​
Lifecycle

Upgrade e rollback são ações versionadas. Remover um plugin não pode apagar dados sem um plano explícito de exportação ou retenção.

​
Plugins oficiais

Plugins first-party confiáveis podem ser compilados junto ao monólito modular. Mesmo assim, possuem limites de dependência e não acessam livremente repositories de outro domínio.

​
Plugins de terceiros

Executam em processo ou container isolado e não recebem:
  • Prisma Client.
  • Credencial global do banco.
  • Secrets de outras organizações.
  • Acesso irrestrito à rede.
  • Capabilities não declaradas.
A comunicação ocorre por SDK, APIs e eventos versionados.

​
Configuração por organização

Instalação global e ativação por organização são estados diferentes.
Secrets são criptografados e separados da configuração comum.

​
Capabilities e permissions

  • Capability: o que um plugin ou provider sabe oferecer.
  • Permission: quem pode usar ou administrar essa capacidade.
Exemplo:
Agentes recebem um subconjunto de tools derivado de capabilities e policies; não herdam automaticamente permissões do proprietário da organização.

​
Eventos e jobs

Plugins publicam contratos versionados e handlers idempotentes. Eventos nunca são usados para esconder uma necessidade de consistência síncrona. Jobs de longa duração seguem o package jobs, com organization, correlation ID e progress tracking.

​
Fonte da verdade

Um plugin não pode redefinir silenciosamente o domínio de outro.
  • Contacts controla identidade.
  • Inbox controla conversas.
  • Scheduling controla appointments.
  • CRM controla pipeline.
  • Connector controla somente mapping e sync state.

​
Conformance kit

Antes da ativação, um plugin deverá passar por:
  • Validação de manifesto.
  • Dependency graph.
  • Tenant isolation.
  • Permission tests.
  • Migration and rollback tests.
  • Event schema validation.
  • Retry and idempotency tests.
  • Health check.
  • License and third-party inventory.

​
Estratégia open source

Aplicações externas não viram plugins internos apenas porque possuem código público. A forma de integração depende da licença, source-of-truth e custo operacional. Consulte Estratégia open source.