achaí-API

Aplicação web que busca endereços brasileiros pelo CEP ou pelo nome da rua. O back-end é uma API em C#/.NET, e o front é um app em Angular.

Demo: achai-api.vercel.app · Documentação da API: achai-api.vercel.app/docs

Como foi feito

O projeto começou como uma API simples que repassava as respostas do ViaCEP e foi reconstruído em etapas, cada uma com a decisão registrada num ADR.

API em vertical slices: cada rota é uma fatia completa (rota, validação e handler), e as fontes externas ficam atrás de interfaces.
Erros previsíveis: CEP inexistente ou parâmetro inválido viram respostas padronizadas (ProblemDetails), com mensagens em português; erro inesperado vira um 500 genérico, com o detalhe só no log.
Robustez nas fontes externas: cache em memória, timeout, retry e circuit breaker em cada chamada, e a BrasilAPI assume quando o ViaCEP falha numa busca por CEP.
Contrato compartilhado: o front usa tipos gerados a partir do documento OpenAPI da API, então uma mudança na API quebra o build do front, e não a tela.
Mais que a busca: vários CEPs de uma vez, consenso entre o ViaCEP e a BrasilAPI, busca por rua tolerante a erro, endereço normalizado, coordenadas, distância entre CEPs, página de status das fontes, um servidor MCP para assistentes de IA e SDKs para .NET e TypeScript gerados do OpenAPI.
Testes em camadas: unitários e de integração sem rede em todo pull request, e testes de contrato semanais contra as APIs reais, que abrem uma issue quando algo muda.
Interface: um playground da API, com a escolha do endpoint, o exemplo de chamada em curl, fetch e C# e a resposta com status, tempo e JSON, e uma página de documentação gerada do OpenAPI, em tema claro, com a paleta Açaí por cima de tokens de design próprios (cores, tipografia e espaçamento).

API: .NET 10, ASP.NET Core Minimal APIs, HybridCache, Microsoft.Extensions.Http.Resilience (Polly), OpenAPI.
Front: Angular 22 (componentes standalone, signals, sem zone.js), JetBrains Mono.
Fontes de dados: ViaCEP, BrasilAPI e IBGE.
Testes: xUnit v3, NSubstitute e Shouldly na API; Vitest no front.
Entrega: Docker, GitHub Actions e deploy contínuo.

Guias: arquitetura, tratamento de erros, cache e resiliência.
Decisões de arquitetura: o porquê de cada escolha, com as alternativas consideradas.
Referência da API: rotas, parâmetros, respostas e modelos, gerada a partir do OpenAPI, com link para testar no playground.