millions/docs/21_ENGINEERING_GUIDELINES.md

Engineering Guidelines

Objetivo

Garantir consistência técnica no desenvolvimento com agentes de IA e reduzir deriva arquitetural entre sessões.

Regras gerais

• Usar TypeScript em todo o projeto
• Preferir server-side validation para mutações críticas
• Manter regras de negócio fora dos componentes visuais
• Manter o domínio explícito e nomeado
• Evitar abstrações prematuras

Backend dentro do Next.js

Na V1, o backend deve viver dentro do projeto Next.js.

Usar:

• Route Handlers quando for necessário expor endpoints
• Server Actions quando fizer sentido para mutações simples ligadas à UI
• camada server/services para regras de negócio
• camada server/repositories para acesso aos dados

Prisma

• Modelar entidades do domínio com nomes claros
• Usar migrations versionadas
• Evitar queries complexas diretamente em componentes
• Centralizar acesso à base de dados em repositórios ou queries server-side

Validação

• Usar Zod para validar inputs e payloads
• Reutilizar schemas entre UI e servidor quando fizer sentido
• Nunca confiar apenas na validação do cliente

UI

• Usar Tailwind CSS
• Usar shadcn/ui como base de componentes
• Criar componentes reutilizáveis para estados, tabelas, filtros e formulários
• Priorizar rapidez operacional sobre efeitos visuais

Estado e dados

• Preferir dados carregados no servidor
• Evitar estado global desnecessário na V1
• Só introduzir state management adicional se surgir necessidade clara

Segurança

• Usar Supabase Auth para autenticação base
• Proteger rotas privadas
• Gerir segredos por .env
• Não expor chaves sensíveis no cliente

Storage

• Usar Supabase Storage apenas quando a funcionalidade de imagens/anexos estiver confirmada
• Definir políticas mínimas de acesso antes de ativar uploads reais

Qualidade de código

• Cada feature deve ser desenvolvida com documentação mínima
• Atualizar 16_DECISIONS_LOG.md quando houver decisões relevantes
• Atualizar 17_PROGRESS.md no fim de marcos importantes
• Atualizar 18_AGENT_HANDOFF.md no fim de cada sessão relevante

O que evitar

• microserviços
• backend separado na V1
• GraphQL
• lógica de negócio espalhada por componentes
• modelos demasiado genéricos
• dependências pesadas sem necessidade clara