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.
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.
2024 Q4 — Refactor the current codebase, especially:
dataProvider
API enabling arbitrary backend implementations2025 Q1 - Expand documentation and improve developer-friendliness
/docs
folder and in-code TSDoc
comments2025 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 info@openvaa.org 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 info@openvaa.org.
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.
The project is a monorepo and it consists of several yarn workspaces (each is a separate NPM module). See the READMEs in each for more information.
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 @openvaa/app-shared build
In order to resolve cross import
s 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 import
s 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 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.
Read more about Testing.
Find further documentation in the docs folder.