> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.callix.dev.br/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.callix.dev.br/_mcp/server.

# Arquitetura

## Arquitetura de pacotes

Três bibliotecas publicadas no npm sob `@callixbrasil`. Um pacote é uma biblioteca que o desenvolvedor instala com um comando e passa a usar no próprio código. A divisão não é arbitrária: cada um roda num lugar diferente, e é isso que mantém a chave de API fora do browser.

#### @callixbrasil/server-sdk

**Roda no servidor do parceiro.** Faz uma coisa só: troca a chave de API por um token de sessão de um usuário. É o único pedaço que conhece o segredo. Superfície mínima — uma classe, um método.

#### @callixbrasil/client-sdk

**Roda no browser do agente.** O núcleo. Registra o softphone (SIP/WebRTC), mantém a máquina de estados do operador, expõe a chamada atual, as pausas e as qualificações. Não depende de framework.

#### @callixbrasil/client-sdk-react

**Camada opcional, para quem usa React.** Empacota o núcleo em 17 hooks e um provider. É conveniência: quem não usa React fala direto com o núcleo, que expõe o mesmo estado por assinatura.

> **Tip**
>
> **React não é obrigatório.** O pacote `client-sdk` exporta a classe `CallixClientSdk` e os signals de estado (`.get()` e `.subscribe()`), o que permite consumo a partir de Angular, Vue, Svelte ou JavaScript puro. A ressalva: documentação e exemplos oficiais cobrem React, então esse é o caminho mais curto.

## Arquitetura de integração

Quatro atores e uma linha que a chave de API nunca cruza. O áudio não passa pelo servidor do parceiro — vai direto do browser do agente para a plataforma.

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {
  'actorBkg': '#1f2a37',
  'actorBorder': '#FF6840',
  'actorTextColor': '#ffffff',
  'actorLineColor': '#8a95a1',
  'signalColor': '#8a95a1',
  'signalTextColor': '#ffffff',
  'messageTextColor': '#ffffff',
  'noteBkg': '#2a2d35',
  'noteBorderColor': '#FF6840',
  'noteTextColor': '#ffffff',
  'sequenceNumberColor': '#ffffff'
}}}%%
sequenceDiagram
    autonumber
    participant S as server-sdk<br />(backend do parceiro)
    participant B as client-sdk<br />(browser do agente)
    participant CX as Plataforma Callix

    Note over S: CALLIX_API_KEY<br />segredo — nunca sai do backend
    S->>CX: cria a sessão (API key)
    CX-->>S: userSessionToken
    S->>B: só o token vai ao browser
    B->>CX: registra o softphone (SIP · WebRTC)
    B-->>CX: áudio + eventos de estado
    Note over B,CX: campanhas, contatos, pausas e qualificações<br />chegam no mesmo canal
```

O áudio vai direto do browser do agente para a plataforma — **nunca passa pelo backend do parceiro**.

> **Warning**
>
> O passo 3 é a razão de existir do `server-sdk`: o browser recebe um token de sessão descartável, nunca a chave de API. Quem obtiver o token consegue operar como aquele agente; quem obtivesse a chave de API operaria como qualquer um.

### Obrigações que isso impõe à aplicação parceira

* **Ter um backend.** Não há integração segura apenas com HTML e JavaScript no browser — algum servidor precisa guardar a chave de API.
* **Servir a aplicação por HTTPS.** O browser não libera o microfone fora de contexto seguro (localhost é a exceção, para desenvolvimento).
* **Mapear usuário da aplicação → usuário da Callix.** O token é emitido para um login específico da plataforma.