A software framework for creating Voting Advice Applications (VAA), also known as Election Compasses. In short, VAAs are applications that help voters find candidates or parties in elections based on how much they agree about political or value statements. They’re currently most popular in the Nordic countries, the Netherlands and the German-speaking part of Europe.
This repository is a monorepo containing the frontend and backend, as well as other modules. In addition to the voters’ frontend, there is a similar UI for candidates that they can use to input their answers.
The project is coordinated by the Finnish non-profit association OpenVAA and funded by Sitra – the Finnish innovation fund.
- 🔎 Transparent
- 💸 Free to use
- 🌍 Fully localisable
- 🗳 Use in any election
- 🤲 Accessible
- 🧩 Modular, customisable and extendable
- 🕶️ Privacy-preserving
- 🎓 Informed by research and research-friendly
- Collect candidates’ or parties’ answers and publish a VAA for voters
- Use previously collected answers to publish a VAA
- Rapidly prototype new VAA designs or functions
- Collect VAA usage data for research
- Offer a fully transparent alternative to closed-source VAAs
- Make it easier to develop new VAA features and designs
- Expand the use of VAAs to elections where they’re not currently used
- Facilitate research on VAAs
To stay up to speed, please ⭐️ star the repo or 📧 subscribe to our newsletter.
The project is currently in an alpha phase with the onus being on refactoring the existing code base for greater robustness and a better developer experience, as well as implementing some missing features.
We released two pilot VAAs for the 2024 EU Elections, which you can try out to see the software in action.
| Video-based VAA | Traditional VAA |
|---|---|
 |
 |
| Finnish, Swedish and English | Finnish only |
| Features custom video content | Select questions by theme |
| User survey and extended analytics | No analytics |
| Data stored in Strapi backend | Data stored in local JSON files |
| Postgres server and two Docker containers running on Render | Single Docker container running on Render |
| nuortenvaalikone.openvaa.org | vaalikone.openvaa.org |
2024 Q3 — Refactor the current codebase, especially:
- Abstract the frontend–backend connection into a
dataProviderAPI enabling arbitrary backend implementations - Implement a
vaa-datadata model for VAA and election data - Convert
vaa-data,vaa-matchingandvaa-filterspseudo-modules into independent modules. These handle together the application logic and are independent of the frontend and backend implementations - Implement the most crucial missing features, such as constituency selection and support for multiple simultaneous elections
- Expand unit and end-to-end test coverage
2024 Q4 — Release the first full VAA to the public, including the interface for the candidates to input their answers (Tampere youth council elections)
- Create a project site with documentation, which is currently spread between the
/docsfolder and in-codeTSDoccomments - Create a research-backed methodological guide to supplement the technical documentation
- Build application manager UI
- Enable plugins or easier customisation of pages and main components
2025 Q2 — Release VAAs in the Finnish county elections
2025 Q3 — First production release
In addition to developers and designers willing to contribute to the codebase (see below), we’re also looking for researchers to collaborate with and organisations willing to publish their own VAAs. Reach us at [email protected] if you’re interested.
We’re very happy to accept any help in coding, design, testing, translating and so on. If you want to help, drop a line at [email protected].
See the contribution guide for further info about contributing to the project.
You can run the whole application in a single Docker image, or run the frontend or backend separately depending on your preferences. Using the Docker image is recommended and the quickest way to set up the application.
- See the Docker setup guide for running the whole application.
- See the frontend Readme for instructions on running the frontend individually.
- See the backend Readme for instructions on running the backend individually.
The project is a monorepo and it consists of several yarn workspaces (each is a separate NPM module):
- vaa-shared
- vaa-strapi
- vaa-frontend
All workspaces share a single yarn.lock file located at the project root but contain their own tsconfig.json and package.json files.
The workspaces can be addressed by yarn from any directory as follows:
yarn workspace [module-name] [script-name].f.e. the shared module can be build by running:
yarn workspace vaa-shared buildIn order to resolve cross imports between the monorepo modules Visual Code Studio uses TypeScript references, which are defined in the tsconfig.json files of the corresponding modules.
In other words, you DO NOT have to build the dependee modules in order for the IDE to resolve their imports within a dependent module or to pick up changes you make in the dependee’s .ts sources.
When you use Yarn and during runtime NPM/Node module resolution mechanism is used instead. It relies on various pointers defined in package.json files of the corresponding modules (e.g. main, module or exports). These pointers usually refer to build/dist directory containing already transpiled TS sources of a given module (.js files). This directory subsequently gets symlinked by yarn install in a node_modules directory of a dependent module.
In other words, you DO have to build the dependee modules prior to running a dependent module or using Yarn on it, so that NPM/Node can find the transpiled .js sources and pick up changes you make in the original .ts code (see also on hot module reloading support or a lack of such here).
The project uses Playwright for E2E testing. The tests rely on generated data which the local PosgresDB is being seeded with.
To run the E2E tests start all the services locally:
yarn dev... and then:
yarn playwright install
yarn testIf you encounter any unexpected issues with the E2E tests, make sure to bring down the Docker stack properly to reseed the DB with the original mock data (more on mock data here).
To bring down the Docker stack properly (delete all containers, images and named volumes which include backend DB volume with potentially seeded mock data) run:
yarn dev:downThe project uses Dependabot to maintain security updates for its dependencies. Dependabot will create automated pull requests monthly to fix potential known security issues in application dependencies.
See Troubleshooting for solutions to some common issues.
You can also find further documentation in the docs folder.