Knoxis

O problema e as restrições

O Knoxis existe para conduzir um ritual específico e de alto risco: uma igreja elegendo presbíteros e diáconos por voto secreto, do jeito que igrejas presbiterianas fazem há gerações, com cédula única e múltiplos escrutínios de contagem até que toda vaga seja preenchida por maioria de verdade. O cliente queria esse ritual num computador, e a exigência que moldou tudo o resto foi que “secreto” precisava significar algo mais forte que “prometemos não olhar”.

Essa é uma restrição mais afiada do que parece. Um formulário web típico pode logar toda requisição, guardar toda linha do banco para sempre, e ninguém fora do time nunca percebe. O custo desse descuido normalmente é uma query lenta ou uma tabela um pouco inchada. Aqui, o mesmo descuido (guardar quem votou ao lado do que foi votado, mesmo que brevemente, mesmo que “só para debugar”) é a única falha que tornaria o sistema inteiro inútil para uma igreja que existe justamente porque não confia em processo informal e sem documentação para lidar com algo tão sensível.

A segunda restrição era a forma da própria governança eclesiástica, que não se encaixa numa lista plana de “usuários” intercambiáveis. Um presbitério tem múltiplos cargos em eleição ao mesmo tempo, cada um com seu próprio número de vagas; a regra para vencer é maioria simples dos votos, o que rotineiramente exige mais de um escrutínio quando ninguém passa de 50%; e o último escrutínio pode virar “quem tiver mais votos vence”, especificamente para garantir que o processo de fato termine. Nada disso é exótico, mas tudo precisava ser representado fielmente: um cálculo de “maioria” errado por uma vaga, ou um sistema incapaz de levar de forma limpa os mesmos candidatos remanescentes para um segundo escrutínio, minaria a mesma confiança que o desenho de sigilo estava protegendo.

A terceira restrição foi disciplina de escopo contra pressão real para adicionar coisa. O cliente estava aberto a infraestrutura como Redis se o sistema precisasse (uma notificação push em tempo real, uma fila de job em background, um cache distribuído), e a resposta honesta, conferida caso a caso, foi que na escala esperada de uma eleição de uma congregação só, nenhuma dessas necessidades era real ainda. Adicionar Redis “por garantia” teria significado uma quarta peça móvel em produção, mais superfície de ataque, e mais coisa para raciocinar num sistema cuja promessa central é confiabilidade pela simplicidade; throughput bruto nunca foi o ponto.

A quarta restrição era que um CPF (o identificador nacional usado para conferir um eleitor contra o rol de membros da igreja) é em si dado pessoal sensível pela lei brasileira, e a única necessidade real do sistema para ele é uma checagem de sim-ou-não na entrada. Qualquer coisa além desse mínimo, inclusive a tentação de simplesmente guardá-lo “para o caso de ser útil depois”, era um passivo sem funcionalidade correspondente para justificá-lo.

A última restrição foi multi-tenancy desde o dia zero: uma plataforma onde qualquer número de congregações conduz suas próprias eleições, completamente isoladas umas das outras, sem cada uma precisar do próprio banco, do próprio deploy, ou do próprio histórico de migration para manter sincronizado.

Arquitetura

Um eleitor abre o fluxo de votação e se identifica com um CPF. O backend normaliza, valida os dígitos verificadores, calcula um hash HMAC com chave e busca contra o rol de eleitores da igreja para aquela eleição específica: uma única comparação indexada, na mesma velocidade de comparar texto puro, exceto que o CPF em claro nunca é o que está sentado no banco. Uma correspondência emite um ballot_session: um token de curta duração, devolvido num cookie httpOnly, que representa “essa pessoa específica agora pode votar nessa cédula específica” sem ainda dizer nada sobre o que ela vai escolher.

Enviar a cédula é onde a promessa real da arquitetura é cumprida. Numa única transação de banco, o backend trava a linha da sessão de cédula, confirma que ela ainda não foi usada e não expirou, marca como usada, e então escreve em duas tabelas separadas: voter_attendance registra que esse eleitor participou desse escrutínio (tem um ID de eleitor, porque saber o comparecimento e impedir voto duplo exigem isso), e votes registra as escolhas de verdade, para cada cargo aberto, sem ID de eleitor, sem CPF, sem nenhuma referência de volta à sessão de cédula. Não existe chave estrangeira que uma consulta possa seguir de uma tabela para a outra. O timestamp do voto em si é truncado ao minuto, o que silenciosamente reduz o valor de tentar correlacionar “quem estava ativo às 19h42m03s” com “o que foi registrado às 19h42m03s”, é uma defesa imperfeita numa eleição minúscula com intervalos longos entre eleitores, mas real na escala em que esse sistema de fato roda.

Toda tabela dessas, e toda tabela do sistema, carrega um organization_id: a fronteira que mantém a eleição de uma igreja completamente invisível para outra. Essa fronteira é imposta por um mixin que todo viewset de API do sistema é obrigado a herdar, que filtra toda leitura pela organização logada e injeta o tenant em silêncio em toda escrita, ignorando qualquer coisa que um cliente tente mandar em vez disso, sem banco separado nem política de row-level security do Postgres envolvidos. Como essa garantia vive no código da aplicação em vez de no próprio motor de banco, ela é reforçada por uma segunda garantia no nível de teste: um único teste de regressão percorre todo viewset registrado no projeto e derruba a build se algum deles tiver sido escrito sem o mixin.

Enquanto um escrutínio está aberto, o organizador acompanha uma contagem ao vivo numa tela separada, só para admin (nunca visível para eleitores), atualizada consultando o backend a cada três segundos em vez de qualquer mecanismo de push. Um ETag construído a partir do ID do escrutínio, seu status e a contagem corrente de votos faz uma contagem sem mudança custar quase nada ao servidor responder: um 304 Not Modified e nenhuma consulta. Quando o escrutínio fecha, a mesma consulta agregada determina quem passou de maioria real dos votos, e quem ficar sem vaga segue automaticamente direto para o próximo escrutínio, com os mesmos candidatos e as mesmas vagas abertas, até toda posição ser preenchida, no último escrutínio, por quem recebeu mais votos, exatamente como as próprias regras impressas da igreja exigem.