ARCHITECTURE — Pulse (documento comentado)

Exemplo da AEX Engineering. Este é um ARCHITECTURE.md modelo-ouro de um projeto fictício ("Pulse", um MVP de pesquisa de NPS). As anotações > 💡 não fazem parte do documento real — existem só para explicar por que cada parte está bem escrita.

💡 Abra com uma frase que qualquer pessoa entende, antes de qualquer diagrama. Se o leitor não sabe o que o sistema faz, o diagrama não ajuda.

Visão geral

Pulse coleta respostas de NPS via link público e mostra o resultado consolidado para o time do produto. É um Next.js único sobre Supabase — sem serviços extras, porque o MVP não precisa.

💡 Note a última frase: ela justifica uma ausência. Documentar o que não existe (e por quê) evita que o próximo dev "conserte" algo de propósito.

Diagrama de componentes

💡 Um diagrama simples que bate com a "visão geral". Diagrama que contradiz o texto gera desconfiança em tudo o mais.

Camadas e responsabilidades

💡 Tabela em vez de prosa: escaneável em segundos. A coluna "Neste projeto" conecta o conceito genérico à realidade — é isso que o leitor procura.

Decisões-chave

• Next.js full-stack para reduzir superfície no MVP → ver DECISIONS.md (ADR-001)
• Sem fila de mensagens: volume de respostas não justifica → ver DECISIONS.md (ADR-002)

💡 Não explique a decisão inteira aqui. Aponte para o DECISIONS.md (fonte única) e diga só o suficiente para o leitor decidir se precisa abrir.

Estratégia de escala

Enxuto agora. Se o volume de respostas crescer a ponto de travar a consolidação em tempo real, avaliamos materialização/cache — não antes.

💡 Fecha alinhado à filosofia "infra escalável só quando necessária". Dá um gatilho concreto ("quando travar a consolidação") em vez de um vago "no futuro".

---

💡 Rodapé com links relativos para os documentos irmãos. Facilita a navegação e reforça que os documentos formam um conjunto, não ilhas.

Modelo de dados: DATABASE.md · Contrato da API: API.md · Decisões: DECISIONS.md