RESOLVE

---

🌍 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:

• Registrar demandas urbanas.
• Visualizar a lista de demandas.
• Consultar detalhes das solicitações.
• Acompanhar o status das solicitações.

🏢 Gestor Público

Responsável por:

• Visualizar demandas registradas de forma global.
• Filtrar solicitações e atualizar o status manualmente.
• Acessar o painel administrativo (Dashboard).
• Acompanhar indicadores operacionais cruciais.

---

🚀 Funcionalidades do MVP

• Cadastro e autenticação de usuários;
• Criação e listagem de demandas urbanas;
• Visualização detalhada de cada demanda;
• Sistema de filtros avançados (prioridade, categoria, região e status);
• Atualização manual de status (exclusivo para gestores);
• Visualizações em formato de Lista;
• Painel administrativo para gestores (Métricas e KPIs);
• Integração com API para simulação de dados.

---

📊 Indicadores Operacionais (Gestão)

O painel administrativo acompanha, no mínimo:

1. Volume: Quantidade total de demandas registradas;
2. Distribuição: Demandas por categoria;
3. 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

Ferramenta Utilizada	Material	Links
Figma	Protótipo	Acesse aqui
Postman	Documentação Pública da API	Acesse aqui
BRmodelo	Modelagem conceitual - Auth	Acesse aqui
BRmodelo	Modelagem lógica - Auth	Acesse aqui
BRmodelo	Modelagem conceitual - Demand	Acesse aqui
BRmodelo	Modelagem lógica - Demand	Acesse aqui
LucidChart	Desenho da Arquitetura em Microsserviços	Acesse aqui

---

🚀 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