VigiaSUS
Projeto de monitoramento e organização de dados públicos relacionados ao SUS, com arquitetura orientada a dados e ingestão de fontes públicas.
Visão geral
VigiaSUS é uma ferramenta de vigilância cívica em saúde pública: cruza dados abertos do governo para apontar padrões suspeitos em estabelecimentos de saúde. Nasceu como TCC de Ciência da Computação e está em desenvolvimento.
O backend, em Spring Boot, recebe o código CNES de um estabelecimento, consulta as fontes públicas, guarda o resultado em PostgreSQL, aplica sete regras de detecção e mantém um grafo de estabelecimentos no Neo4j. O frontend é uma aplicação Angular com grafo interativo, dashboard, busca e análise.
Tecnologias
- Java
- Spring Boot
- PostgreSQL
- Neo4j
- Docker
- n8n
Funcionalidades
- Análise de um estabelecimento pelo código CNES (GET /api/estabelecimentos/{codigoCnes}), que consolida cadastro, estoque de medicamentos, despesas federais e situação no TCU em uma única resposta.
- Cache em PostgreSQL com validade de 6 horas para os dados do CNES e do BNAFAR/HORUS; Portal da Transparência e TCU são sempre consultados ao vivo.
- Sete regras determinísticas de detecção, com alertas de severidade alta, média ou baixa.
- Endpoint de resumo do painel (GET /api/dashboard/stats) com totais de estabelecimentos e de alertas por severidade.
- Sincronização de cada estabelecimento analisado como nó no Neo4j, sem interromper a análise se o grafo estiver indisponível.
- Frontend Angular com landing page, dashboard, busca e página de análise, e grafo interativo com Cytoscape.js.
- Docker Compose com Neo4j, PostgreSQL, backend e frontend (Nginx), com healthchecks.
Arquitetura
O sistema tem três camadas: o frontend Angular, o backend Spring Boot e dois bancos com papéis diferentes.
- Frontend: Angular 21 com componentes standalone, Tailwind CSS 4 e Cytoscape.js, servido por Nginx, que encaminha /api/ ao backend.
- Backend: Spring Boot 3.4 com Java 17, Spring Data JPA, Spring Data Neo4j e RestClient para as APIs externas, organizado em pacotes api, client, service, domain, repository, neo4j e config.
- PostgreSQL 16: estabelecimentos, itens de estoque e alertas.
- Neo4j 5 com o plugin APOC: grafo de estabelecimentos.
O grafo exibido no frontend usa dados de exemplo e as APIs abertas do DATASUS. O backend expõe apenas os endpoints de análise e de estatísticas, então o Neo4j ainda não alimenta essa tela.
Pipeline de dados
Hoje o pipeline é sob demanda: ele roda dentro da requisição de análise, e não em segundo plano. O fluxo abaixo corresponde ao EstabelecimentoService do backend.
-
Fontes públicas
CNES e BNAFAR/HORUS (DATASUS), Portal da Transparência e certidões do TCU.
-
Spring Boot: clientes das APIs
CNES e BNAFAR só são buscados quando o cache do PostgreSQL não existe ou passou de 6 horas. Transparência e TCU são consultados a cada análise.
-
Processamento: detecção de alertas
O AlertaDetector aplica sete regras sobre os dados reunidos e classifica cada alerta por severidade.
-
PostgreSQL
Persiste o estabelecimento, o estoque e os alertas.
-
Neo4j
Grava ou atualiza o nó do estabelecimento (upsert por código CNES), sem bloquear a resposta em caso de falha.
-
Dados organizados
A API devolve uma resposta única com cadastro, estoque, alertas, despesas e situação no TCU.
Ingestão de dados
A ingestão atual é pontual: cada análise chama as APIs públicas. Não há agendamento, filas nem armazenamento do payload bruto.
- CNES (DATASUS): dados cadastrais do estabelecimento, sem autenticação.
- BNAFAR/HORUS (DATASUS): estoque de medicamentos por estabelecimento.
- Portal da Transparência: despesas federais por favorecido (CNPJ), com chave de API configurada por variável de ambiente.
- TCU (Certidões APF): consulta de inidoneidade por CNPJ.
- O cliente do SIOPS existe no código, mas ainda não participa do fluxo principal.
PostgreSQL
O PostgreSQL guarda o resultado das análises e funciona como cache dos dados do CNES e do BNAFAR/HORUS. O esquema é gerado pelo Hibernate a partir das entidades.
- Estabelecimento: cadastro normalizado do CNES, com data da última sincronização.
- ItemEstoque: medicamentos por estabelecimento, com programa de saúde, quantidade e validade.
- Alerta: severidade, título, detalhe e valor estimado, ligado ao estabelecimento.
- As sete regras cobrem: CNPJ inidôneo no TCU, repasses federais acima do esperado para o tipo de unidade, tipo de unidade sem farmácia com estoque, unidade sem atendimento SUS com estoque do SUS, cadastro CNES desatualizado há mais de um ano, medicamentos sem programa declarado e estoque acima do esperado.
Neo4j
O grafo hoje tem um único tipo de nó, Estabelecimento, com código CNES, nome, UF, município, CNPJ, atendimento SUS e total de alertas. Os relacionamentos previstos (mesmo CNPJ, localizado em, recebe medicamento) ainda não foram implementados.
n8n
O n8n está previsto como orquestrador de ingestão, mas ainda não foi implementado: não há workflows nem serviço n8n no Docker Compose. O que existe é a proposta técnica documentada no repositório, resultado de uma auditoria da arquitetura atual e de uma pesquisa de APIs públicas.
- Princípio da proposta: o n8n coleta, normaliza, deduplica, valida e grava os dados; as regras de risco, o score e os alertas continuam no Spring Boot.
- Tabelas propostas para o PostgreSQL: sources, sync_checkpoints, raw_source_data, execution_log e data_quality_issues, com idempotência por fonte, endpoint, identificador e hash.
- Um workflow por fonte (Portal da Transparência, PNCP, TCU, Receita, DATASUS), com sincronização incremental por checkpoint.
- Roadmap em 13 etapas, começando pelo conector do CNES.
-
Fontes públicas
Portal da Transparência, PNCP, TCU, CGU, Receita e DATASUS.
-
n8n Planejado
Coleta, normalização, deduplicação e validação, com checkpoints de sincronização.
-
PostgreSQL Planejado
Payload bruto e entidades normalizadas (empresas, contratos, licitações, sanções).
-
Spring Boot
Motor de análise. Hoje já executa as sete regras; indicadores e score explicável fazem parte da proposta.
-
Neo4j
Grafo de entidades e relacionamentos.
-
API REST e Angular
Dashboard, busca, grafo e alertas.
Screenshots
Desenvolvimento e desafios
O backend foi dividido por responsabilidade (controllers, clientes de API, serviços, entidades e repositórios), e todos os arquivos Java têm Javadoc. O frontend roda sozinho com dados de exemplo, o que facilita demonstrar o projeto sem subir os bancos.
A documentação fica na pasta docs do repositório, organizada por área: API, arquitetura, backend, frontend, infraestrutura, n8n e TCC.
Cruzar fontes com identificadores e formatos diferentes
Desafio
Cada fonte pública identifica o estabelecimento à sua maneira: o CNES usa o código CNES, enquanto a Transparência e o TCU são consultados por CNPJ, e as datas chegam em formatos distintos.
Solução
O código CNES é o ponto de entrada, e o CNPJ retornado por ele alimenta as consultas seguintes. O detector de alertas aceita datas nos formatos yyyy-MM-dd, dd/MM/yyyy e yyyyMMdd.
Continuar funcionando quando uma fonte ou o grafo falha
Desafio
As APIs públicas ficam indisponíveis com frequência, e o Neo4j é uma dependência auxiliar da análise.
Solução
Se a API do CNES falhar e o estabelecimento já estiver em cache, o cache é usado mesmo expirado. Uma consulta ao TCU indisponível vira um estado "indisponível" na resposta, e a gravação no Neo4j roda dentro de try/catch e apenas registra um aviso.
Não transformar heurística em acusação
Desafio
Alertas baseados em regras podem ser lidos como prova de irregularidade, o que não é o caso.
Solução
Os limiares por tipo de unidade ficam explícitos no código, cada alerta traz título e detalhe, e o projeto declara que os padrões identificados indicam relações entre entidades e não constituem prova.
Conclusão
O VigiaSUS reúne, em um único projeto, integração com APIs públicas, persistência relacional, grafo e uma interface interativa. O núcleo (consulta, cache, sete regras e resposta consolidada) já funciona de ponta a ponta. A ingestão automatizada via n8n, mais cruzamentos entre bases e algoritmos de detecção de comunidades no Neo4j seguem como próximos passos.
Projetos relacionados
FinTrack
Plataforma de gestão financeira pessoal inspirada em aplicações de organização financeira, desenvolvida com foco em arquitetura, experiência do usuário e evolução para recursos de Open Finance.
FutureData
Sistema de gestão para assistência técnica: ordens de serviço de ponta a ponta, portal do cliente e atendimento automatizado por WhatsApp com IA.