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

# Multi-tenancy

> Modelo de conta comercial, organizações tenant, memberships e isolamento de dados.

# Multi-tenancy

A **Organization** é a principal fronteira de isolamento da plataforma.

Cada loja física operada separadamente é uma organização tenant distinta no primeiro vertical.

## Modelo conceitual

* **User:** pessoa autenticada.
* **CustomerAccount:** relação comercial, assinatura e limite de tenants.
* **AccountMembership:** vínculo administrativo ou financeiro com a conta.
* **OrganizationGroup:** agrupamento opcional para navegação e relatórios aprovados.
* **Organization:** tenant, loja e proprietária dos dados operacionais.
* **Membership:** vínculo do usuário com uma organização, incluindo papel e permissões.
* **OperatingLocation:** endereço principal da organização; não representa outra loja cobrável.

```text theme={null}
User: Gabriel
└── CustomerAccount: Negócios Gabriel
    ├── OrganizationGroup: Barbearias Gabriel
    │   ├── Organization: Centro
    │   ├── Organization: Shopping
    │   └── Organization: Zona Sul
    └── OrganizationGroup: Manicure Gabriel
        └── Organization: Loja principal
```

As organizações do mesmo grupo não compartilham automaticamente contatos, mensagens, agenda, profissionais, credenciais ou WhatsApp.

## Regra comercial

A assinatura base poderá incluir uma organização ativa. Organizações adicionais poderão consumir entitlements e gerar cobrança extra no futuro.

O valor não está definido nesta fase.

## Dados pertencentes ao tenant

Cada organização possui seus próprios:

* Membros e permissões.
* Perfil, endereço e timezone.
* Serviços e versões de preço.
* Profissionais, escalas e intervalos.
* Contatos, tags e campos personalizados.
* Inbox, conversas e mensagens.
* Conexão de WhatsApp.
* Agendamentos e notificações.
* Agentes, conhecimento e plugins.

O mesmo número de telefone pode existir como contatos independentes em organizações diferentes.

## Isolamento em camadas

```text theme={null}
Request, webhook or job
    ↓
Authenticated or trusted origin
    ↓
Account context when commercially relevant
    ↓
Organization membership or stored connection mapping
    ↓
Trusted organization context
    ↓
Repository ownership filtering
    ↓
PostgreSQL Row-Level Security
```

Toda entidade operacional pertencente ao cliente deve possuir `organizationId`.

## Webhooks e canais

Cada `ChannelConnection` pertence a exatamente uma organização.

No piloto inicial, cada organização possui um WhatsApp Business principal próprio.

A organização é resolvida usando o mapeamento interno da conexão. Um identificador de tenant enviado no payload externo nunca é considerado autoridade.

## Workers

O worker não possui um tenant global ativo.

Cada job:

1. Valida o envelope.
2. Carrega a organização.
3. Cria um contexto isolado.
4. Revalida o ownership dos registros.
5. Executa a operação.
6. Destrói o contexto.

Jobs de organizações diferentes podem rodar simultaneamente sem compartilhar contexto mutável.

## Regras

* A organização selecionada no frontend não é autorização.
* Ser proprietário da conta não concede leitura automática de dados de todas as organizações.
* `OrganizationGroup` não é uma fronteira de segurança.
* Cache, arquivos, filas, logs e realtime incluem escopo de organização.
* Testes de integração devem tentar acessar dados de uma organização irmã e confirmar a negação.
* Plugins externos não recebem acesso direto ao banco principal.
* Relatórios consolidados exigem serviço e permissão próprios, retornando somente dados agregados aprovados.

## Evolução futura

O modelo inicial utiliza banco compartilhado com isolamento lógico. Clientes maiores poderão futuramente receber schema, banco ou deployment dedicado sem alterar os contratos de domínio.

Qualquer compartilhamento de profissionais, clientes ou agendas entre organizações exigirá ADR próprio.