​

Decisões

A Orquena registra decisões importantes em ADRs individuais. Esta página funciona como índice e resumo; ela não substitui os registros versionados.

​

Regras de governança

• Números de ADR nunca são reutilizados.
• Cada ADR mantém contexto, decisão, consequências, alternativas e condições de reavaliação.
• ADRs superseded permanecem acessíveis.
• Mudanças arquiteturais entram antes ou no mesmo PR da implementação.
• RFCs representam propostas ainda não aceitas.
• Overview pages não podem alterar silenciosamente uma decisão formal.
• Código e documentação não podem contrariar um ADR sem substituição explícita.

​

ADRs aceitos

​

ADR 0001 — Domínios nativos e conectores externos

A Orquena mantém contratos e fontes da verdade próprias para domínios essenciais. Aplicações externas integram por APIs, webhooks e mappings e não compartilham o banco principal. Consultar ADR 0001

​

ADR 0002 — WAHA como primeiro provider não oficial

WAHA será usado para desenvolvimento e pilotos controlados atrás de MessagingProvider, preservando Meta Cloud API como direção oficial futura. Consultar ADR 0002

​

ADR 0003 — BullMQ sobre Valkey

BullMQ sobre Valkey é o adapter inicial de jobs. Domínios usam contratos próprios, e PostgreSQL outbox faz a transição durável das transações para o processamento assíncrono. Consultar ADR 0003

​

ADR 0004 — Object storage S3-compatible

A aplicação utiliza um contrato genérico S3-compatible. Managed storage é permitido; SeaweedFS é candidato self-hosted; MinIO fica como compatibilidade revisada. Consultar ADR 0004

​

ADR 0005 — Better Auth para identidade e sessões

Better Auth implementa credenciais, providers, verification e sessões. Tenancy, memberships, permissions e billing permanecem contratos da Orquena. Consultar ADR 0005

​

ADR 0006 — OpenTelemetry e Grafana stack

OpenTelemetry é o contrato de observabilidade. Alloy, Prometheus, Loki, Tempo e Grafana formam a stack inicial. Consultar ADR 0006

​

ADR 0007 — CustomerAccount e Organization tenants

CustomerAccount representa a relação comercial. Cada Organization é uma loja, tenant, fronteira de dados e futura unidade faturável. Agrupamentos não concedem acesso. Consultar ADR 0007

​

ADR 0008 — Orquena como marca do produto

Orquena é o nome canônico da plataforma, do repositório, dos domínios e dos novos namespaces de produto. Consultar ADR 0008

​

Decisões de produto aceitas

Nem toda regra de produto exige ADR. Comportamentos observáveis pertencem aos PRDs versionados. Decisões atuais incluem:

• Google Login e email/senha no MVP.
• Calendar autorizado em consentimento separado.
• Setup persistido e progresso calculado no backend.
• WhatsApp conectado cedo com sincronização recente limitada.
• Orquena Inbox como domínio canônico de conversas.
• IA OFF por padrão.
• COPILOT apenas preenche o composer.
• AUTOPILOT atua somente por tools controladas.
• Handoff continua na mesma conversa.
• Scheduling permanece fonte da verdade diante do Google Calendar.

Fontes:

• docs/prds/onboarding-inbox-ai-v1.md
• docs/prds/appointments-vertical-v1.md
• docs/architecture/conversation-ai-control-v1.md

​

Decisões ainda necessárias antes do bootstrap

• Versões e política do workspace pnpm/Nx.
• Estrutura definitiva de apps e packages executáveis.
• PostgreSQL, Prisma encapsulado, migrations e RLS.
• Contratos HTTP e formato de erros.
• Configuração tipada e secret management.
• Lifecycle mínimo de plugins no código.
• Transporte realtime inicial.

Essas decisões devem entrar em ADRs ou contratos técnicos antes de serem tratadas como implementação aceita.

​

Dependências open source

A adoção de uma dependência exige registro de:

• Licença e modelo de distribuição.
• Versão revisada.
• Obrigações de atribuição ou network use.
• Manutenção, releases e advisories.
• Dados processados e fronteiras de segurança.
• Upgrade, rollback e alternativa de saída.

Pesquisa ou proof of concept não equivale a decisão aceita.

​

Por que os ADRs continuam separados

Manter cada ADR em arquivo próprio preserva:

• Histórico de revisão por decisão.
• Links estáveis.
• Ownership e code review focados.
• Diferença clara entre mudança editorial e mudança arquitetural.
• Supersession sem reescrever o passado.

Esta página pode evoluir como mapa de leitura, mas não concentra todo o conteúdo dos ADRs em um único arquivo.