# 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