inklabs/vote

Demo application that implements Ranked Choice Voting in Go using a CQRS architecture

Ranked Choice Voting - Go CQRS

This is a demo application that implements Ranked Choice Voting, also known as Instant Runoff Voting, where voters rank candidates in order of preference, and a single winner is selected.

The sole purpose of this project is to demonstrate the capabilities of the (currently private) Go CQRS application framework.

Design

The architecture leverages Command Query Responsibility Segregation (CQRS). Business logic can be written in Commands, Queries, or Listeners.

Actions

Actions are Commands that modify state, or Queries that retrieve data. Commands can be asynchronously processed, with the status and log messages available for later retrieval.

• Commands
  • CommenceElection
  • MakeProposal
  • CastVote
• AsyncCommands
  • CloseElectionByOwner
• Queries
  • ListOpenElections
  • ListProposals
  • GetProposalDetails
  • GetElectionResults

Events

Events are used to remove temporal coupling between modules with separate responsibilities. Commands raise events and Listeners subscribe to them asynchronously.

• Events
  • ElectionHasCommenced
  • ProposalWasMade
  • VoteWasCast
  • ElectionWasClosedByOwner
  • ElectionWinnerWasSelected

Listeners

Listeners subscribe to Events and execute code asynchronously.

• ElectionWinnerVoterNotification
  • TODO: notify voters via SMS, Slack, or email
• ElectionWinnerMediaNotification
  • TODO: send press release email

Code Generation

The underlying Go CQRS application framework utilizes code generation to build the APIs and SDKs to execute this application. The Vote App uses go:generate directives to parse the domain and build various APIs. The generated output is not yet included in this project.

APIs

APIs are exposed through HTTP, gRPC, and CLI tooling.

Examples:

• CLI Examples
• HTTP API Examples
  • HTTP Schema Examples

SDK

SDKs are auto-generated leveraging the gRPC clients.

• Go
• Python

Test

go generate .
go test ./...

Run

go run cmd/httpapi/main.go
go run cmd/grpcapi/main.go
go run cmd/cli-local/main.go --help

Test Python

go run cmd/grpcapi/main.go
python3 -m doctest python_test.py