> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sistema de plugins

> Contratos, tipos, lifecycle, segurança e limites para capacidades e integrações da Orquena.

# 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:

```text theme={null}
id
name
version
type
capabilities provided
capabilities required
permissions
configuration schema
routes
jobs
events
UI extensions
AI tools
health check
compatibility range
network requirements
```

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

```text theme={null}
DISCOVERED
    ↓
VALIDATED
    ↓
INSTALLED
    ↓
CONFIGURED
    ↓
ENABLED
    ↓
DISABLED
    ↓
UNINSTALLED
```

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.

```text theme={null}
PluginCatalogEntry
PluginVersion
OrganizationPluginInstallation
PluginConfiguration
PluginCredential
```

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:

```text theme={null}
Capability: appointments.write
Permission: scheduling.appointments.manage
```

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](/architecture/open-source-strategy).