> ## 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.
# Arquitetura
> Resumo dos limites arquiteturais, fontes da verdade, processos e fluxos da Orquena.
# Arquitetura
A Orquena começa como um **monólito modular orientado a eventos**, com processos separados apenas quando carga, segurança ou isolamento justificarem.
Esta página resume o desenho. Contratos versionados, ADRs e documentos específicos continuam sendo a autoridade para implementação.
## Princípios obrigatórios
* O Platform Kernel permanece neutro em relação aos domínios de negócio.
* Cada registro tenant-owned pertence a uma `Organization`.
* Conta, grupo ou seleção no frontend não provam autorização.
* PostgreSQL é a fonte canônica do estado de negócio.
* Providers são substituíveis e não definem regras de domínio.
* Aplicações externas não compartilham o banco principal.
* AI Runtime não acessa Prisma nem tabelas diretamente.
* Mudanças de estado publicam eventos através de transactional outbox.
* Trabalhos assíncronos são versionados, idempotentes, observáveis e limitados.
* Realtime melhora a experiência, mas nunca é fonte da verdade.
## Hierarquia principal
```text theme={null}
CustomerAccount
├── AccountMembership
├── Subscription e entitlements
├── OrganizationGroup? // navegação e relatórios autorizados
└── Organization // tenant e loja
├── Memberships
├── Contacts
├── Services e prices
├── Professionals
├── Scheduling
├── Inbox e messages
├── Channel connections
├── AI configuration
└── Provider credentials
```
Cada loja operada separadamente é uma organização isolada. Uma organização irmã não recebe acesso implícito aos dados da outra.
## Processos planejados
| Processo | Responsabilidade principal |
| ---------------- | --------------------------------------------------------------- |
| `web` | Dashboard, onboarding, Inbox, agenda e configurações |
| `platform-admin` | Operação restrita da plataforma e suporte auditado |
| `api` | Kernel, domínios, comandos, queries, autorização e persistência |
| `worker` | Outbox, jobs, sincronizações, notificações e reconciliação |
| `realtime` | Eventos autorizados para interfaces conectadas |
| `ai-runtime` | Agentes, tools, workflows, políticas, avaliações e traces |
Os processos compartilham contratos públicos. Eles não atravessam limites importando implementações internas ou usando o banco como API improvisada.
## Modularidade
```text theme={null}
Platform Kernel
├── identity
├── tenancy
├── permissions
├── audit
├── configuration
├── events e jobs
├── files
├── entitlements
└── plugin runtime
First-party capabilities
├── contacts
├── service catalog
├── professionals
├── scheduling
├── inbox
├── notifications
├── CRM progressivo
└── automations
Providers
├── WAHA
├── Google Calendar
├── storage S3-compatible
├── AI providers
└── futuros adapters
```
Domínios dependem de contratos e capabilities. Um domínio não importa o SDK específico de um provider.
## Fluxo de mensagem
```text theme={null}
WhatsApp
↓
WAHA webhook
↓ autenticação, deduplicação e normalização
Persistência da mensagem
↓
Transactional outbox
↓
Router da conversa
├── atendimento humano
└── AI Runtime
↓ tool autenticada
Orquena API
↓ regra de domínio
resposta persistida
↓
provider de entrega
```
A API confirma o webhook rapidamente. Geração de IA nunca bloqueia o recebimento do evento do provider.
## Fluxo de agendamento
```text theme={null}
Pedido do cliente
↓
Tool de disponibilidade
↓
Scheduling Domain
↓
slots válidos
↓
AppointmentHold expirável
↓ confirmação explícita
Appointment confirmado atomicamente
↓
outbox e sincronizações
```
A proteção contra conflito ocorre na camada transacional. O modelo de linguagem não decide se um horário é válido.
## Fluxo de IA
```text theme={null}
AI Runtime
↓ chamada interna autenticada
Orquena API
↓ tenant, permission e policy recheck
Domain service
↓ authorized repository
PostgreSQL
```
Cada execução registra:
* Organização e identidade do agente.
* Template, prompt e model versions.
* Tool calls e referências de resultados.
* Tokens, custo, duração e erros.
* Decisões de política.
* Handoff e aprovação.
* Correlation e causation IDs.
## Eventos e jobs
PostgreSQL e outbox fazem a transição durável entre uma transação e o processamento assíncrono.
BullMQ sobre Valkey é o adapter inicial, atrás de contratos próprios.
Cada job tenant-owned inclui:
* Tipo e versão.
* `organizationId` confiável.
* Idempotency key.
* Correlation e causation IDs.
* Timeout.
* Política de retry e backoff.
* Limite de concorrência.
* Dead-letter e replay auditado.
Nenhum worker possui um tenant global ativo. O contexto é criado e destruído para cada execução.
## Dados e credenciais
* PostgreSQL guarda estado de negócio e metadados canônicos.
* Valkey guarda filas, cache e coordenação efêmera.
* Object storage guarda mídia e documentos.
* Credenciais são criptografadas e separadas de configuração comum.
* Tokens de providers nunca aparecem em logs ou eventos de domínio.
* Payloads externos permanecem dentro dos adapters.
## Extensibilidade
Plugins declaram:
* Identidade e versão.
* Capabilities fornecidas e exigidas.
* Permissions.
* Configuração e credenciais.
* Rotas e contribuições de UI.
* Eventos, jobs e tools.
* Compatibilidade e health checks.
A primeira implementação não executa pacotes arbitrários de terceiros dentro da API. Extensões externas exigem isolamento e contratos explícitos.
## Implantação inicial
A topologia inicial será Docker Compose em VPS, com containers separados para processos e serviços stateful.
A evolução para múltiplas máquinas, serviços gerenciados ou orquestração acontece somente com evidência de carga ou necessidade operacional. Separar deployment não muda automaticamente a propriedade dos domínios.
## Documentos detalhados
Contexto, camadas, processos e limites.
Organizações, memberships e isolamento.
Estrutura e regras de dependência.
Contratos aceitos antes do código.
Contratos canônicos adicionais:
* `docs/architecture/system-context-v1.md`
* `docs/architecture/data-model-v1.md`
* `docs/architecture/events-and-jobs-v1.md`
* `docs/architecture/plugin-contracts-v1.md`
* `docs/architecture/conversation-ai-control-v1.md`