Specification Pack v1
A primeira implementação será guiada por contratos explícitos, não por decisões improvisadas durante a geração de código.
Produto
O primeiro vertical atende empresas baseadas em agendamento.
Inclui:
CustomerAccount para assinatura e gestão comercial.- Uma
Organization tenant para cada loja operada separadamente.
- Agrupamento opcional de organizações sem compartilhamento automático de dados.
- Membros e permissões independentes por tenant.
- Serviços, preços versionados e profissionais.
- Horários de funcionamento, escalas, intervalos e agendamentos.
- Contatos, tags e inbox isolados por organização.
- Secretária de IA usando tools controladas.
- WAHA como primeiro provider de testes e pilotos.
- Notificações transacionais.
O cliente externo nunca precisa de conta no painel: ele utiliza o próprio WhatsApp para falar com o número comercial da organização.
Clínicas podem reutilizar o motor de agenda no futuro, mas prontuários, convênios e dados médicos ficam fora da primeira versão.
Tenancy
Cada organização é:
- Tenant.
- Fronteira de segurança.
- Unidade futura de cobrança.
- Proprietária de contatos, WhatsApp, catálogo, agenda, agentes e plugins.
OrganizationGroup serve apenas para navegação e relatórios explicitamente autorizados.
Agendamento
A disponibilidade é calculada pela interseção de:
- Horário de funcionamento da organização.
- Horário de trabalho do profissional.
- Intervalos, folgas, bloqueios e exceções.
- Serviço habilitado para o profissional.
- Duração e buffers.
- Agendamentos e holds existentes.
- Recursos obrigatórios.
- Lead time, horizonte e timezone.
A IA não interpreta escalas livremente. Ela chama uma tool de disponibilidade e recebe slots válidos.
Preços
Serviços possuem versões de preço com vigência.
- Novas consultas usam o preço vigente.
- Mudanças futuras podem ser agendadas.
- Agendamentos confirmados preservam o preço aceito.
- Alterar preço emite evento, mas não dispara mensagens automaticamente.
- Um plugin futuro de campanhas poderá criar um rascunho sujeito a consentimento e aprovação.
- Campanhas em massa via WAHA ficam desabilitadas no beta.
Plugins
Plugins oficiais são pacotes revisados do monorepo e descobertos por catálogo estático gerado no build.
A primeira versão não instala pacotes npm arbitrários em produção. Integrações externas executam em serviços ou containers isolados.
Cada plugin declara:
- ID e versão.
- Compatibilidade.
- Capabilities e dependências.
- Permissões.
- Configuração.
- Rotas e contribuições de interface.
- Eventos e jobs.
- Ferramentas para agentes.
- Health check e classificação dos dados.
Eventos e jobs
PostgreSQL é a fonte da verdade e utiliza transactional outbox para publicar eventos.
BullMQ sobre Valkey é o primeiro transporte de jobs, sempre atrás dos contratos da plataforma.
O worker não possui um tenant global ativo. Cada job abre um contexto isolado para sua organização, valida os registros e destrói o contexto ao terminar.
- Payload versionado.
organizationId confiável.- Idempotency key.
- Timeout.
- Retry classificado.
- Backoff.
- Dead-letter durável.
- Controle de concorrência.
- Retenção.
Modelo de dados
O modelo cobre identidade, conta comercial, tenancy, contatos, catálogo, versões de preço, profissionais, disponibilidade, agenda, inbox, IA, notificações, campanhas futuras, CRM opcional e operação da plataforma.
Dados específicos de novos verticais entram em plugins próprios.
Segurança
Controles críticos incluem:
- Membership e permissões por organização.
- Row-Level Security quando aplicável.
- Testes entre organizações irmãs.
- Webhooks autenticados e deduplicados.
- Resolução do tenant pelo mapeamento interno da conexão.
- Credenciais criptografadas.
- Agentes sem acesso direto ao banco.
- Tools com menor privilégio.
- Proteção contra prompt injection.
- Constraints transacionais para evitar conflito de agenda.
- Rate limits e budgets por organização.
Desempenho
Metas são separadas por tipo de carga.
Dez mil conexões realtime, dez mil sessões de WhatsApp e dez mil execuções de IA são problemas diferentes e nunca serão tratados como a mesma promessa.
A primeira etapa terá metas mensuráveis de API, disponibilidade, webhook, filas e concorrência, validadas por testes de carga antes da comercialização.