ElectionGuard SDK Ballot Marking Device Reference Implementation

The ElectionGuard Reference Ballot Marking Device (BMD) is a fully functional implementation of a BMD built in ReactJS. It uses the Gamepad API to support a physically-connected Xbox Adaptive Controller for navigating ballots with the A/B buttons, D-pad, or other devices plugged into the XAC's connection ports.

The BMD was designed under the supervision of the Center for Civic Design as an update of the Anywhere Ballot and built by the team at VotingWorks. It runs locally in a web browser (Chrome or Edge Beta). A sample set of ballots (in json format) is available in both the /public/data/ and /src/data directories that showcases a variety of contests and referenda use cases.

By default, when a ballot is printed, the BMD also generates a static tracking ID. End-to-end verifiable elections create tracking IDs generated when the ballot is encrypted. It's used by voters to check that their vote was included in the final tally when all the artifacts of an end-to-end verifiable election are published. When you have built working encryption capability (using the C Implementation), the election.json configuration file can be modified to retrieve the tracking ID by updating this code block.

Install and Run App Locally

This assumes you have git and yarn installed.

1. Clone the repo:

   git clone [email protected]:microsoft/ElectionGuard-SDK-Ballot-Marking-Device-Reference-Implementation.git
   

2. Navigate to the top level of the cloned directory

   cd ElectionGuard-SDK-Ballot-Marking-Device-Reference-Implementation
   

3. Install dependencies:

   yarn install
   

4. Run the app in your local browser:

   yarn start
   

Local Development Scripts

• yarn install - Install the dependencies.
• yarn start - Run the app locally.
• yarn test- Run tests in interactive mode.
• yarn test:coverage - Run all tests and update test coverage report.

See package.json for all available scripts.

Technical Implementation

This project was bootstrapped with Create React App for TypeScript. It uses Styled Components for styles (and some css files too). ESLint is configured to lint Javascript and TypeScript files, and format code using Prettier. stylelint is used to lint modern css. Jest, dom-testing-library, react-testing-library, and Cypress are used to test components and end-to-end user flows.