Decisões de Arquitetura (ADRs)

Registro das principais decisões técnicas e de produto tomadas no projeto. O objetivo é documentar o raciocínio por trás de cada escolha para que futuras alterações sejam conscientes das implicações.

O que é um ADR?

ADR (Architecture Decision Record) é um documento curto que captura uma decisão importante de arquitetura, incluindo:

• O contexto em que a decisão foi tomada
• As alternativas consideradas
• A escolha feita e por quê
• As consequências conhecidas

Decisões documentadas

#	Decisão	Status
ADR-001	NestJS como framework backend	Ativo
ADR-002	Chatwoot como plataforma de atendimento	Ativo
ADR-003	Clerk como provedor de autenticação	Ativo
ADR-004	Deploy via script + Docker Compose (sem Kubernetes)	Ativo

Outras decisões relevantes (registro compacto)

Stack geral

• [2026-03] Next.js 16 (App Router) + REST API própria — escolhido sobre monolito Next.js full-stack para permitir separação de deploy e escalar backend independentemente
• [2026-03] ignoreBuildErrors: true no next.config — TypeScript errors não bloqueam build em produção; permite deploy emergencial

Frontend

• [2026-03] Responsividade: Sidebar fixa no desktop (≥1024px), Drawer + BottomNav no mobile
• [2026-03] Dashboard com h-[100dvh] + flex hierárquico — viewport locked para caber em qualquer tela sem overflow
• [2026-03] PWA com service worker cache-first para shell, network-first para API

Backend

• [2026-04] Inbox customizado (/inbox) descontinuado em favor do Chatwoot — Chatwoot oferece features maduras de atendimento sem precisar reimplementar
• [2026-04] n8n como middleware de eventos entre Chatwoot e CRM — mantém o CRM desacoplado de workflows específicos de atendimento
• [2026-03] Timestamps sempre em UTC no banco; conversão para timezone local feita na camada de apresentação

Segurança

• [2026-04] AZURE_CLIENT_SECRET movido para /home/crm/.crm-secrets (fora do diretório do app, chmod 600) — garante que o secret não fica no git mesmo por acidente
• [2026-04] webhookVerifyToken e whatsappUnsubscribeToken armazenados como SHA-256 — plaintext nunca persistido
• [2026-04] CPF removido de todos os endpoints públicos e logs — somente hash + masked disponíveis externamente

Banco de dados

• [2026-03] Sincronização incremental do ERP usa trava global — evita duas instâncias de sync simultâneas que causariam duplicatas
• [2026-03] Soft delete não implementado — exclusões são permanentes, logs de auditoria registram o contexto antes da exclusão