​

Arquitetura

​

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

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

​

Processos planejados

​

Modularidade

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

​

Fluxo de mensagem

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

​

Fluxo de agendamento

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

​

Fluxo de IA

AI Runtime
    ↓ chamada interna autenticada
Orquena API
    ↓ tenant, permission e policy recheck
Domain service
    ↓ authorized repository
PostgreSQL

• 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

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

​

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

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

​

Implantação inicial

​

Documentos detalhados

• 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