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 0001ADR 0002 — WAHA como primeiro provider não oficial
WAHA será usado para desenvolvimento e pilotos controlados atrás deMessagingProvider, 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 0003ADR 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 0004ADR 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 0005ADR 0006 — OpenTelemetry e Grafana stack
OpenTelemetry é o contrato de observabilidade. Alloy, Prometheus, Loki, Tempo e Grafana formam a stack inicial. Consultar ADR 0006ADR 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 0008Decisõ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
OFFpor padrão. COPILOTapenas preenche o composer.AUTOPILOTatua somente por tools controladas.- Handoff continua na mesma conversa.
- Scheduling permanece fonte da verdade diante do Google Calendar.
docs/prds/onboarding-inbox-ai-v1.mddocs/prds/appointments-vertical-v1.mddocs/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.
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.
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.