Skip to main content

​
Overview

Consensus is a web-based electronic voting platform built with Node.js and Fastify. It provides a complete solution for running democratic elections with multiple voting methods, voter management, and comprehensive audit trails.

Quick Start

Get started in minutes - from account setup to casting your first vote

Installation

Deploy locally, with Docker, or try it instantly in GitHub Codespaces

Voting Systems

Learn about FPTP, STV, and Alternative Vote

Architecture

Understand the system design and patterns

​
Key features

​
Multiple voting systems

Consensus supports three different voting methods to suit various election types:
  • First Past The Post (FPTP) - Traditional single-choice voting
  • Single Transferable Vote (STV) - Proportional representation with ranked preferences
  • Alternative Vote (AV) - Ranked-choice voting for single-winner elections

​
Voter management

  • Secure voter registration with email validation
  • Admin approval workflow for voter verification
  • Guest voting support for public polls
  • GDPR-compliant account deletion

​
Election administration

  • Create and manage multiple concurrent elections
  • Scheduled start and end dates with automatic activation
  • Real-time results calculation using the Strategy pattern
  • Comprehensive audit logging with the Observer pattern
  • Tie resolution handling for close elections

​
Security and privacy

  • Bcrypt password hashing
  • Session-based authentication with secure cookies
  • Cloudflare Turnstile CAPTCHA integration
  • Ballot anonymization - votes cannot be traced to voters
  • Vote confirmation codes for voter verification

​
Architecture

Consensus is built following software engineering best practices:
The application uses Dependency Injection, Repository Pattern, Strategy Pattern for voting algorithms, and Observer Pattern for election events.

​
Technology stack

  • Backend: Node.js 22+, Fastify web framework
  • Database: SQLite with better-sqlite3
  • Templating: EJS views
  • Authentication: Session-based with @fastify/session
  • Password Security: bcrypt
  • Testing: Jest with unit and E2E tests

​
Project structure

src/
├── controllers/     # Request handlers for routes
├── services/        # Business logic layer
├── repositories/    # Data access layer
├── domain/          # Entities and enums
├── db/              # Database connection and migrations
└── web/             # Server setup, routes, and views

​
Use cases

Consensus is ideal for:
  • Student union elections
  • Club and organization voting
  • Local council elections
  • Corporate board elections
  • Community polls and surveys
  • Any democratic decision-making process

​
Getting started

1

Install Consensus

Choose your preferred installation method: local setup, Docker, or GitHub Codespaces
2

Seed the database

Populate the system with sample data to explore features
3

Create your first election

Log in as an admin and set up an election with candidates
4

Cast votes

Register voters and let them participate in elections
When you first start Consensus, default admin credentials are created automatically. Check the console output for login details.

​
What’s next?

Quick Start Guide

Follow our step-by-step guide to cast your first vote

Installation Guide

Set up Consensus in your environment

Build docs developers (and LLMs) love

Get started for freeTalk to us