Junction2024-Hackaconda

❔ Problem Description:

Many people feel unheard and unrepresented in the current democracy. This results in people’s opinions not being taken into consideration, a core foundation of democracies. This must change. As a solution we introduce Survall, a surveying platform that serves you!

🌍 Real-World Impact:

Survall seeks to achieve several key goals:

• Ease of use: To encourage participation in the democratic process, the barrier of entry should be reduced as much as possible. Whether as an app, website, or kiosk in public spaces, this easy-to-use tool makes it simple for anyone to participate and have their voice heard in ongoing conversations.

• Automation: By leveraging LLMs to moderate the discussions, relevant follow-up questions can be generated that take into account what the users find important by analyzing their discussions. This aims to reduce the amount of human moderation required to maintain the platform, increasing the ease of adoption from a host's perspective.

• Anonymity: Protecting users' identities is central to fostering free expression. This is achieved by dividing the authentication and the voting on two different services. The authentication service cannot influence the voting, but can verify identities. The voting service cannot read identities, nor how individual users voted.

• Transparency: The key to build trust in any system, especially a democratic one. This aspect is promoted by showing people the aggregated statistics of all discussed questions, allowing them to verify the results themselves. This allows users to build up trust in the results generated by the platform, encouraging the platforms use, and thus in extension, the participation in the democratic process.

🎥 Video Demo and Explanation

https://www.youtube.com/watch?v=UkNXdBs7zE8

💭 Future Enhancements:

As a proof of concept, Survall, has a great potential for growth:

• Moderation Tools: Creating admin pages gives administrators and moderators an easy platform to add new discussion points and approve the LLM generated follow-up question suggestions, improving the platform's usability for hosts

• Security Integration: Due to its modular setup, the Survall authentication server can be integrated with a trusted platform based on the host's needs. For example, governments could use national authentication systems to ensure only citizens participate, while private organizations could utilize public single sign-on services like GitHub.

• LLM Bias Reduction and Fine-Tuning: Large Language Models are known to be inherently biased and so care should be taken to mitigate this influencing the discussion, eroding trust, and increasing the moderation load. A fine-tuned LLM closely monitored for bias would be a step in solving this.

With Survall, making your voice heard has never been easier!

📓 Setup

The Survall application consists of three components, the client which which the users interact, the authetication server which sets up secure sessions, and the backend server which serves questions to the clients which they can answer.

The chapters below detail the setup process, split between the frontend client and the backend servers.

🔧 Frontend setup

The frontend is using Vue and Vite give the user their UI. All of the files for the frontend are in the survall_frontend directory.

Frontend preparations

Install the dependencies for the frontend using npm.

#in the ./survall_frontend directory
npm install

Furthermore, you need to set up your .env file. The .env.example has the same layout as a typical .env file. The VITE_AUTH_DOMAIN should be the address to access the authorization service. The VITE_API_DOMAIN should ebt the address to access the voting service.

If these are set you should be prepared to run the front end.

Compile and Hot-Reload for Development

The hot-reload mode allows you to access the frontend with hot reload. Any change you make to the application will be directly updated in your browser. To run the frontend in development mode, run the following command.

#in the ./survall_frontend directory
npm run dev

The output will then show on which port the frontend is running. Access the address in your browser and the frontend will be displayed.

Compile and Minify for Production

#in the ./survall_frontend directory
npm run build

The files will then be placed inside the ./survall_frontend/dist directory. The files in the directory can then be served by a HTTP engine (such as NGINX or Apache)

🔨 Backend Setup

The backend is using Flask and the OpenAI API with python. The files for the authentication server can be found in survall_auth and the file for the question server can be found in survall_backend.

Backend preparations

Optionally for both the authentication and question server a conda environment can be created. This is not nessesary for the functionality of the application.

#in the ./ root directory
conda create --name survall_backend python=3.10.0

conda activate survall_backend

Non-optionally install the dependencies for the backend using pip.

#in the ./ root directory
pip install -r requirements.txt

Furthermore, you need to set up your .env files. The .env.example has the same layout as a typical .env file. In the ./survall_auth directory, the SURVALL_SECRET_KEY should be the a random string used as a private key to encrypt the login sessions. Additionally, in the ./survall_backend directory, the OPENAI_API_KEY should be set to allow the application generate new questions dynamically.

Running the backend

To run both backend servers, navigate to their respective sub-directories in seperate CLIs and run the following commands:

#in the ./survall_auth directory
python main.py

#in the ./survall_backend directory
python main.py

After starting both servers, no additional actions are required and the application is ready to be interacted with via the frontend client.

Database

As an additional note, the current demo is setup to create a mock-database and inject it with mock-data in ./survall_backed/survall.db. After initializaiton this database persists any voting responses and newly generated questions, which will be loaded when restarting the backend. The backend is setup such that the database layer can easily be swapped with a techstack fitting the requirements of the host.