🌍 Visão Geral
A plataforma busca melhorar a comunicação entre o cidadão e a gestão responsável, reduzindo a dispersão de informações e apoiando a tomada de decisão com dados operacionais em tempo real.
🎯 O Problema Central
A ausência de uma plataforma centralizada para registro, rastreabilidade e priorização de demandas urbanas dificulta a tomada de decisão por parte da gestão e reduz a eficiência no atendimento à população.
🏛️ Alinhamento com Políticas Públicas
A proposta dialoga com as diretrizes de transformação digital no setor público, em especial a Lei nº 14.129/2021 (Lei do Governo Digital), estabelecendo princípios como:
- Eficiência administrativa e desburocratização;
- Transparência;
- Uso de soluções digitais para melhorar os serviços públicos.
Relaciona-se também com a Estratégia Nacional de Governo Digital, incentivando o uso de tecnologias para melhorar a relação entre o governo e o cidadão.
✅ Objetivos Específicos
- Centralizar o registro de demandas urbanas.
- Permitir o acompanhamento claro das solicitações.
- Oferecer visibilidade operacional para os gestores.
- Aumentar a transparência no atendimento à população.
- Organizar o fluxo de demandas com base na prioridade, data e status.
👥 Perfis de Usuário
🧑💼 Cidadão
Responsável por:
🏢 Gestor Público
Responsável por:
🚀 Funcionalidades do MVP
📊 Indicadores Operacionais (Gestão)
O painel administrativo acompanha, no mínimo:
- Volume: Quantidade total de demandas registradas;
- Distribuição: Demandas por categoria;
- Geografia: Demandas por região.
🖥️ Telas do Projeto
🥇 Prioridade Alta
| Tela | Descrição |
|---|
| Página Inicial (Cidadão) | Destaque para o fluxo do cidadão, listagem de demandas, sistema de filtros e acesso à área do gestor. |
| Página Inicial (Gestor) | Listagem geral, filtros avançados, acesso ao painel administrativo e ações de edição/atualização de status. |
| Formulário de Demanda | Coleta de dados da ocorrência (local, descrição, categoria, imagem, etc.). |
| Detalhes da Demanda | Visualização completa de todos os dados de um registro específico. |
| Painel Administrativo | Dashboard focado em métricas operacionais para os gestores. |
| Sistema de Filtros | Combinação de filtros por categoria, região, status e prioridade. |
🥈 Prioridade Secundária
| Tela | Descrição |
|---|
| Login e Cadastro | Acesso segmentado (Sou cidadão ou Sou gestor) com email e senha. |
⚙️ Stack Tecnológica
| Camada | Tecnologias Utilizadas |
|---|
| Front-end | TypeScript, Next.js, Chakra UI, Tailwind CSS, Zustand |
| Back-end & Integração | Node.js, Express, Prisma ORM |
| Autenticação & Dados | JWT, Cookies, Redis, Cron Jobs, API Fake |
📡 Documentação da API
A plataforma RESOLVE utiliza um API Gateway como ponto central de entrada (Porta 8080), que gerencia o tráfego e a segurança entre o frontend e os microsserviços internos.
- Ponto Único de Entrada:
http://localhost:8080
- Padronização: Todas as trocas de dados são realizadas via JSON.
| Serviço | Método | Endpoint | Descrição |
|---|
| Monitoramento | GET | /health | Verifica a saúde e disponibilidade dos serviços. |
| Autenticação | POST | /auth/login | Autentica o usuário e gera o token de acesso (JWT). |
| Demandas | GET | /demands | Lista todas as demandas (com suporte a filtros avançados). |
| Demandas | POST | /demands | Registra uma nova ocorrência urbana no sistema. |
| Métricas | GET | /metrics | Retorna KPIs e indicadores operacionais para o gestor. |
Arquitetura Avançada: Concorrência, Paralelismo e Otimização
A arquitetura da plataforma RESOLVE foi desenhada para operar como um sistema distribuído de alta disponibilidade e resiliência. Abaixo estão mapeados os padrões implementados na infraestrutura e no código:
Concorrência (Event-Driven & Background Jobs)
A aplicação tira proveito do Event Loop do Node.js e de uma arquitetura orientada a eventos para não bloquear a thread principal durante processamentos pesados:
- Mensageria e Filas (Redis): O
demand-service não trava a requisição aguardando a atualização das métricas. Ao alterar um status, ele delega a tarefa disparando eventos de forma assíncrona (lPush na fila smartcity:event-queue e publish no canal smartcity:denuncia-status) e devolve a resposta imediatamente ao gestor.
- Workers em Segundo Plano: O
metrics-service possui workers dedicados (startEventSubscriber e startQueueWorker) que escutam ativamente o Redis. Eles processam as atualizações de KPIs em background, lidando com falhas através de políticas de retry (withRetry).
- Agregação Assíncrona (
Promise.all): No cálculo de métricas, múltiplas consultas de leitura (total, categorias, regiões e status) são disparadas simultaneamente. O Node.js gerencia essas requisições concorrentemente, reduzindo o tempo de carregamento do dashboard.
- Timeout no Publish do Redis (
Promise.race): Ao publicar um evento de mudança de status no Redis, o demand-service disputa a operação contra um temporizador de 3 segundos. Caso o Redis demore ou falhe, a corrida rejeita a promise e loga o erro — sem travar a thread que já devolveu a resposta HTTP ao gestor.
- Controle de Concorrência com Transações (
prisma.$transaction): As operações de atualização de status e de prioridade de uma demanda são executadas dentro de uma transação atômica. A gravação na tabela denuncias e a criação do registro em historicos acontecem como uma unidade indivisível — se qualquer etapa falhar, tudo é revertido, prevenindo inconsistências quando múltiplas requisições concorrentes chegam ao mesmo tempo.
- Limite de Reconexão do Redis com Backoff Progressivo: A configuração do cliente Redis define uma estratégia de reconexão com no máximo 3 tentativas, aplicando um atraso progressivo entre elas (
retries * 200ms — ou seja, 200ms, 400ms e 600ms). Após esgotar as tentativas, a conexão é encerrada em vez de tentar indefinidamente. Isso evita rajadas de reconexão que sobrecarregariam o servidor Redis em caso de falha.
- Nível de Isolamento de Transação (Read Committed) Por padrão, as transações do Prisma (prisma.$transaction) no PostgreSQL operam sob o nível de isolamento Read Committed. Isso garante concorrência segura que se, por exemplo, dois gestores tentarem atualizar o status da mesma denúncia ao mesmo tempo, o banco garante que a segunda transação só lerá os dados após a primeira dar commit, evitando o Dirty Reads.
- Durante a execução de um prisma.denuncia.update dentro do bloco de transação, o PostgreSQL aplica um bloqueio exclusivo de linha. Isso impede que requisições concorrentes alterem o registro da denúncia no exato milissegundo em que o histórico está sendo gerado, blindando o sistema contra Race Conditions.
Paralelismo (Processamento Distribuído)
O paralelismo real do sistema é alcançado através da sua infraestrutura, tirando proveito de múltiplos recursos computacionais:
- Ecossistema de Microsserviços (Docker): O
api-gateway (porta 8080), auth-service (3001), demand-service (3002) e metrics-service (3003) operam como processos independentes. Eles rodam simultaneamente, dividindo a carga de CPU do servidor host.
- Execução no Banco de Dados: Quando o back-end dispara as requisições concorrentes de métricas, o PostgreSQL executa essas queries de leitura pesada paralelamente em seus próprios processos internos.
- Listagens Paginadas com Contagem Paralela (
Promise.all): Nas funções listDenunciasByCidadao e listAllDenuncias do demand-service, a contagem total de registros (COUNT) e a busca paginada (findMany) são disparadas simultaneamente com Promise.all. O banco executa ambas as queries em paralelo, reduzindo o tempo de resposta de cada listagem em comparação com execução sequencial.
- Aquecimento de Serviços Não-Bloqueante (
Promise.allSettled): O api-gateway expõe um endpoint /warmup que dispara pings simultâneos para os três microsserviços sem aguardar nenhuma resposta (fire-and-forget). O uso de Promise.allSettled garante que a falha de um serviço não impeça o retorno imediato do gateway — o cliente recebe 200 enquanto os processos são acordados em paralelo.
- Workers Paralelos do PostgreSQL: O PostgreSQL do Supabase é configurado para alocar múltiplos Background Workers para executar varreduras e agregações paralelas na CPU do servidor de banco de dados. Quando o metrics-service dispara as queries analíticas, o banco pode dividir a tabela denuncias em blocos e processar a contagem por categorias em paralelo, utilizando múltiplos núcleos de processamento do servidor.
Otimização, Resiliência e Segurança
Técnicas rigorosas foram implementadas para proteger a memória, o tempo de resposta e a estabilidade do servidor:
- Camada de Cache (Redis): KPIs processados são cacheados com um Time To Live (TTL) de 5 minutos. Isso blinda o banco de dados contra centenas de consultas analíticas repetitivas quando múltiplos gestores acessam o painel ao mesmo tempo.
- Rate Limiting (API Gateway): O proxy de entrada (porta 8080) possui um limitador estrito de 200 requisições a cada 15 minutos por IP. Essa barreira previne que picos de uso repentinos ou ataques de negação de serviço (DDoS) saturem os microsserviços.
- Mecanismos de Fail-Safe e Timeout: A renovação do cache de métricas utiliza um
Promise.race com um limite de 5 segundos. Isso garante que a aplicação rejeite a operação rapidamente caso o banco de dados trave, evitando que o sistema inteiro congele esperando uma resposta infinita.
- Health Checks Ativos: O Gateway possui uma rota
/health que realiza chamadas concorrentes (Promise.all) para validar o status de todos os microsserviços, reportando a integridade da infraestrutura em tempo real.
- Índices no Banco de Dados: O schema Prisma do
demand-service define índices explícitos (@@index) nos campos categoria, status, prioridade e regiao da tabela denuncias. Isso acelera diretamente as queries de filtragem do painel do gestor, evitando varreduras completas na tabela a cada requisição.
- Paginação com
skip/limit: Todas as listagens de demandas utilizam paginação (skip + take no Prisma), garantindo que apenas o subconjunto de dados solicitado seja carregado na memória e trafegado entre banco e serviço — sem trazer registros desnecessários independentemente do volume total de demandas.
upsert Atômico para Resolução de Identidade: As funções resolveCidadaoId e resolveGestorId utilizam prisma.upsert ao invés de SELECT + INSERT em operações separadas. Isso elimina a race condition onde duas requisições simultâneas do mesmo usuário tentariam inserir o mesmo registro no banco, causando violação de chave única.- Atualização Local sem Re-fetch Total: Ao alterar o status ou a prioridade de uma demanda, a interface atualiza apenas o registro afetado no estado local (Zustand) com base na resposta da API, sem disparar um novo carregamento de todas as demandas. Isso reduz o número de requisições desnecessárias e mantém a interface responsiva.
- Persistência Seletiva no Frontend (): O estado global do Zustand utiliza a opção para persistir no apenas os dados essenciais de sessão (, , , ). Dados volumosos e potencialmente desatualizados como , e são , evitando leitura de cache obsoleto e consumo desnecessário de armazenamento local.
🔗 Links Úteis
🚀 Como Rodar
Frontend
cd Smart-City
npm install
npm run dev
Disponível em http://localhost:3000
Backend e Banco de Dados
cd backend
copy .env.example .env.local
docker compose --env-file .env.local up -d --build
docker compose --env-file .env.local exec auth-service npx prisma generate
docker compose --env-file .env.local exec auth-service npx prisma migrate deploy
docker compose --env-file .env.local exec demand-service npx prisma generate
docker compose --env-file .env.local exec demand-service npx prisma migrate deploy
Disponível em http://localhost:8080
Ambiente reprodutível com Nix (opcional)
O repositório traz um flake.nix para quem usa Nix/NixOS. Ele fixa as versões
das ferramentas, então não é preciso instalar Node na mão nem acertar a
versão certa:
nix develop # Node 22 + Playwright (frontend e e2e)
nix develop .#backend # Postgres 16 + Redis + Node, para rodar os serviços sem Docker
Dois detalhes que o flake resolve e valem para todo mundo saber:
- Node: os Dockerfiles do backend fixam
node:20-alpine, mas o Node 20 saiu
de suporte (EOL em 2026-04-30). O flake usa Node 22 LTS, que atende o
requisito do Next 16 (>= 20.9). O e2e/README.md ainda diz "Node 18+" —
isso está desatualizado.
- Playwright: o pacote npm exige um build exato de navegador, então
e2e/package.json fixa @playwright/test na mesma versão empacotada pelo
nixpkgs (playwright-driver). No shell do Nix os navegadores já vêm prontos
(PLAYWRIGHT_BROWSERS_PATH), dispensando o npx playwright install — que,
sem isso, baixa um binário dinâmico que não roda no NixOS. Se as versões
saírem de sincronia, o shell avisa ao ser aberto.
Quem não usa Nix segue normalmente com Node 22 instalado pelo gerenciador de
sua preferência — nada no projeto passou a depender do Nix.
👩💻 Equipe de Desenvolvimento
- Beatriz Paredes
- Cecília Medeiros
- Isabella Batista
- Jose Leandro De Morais
- Gabriel Souza
