Pular para o conteúdo principal
JC
PT | EN
← Voltar aos projetos Maanaim Entrada

Maanaim Entrada

Next.js React TypeScript Node.js PostgreSQL Fastify Zod Python

Visão Geral

O Maanaim Entrada é um sistema interno usado pela Igreja Cristã Maranata - Maanaim de Uberlândia para controlar, em tempo real, a entrada e saída de participantes em eventos presenciais. Antes do sistema, o controle era feito de forma manual, com planilhas e contagem aproximada, o que dificultava saber quantas pessoas estavam simultaneamente no local, gerava filas na portaria e criava risco de ultrapassar a capacidade.

Implementei uma aplicação web PWA onde as equipes de portaria usam celular ou tablet para ler crachás com QR code (via câmera ou leitor físico). Cada leitura registra entrada ou saída no banco em tempo real, com validação contra a lista de inscritos por evento e atualização instantânea de um painel de status. Coordenadores conseguem acompanhar a lotação atual, filtrar por igreja e gerar registros confiáveis de presença.

Atuei como desenvolvedor full-stack responsável por toda a solução: arquitetura, front-end em Next.js, API em Fastify, modelagem em PostgreSQL com Drizzle, autenticação JWT com refresh token, autorização com CASL, infraestrutura em Docker e CI/CD com GitHub Actions em VPS. Também assumi a parte de afinamento fino da UX para operadores de portaria, em especial o fluxo de leitura de crachá em dispositivos móveis.

Hoje o sistema está em produção, já foi usado em mais de 70 eventos e registrou dezenas de milhares de participantes, eliminando o controle manual e reduzindo o tempo de processamento na entrada, especialmente em seminários com grandes volumes de chegadas simultâneas.

Diferencial Principal

O diferencial do Maanaim Entrada não é ser “mais um sistema de check-in”, mas conseguir operar sob as restrições reais de um evento religioso de grande porte: internet instável, operadores com diferentes níveis de familiaridade com tecnologia, picos altos de leitura em poucos minutos e necessidade de feedback instantâneo na operação.

Tecnicamente, o ponto central é o fluxo de leitura de crachá robusto em dispositivos móveis: câmera do navegador, suporte a leitores físicos, fallback para busca manual, aceitação de múltiplos formatos de identificação e gerenciamento explícito de permissões de câmera com feedback claro ao operador. Junto disso, a atualização em tempo real via Socket.IO em um painel compartilhado por várias equipes reduz a necessidade de comunicação verbal e planilhas paralelas.

Outro diferencial é a engenharia pensada para evolução: monorepo com pnpm/Turborepo, schema de banco versionado com Drizzle, CI/CD automatizado para uma VPS simples, e um modelo de autenticação/ autorização já preparado para papéis distintos (portaria, coordenação, administração) sem complicar a operação diária.

Arquitetura

  • PWA Web App (Next.js 15 + React 19): interface principal usada em celulares, tablets e desktops; suporta instalação como PWA, modo offline básico e acesso rápido em campo.
  • Módulo de Scanner de QR Code: componente React responsável por acessar a câmera ou leitor físico, gerenciar permissões, selecionar o dispositivo de vídeo e traduzir o valor lido em um participante válido.
  • Tela de Controle de Portaria: fluxo operacional para operadores registrarem entrada/saída, visualizarem últimas leituras, erros de leitura e buscar manualmente por nome/inscrição.
  • Painel de Status do Evento: visão consolidada com contagem atual de presentes, entradas e saídas por período, capacidade e distribuição por igreja, atualizada em tempo real via WebSocket.
  • API HTTP (Fastify 5): serviços REST responsáveis por autenticação, gestão de eventos, inscrições, registros de presença, auditoria e configurações gerais.
  • Módulo de Autenticação (JWT): emissão de access e refresh tokens, armazenamento seguro em cookies HTTPOnly, renovação transparente e revogação quando necessário.
  • Camada de Autorização (CASL): definição de habilidades por papel (portaria, coordenação, admin), restringindo ações e acesso a recursos de forma granular.
  • Camada de Validação (Zod): validação de payloads de entrada/saída e respostas da API garantindo type-safety de ponta a ponta entre front-end e back-end.
  • ORM e Migrations (Drizzle + PostgreSQL): modelagem relacional de eventos, igrejas, participantes, inscrições e registros de presença, com migrations versionadas e seguras para produção.
  • WebSocket Layer (Socket.IO): canal de comunicação em tempo real para emitir atualizações de presença e status de eventos para todos os clientes conectados.
  • Cache e Sessões: suporte a sessões, cache de dados quentes e coordenação de eventos de tempo real entre múltiplas instâncias da API.
  • Infraestrutura de Deploy: containerização da aplicação, orquestração simples em VPS, gerência de processos e logs centralizados.
  • Pipeline CI/CD (GitHub Actions): automações para instalar dependências do monorepo, rodar build, executar migrations e (re)iniciar a API de forma consistente em cada deploy.

Destaques Técnicos

  • Sistema em produção com 74 eventos gerenciados e mais de 27.000 participantes cadastrados/registrados.
  • Arquitetura PWA + WebSocket pensada para picos de uso: centenas de leituras de crachá em poucos minutos na abertura de eventos.
  • Scanner de QR code iterado em mais de 20 modificações para lidar com permissão de câmera, seleção de dispositivo, comportamento inconsistente de navegadores móveis e formatos variados de crachá.
  • Fluxo de matching de crachá robusto, aceitando inscrição numérica, string ou crachaId físico, com fallback para busca manual quando necessário.
  • Back-end em Fastify 5 com foco em performance, combinado com Drizzle ORM para segurança de tipo e migrations versionadas em um banco PostgreSQL em produção.
  • Modelo de autenticação JWT com refresh tokens e cookies HTTPOnly, adequado para uso em PWA em múltiplos dispositivos.
  • Implementação de controle de acesso baseado em papéis com CASL, separando claramente operadores de portaria, coordenadores e administradores.
  • Monorepo com pnpm + Turborepo e pipeline GitHub Actions estabilizado após múltiplas iterações, orquestrando build, migrations e restart de serviços.
  • Deploy em VPS simples com Docker, mostrando uma solução pragmática de produção sem depender de orquestradores complexos.
  • Base de código em TypeScript, cobrindo front-end, back-end, contratos de API, validação e tipagem compartilhada.