Cuidando do Meu Bairro

Versão 1.0 - dezembro de 2015.

Projeto Cuidando do Meu Bairro: abertura e geolocalização do orçamento municipal.

Acesso:

Códigos-fonte (repositórios git):

Documentação:

Histórico e versões

Este projeto teve origem no Cuidando do Meu Bairro de 2013, que buscava mapear a execução do orçamento municipal de São Paulo, não só em regiões, mas também colocando um ponto no mapa para cada despesa. Por isso o presente projeto foi apelidado de Cuidando2: uma nova interface, novos recursos e melhoras nos dados gerados pelo software.

Como os dados obtidos da prefeitura não têm as coordenadas geográficas de cada despesa (no máximo algumas tem a região a que se destinam), o ponto de partida são os endereços nos textos das descrições das despesas, que por sua vez podem ser submetidos à geocodificação em ferramentas adequadas.

A extração dos endereços a partir do texto é obtida através de expressões regulares. A geocodificação desses endereços é realizada pelas APIs OpenStreetMap-Nomination e Google-geocoding. Esse processo não é perfeito, acumula erros tanto da fase de extração como da fase de geocodificação, de modo que muitas despesas não são mapeadas, ou acabam exibidas no local errado. No Cuidando2 o processo foi aperfeiçoado para reduzir a taxa de erros.

Arquitetura

Buscando ampliar a chance de reuso do código desenvolvido e permitir um nível maior de interação com outros aplicativos, o projeto seguiu uma arquitetura de micro serviços. Ou seja, ao invés de ter um único código monolítico que implementasse todas as funcionalidades desejadas, elas foram distribuídas em pequenos módulos, cada um com uma funcionalidade específica:

Alt text

As setas avermelhadas indicam conexões em que as escritas provavelmente necessitarão de um token.

A navegação HTML é de responsabilidade do Cuidando2, implementado atualmente em cuidando.vc, que através de Ajax faz a comunicação com cada módulo, nos respectivos endpoints:

Função Responsabilidade Endpoint em uso Notas
Geolocalização Gastos Abertos site-cuidando.rhcloud.com/dados/api/v1 leitura das coordenadas
Dados de execução orçamentária Gastos Abertos demo.gastosabertos.org consulta à base de dados
Autenticação dos usuários Vira-Lata viralata-cuidando.rhcloud.com token de acesso, leitura/escrita
Comentários dos usuários Tagarela tagarela-cuidando.rhcloud.com leitura/escrita dos textos
Interface com eSIC EsicLivre cuidando.vc/esiclivre realização de pedidos de informação, leitura/escrita

Cada um desses endpoints apresenta também uma documentação mais detalhada da API quando acessado diretamente do navegador, exemplificando o uso de cada uma das operações REST disponíveis no microserviço.

Modos de operação e replicação

Conforme a finalidade, o projeto pode ser copiado e adaptado, parcial ou integralmente. O caso típico é a replicação para atuar com outros municípios, mudando apenas o escopo de dados no Gastos Abertos e adaptando-se o EsicLivre para as peculiaridades do eSIC do município.

Uma outra forma comum de replicação é a integral, quando se deseja instalar e testar localmente (o programador no seu computador) para entender melhor o funcionamento do software como um todo, ou para realizar (através de fork) adaptações maiores.

Replicando apenas o site

Na ausência de dados da cidade, operaria em modo “somente leitura”. Util para designers e trabalhos restritos ao site.

(disponível também em install-site.md).

Replicando serviços e preparo dos dados

Para reproduzir os microserviços, deve-se reproduzir também as bases de dados.

As instruções para replicação do software estão em install-services.md. A preparação dos dados pode ser realizada de três modos:

  • sandbox: base de dados mínima com dados de teste.
  • referência: dados da base em operação, em um site Cuidando já implantado.
  • novo: construir uma base de dados nova (por exemplo para um novo município). A metodologia e dicas encontram-se descritas nesta Wiki.

Replicação completa

Para replicar ambos, o site e os serviços, um script mais consido também é oferecido: src/full.sh.

CRÉDITOS E LICENÇAS

A presente documentação e todos os scripts deste módulo de documentação estão licenceados sob CC-BY 4.0.

O Cuidando2 é um projeto realizado por várias mãos,

  • Alexandre Evangelista de Souza Júnior (@alexandre)
  • Andrés M. R. Martano (@andresmrm)
  • Gisele S. Craveiro (coordenação),
  • Jutta Machado Schimdt
  • Solaine Lima
  • ... e todos os parceiros e beta-testers, que auxiliaram com sugestoes criativas e construtivas

com apoio de,

e disperso por alguns módulos, listados a seguir com indicação das respectivas licenças e equipes: