This repository has been archived, because there's now an official postal vote service.
This (unofficial) service allows users to apply for postal votes in England, Scotland and Wales.
This service is composed of a web form and back-end. The web form screens users with eligibility questions (are you registered, what country are you in) and if eligble, collects their details and signature. It sends these to the back-end which generates a completed PDF application form based on a template. If the user passes an invisible bot challenge the back-end then sends this to the applicants electoral registration office (ERO), otherwise it provides the form to the user and they send it to their ERO.
Full process flow
- Install Node.js
- Clone this repository
- Start the web app with
cd web && npm install && npm start - Start the server with
cd server && npm install && npm start
To view the web app, go to localhost:8000 in your browser.
To view email, go to localhost:8005 in your browser.
You can edit the files in server/src and web/src and your app will automatically update.
web: Website that hosts a webform for users to determine their eligibility for postal voting, collect their details, and interact with the API. Written in TypeScript, using React, govuk-react and signature_pad, bootstrapped with create-react-app.server: API for creating the PDF application, looking up user's council and emailing the form. Written in TypeScript, using Serverless, serverless-offline-ses-v2, pdf-lib and nodemailer. Uses the reCAPTCHA and WhereDoIVote APIs.
This section describes the dev and production architecture of the app.
This live site was hosted at adamjones.me/postal-vote.
The dev site was hosted at adamjones.me/postal-vote-dev.
The website is built with React as a static SPA, which is distributed to GitHub pages using GitHub actions to both the dev and prod sites automatically on commits to master. To have separate prod and dev websites there's an additional GitHub repository, postal-vote-dev, to act as the source repo for GitHub pages for the dev version. Because of limitations in GitHub pages (e.g. can't set redirect rules) we use the hash router from react-router for routing, so everything is served from /index.html. This also has good compatiblity with the form library we use, react-hook-form.
The server is effectively an AWS Lambda behind API Gateway that talks to a number of other AWS services (e.g. AWS SES for emails, AWS CloudWatch for monitoring, and AWS IAM for getting access to those resources). It talks to two external APIs: Google's reCAPTCHA for bot detection and DemocracyClub's WhereDoIVote for finding an electoral registration office for a postcode. The purpose of bot detection is to prevent someone abusing the API to send email spam to a council. The server infrastructure is managed by Serverless and defined in server/serverless.ts. We use various tools to bundle the actual server code before deploying it to Lambda, the key one being webpack. The code is automatically deployed to the dev stage on commits to master by GitHub actions, while deploying the code to prod is manual (done with cd server && npm install && npm run deploy:prod).
To configure the dev and prod versions we use environment files, which specify the stage and various settings and credentials. For example, these include whether to display the dev banner, API base URLs, and access keys for reCAPTCHA. The npm scripts in web/package.json and server/package.json are set up to select the right env file before building and deploying app. The website environment files are public, while the server ones are kept secret. Local templates are provided for ease of local development, which are automatically installed (without overwriting existing configuration if present) in the postinstall npm hook.
Regulation 6 (Electronic signatures and related certificates) of The Representation of the People (England and Wales) Regulations 2001 states "A requirement in these Regulations for an application, notice or objection to be signed is satisfied [...] where there is an electronic signature incorporated into or logically associated with a particular electronic communication, and the certification by any person of such a signature."
Regulation 51 (General requirements for applications for an absent vote) of The Representation of the People (England and Wales) Regulations 2001 sets out requirements for what the absent vote application must state and that it must be signed.
Together, these mean electoral registration offices should accept electronic signatures. From experience, all the councils I've dealt with are happy to handle e-signed applications.
The Electoral Commision also has more guidance on the regulations around requirements for postal votes.