OpenVAA / voting-advice-application

An open-source platform for creating Voting Advice Applications (VAAs)
https://openvaa.org/en
GNU General Public License v3.0
10 stars 0 forks source link
strapi svelte typescript

OpenVAA Voting Advice Application

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.

💡 Features

🔨 Use cases

🥅 Project goals

🚧 Project status: Alpha

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
 The Election Compass for Young People – EE 2024 EE 2024 Election Compass
 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

🎢 Roadmap

2024 Q4 — Refactor the current codebase, especially:

2025 Q1 - Expand documentation and improve developer-friendliness

2025 Q2 — Release VAAs in the Finnish county elections

2025 Q3 — First production release

🪢 Collaborate

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.

🍭 Contributing

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.


Getting started

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 install dependencies for all modules and build all modules run:

yarn install
yarn workspaces run build

Module resolution

IDE

In 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.

NPM/Node

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).

Maintaining dependencies

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.

Troubleshooting

See Troubleshooting for solutions to some common issues.

Read more about Testing.

Find further documentation in the docs folder.