Projeto e engenharia

Decisões técnicas

Relatório das decisões técnicas que orientam a arquitetura, as tecnologias escolhidas, a qualidade de software e a governança de dados do GOBPS.

Interface e experiência

A interface foi organizada para transformar conteúdo político extenso em uma consulta direta, responsiva e consistente.

Astro e componentes orientados a conteúdo
- Geração estática para rotas de consulta rápidas.
- Componentes reutilizáveis e Tailwind CSS para preservar padrões visuais e responsividade.
Dados servidos exclusivamente pelo backend
- O navegador não mantém catálogo local nem respostas simuladas.
- Estados de foco, imagens com dimensões definidas e navegação por teclado fazem parte da implementação.
Verificação de fluxos críticos
- Playwright cobre páginas, filtros, comparação e layouts em desktop e celular.

O backend é a camada que estabiliza os contratos públicos e evita que detalhes de provedores externos vazem para a interface.

.NET 9 e API REST
- Controllers pequenos delegam fluxos a casos de uso, serviços e repositórios.
- Validação de entrada e Problem Details tornam erros previsíveis para o cliente.
SOLID e Clean Code aplicados ao domínio
- Dependências apontam para o domínio; nomes e responsabilidades permanecem explícitos.
- Dados JSON versionados são tratados por adaptadores próprios enquanto não há banco transacional.
Proveniência como parte do contrato
- Dados públicos guardam fonte, data de consulta e critérios de uso quando aplicável.

A qualidade é tratada como parte da entrega: testar, observar e falhar de modo compreensível reduz regressões e facilita manutenção.

Testes automatizados em duas camadas
- Testes de backend usam clientes falsos apenas no ambiente de teste; respostas públicas não recebem dados simulados.
- Testes de contrato protegem a integração entre Astro e backend.
Observabilidade com privacidade
- Logs estruturados e métricas de requisição apoiam diagnóstico sem registrar dados pessoais.
- Integrações externas têm timeout, resiliência e tratamento explícito de indisponibilidade.
Configuração protegida
- Segredos ficam fora do código versionado; o formulário de contato recebe proteção anti-robô e limites proporcionais.

O projeto adota práticas proporcionais ao seu estágio atual para manter histórico de decisões, revisão e publicação reproduzível.

Branches e integração contínua
- Branches de trabalho, development e main separam desenvolvimento, revisão e produção.
- GitHub Actions executa restauração, auditoria de dependências e testes antes do deploy; Dependabot propõe atualizações para revisão.
Automação com revisão humana
- Atualizações de conteúdo só avançam com fonte, contrato e validação confiáveis.
- Fatos políticos e alterações editoriais permanecem sujeitos a revisão humana.
Uso responsável de informação pública
- Fontes oficiais, inventário de proveniência, créditos e licenças orientam a curadoria.
- A LGPD orienta minimização de dados, finalidade clara e canais para correção, crítica, feedback e sugestões.