Project Info
Inspiration
In 2024, during the General Election, thousands of Santa Clara County residents (including us!) received a ballot and the Santa Clara County Voter Information Guide—a 44-page long rundown of each candidate and ballot measure. Critical to making informed voting decisions, this guide presents lengthy, densely worded explanations of ballot initiatives—many of which have significant implications for local communities. As students who are now voters, we have heard from friends and other adults that their struggles with the voter guide can lead to confusion or distress, a lack of clarity on what to vote for, and decreased enthusiasm for civic engagement and the election process. Furthermore, the phenomenon of “undervoting” can be exacerbated by this confusion. In the 2024 General Election, counties in the United States had up to 9% undervoting on various propositions, from tiny Alpine County in California to the much more sizable Harris County in Texas. In each of these cases, the outcomes of various races may have changed had there been fewer ‘undervoters’. For this project, we have decided to begin our focus right here in Santa Clara County, as we already have a young and inexperienced (and frankly, impatient) voter base yet to be tapped. We also zeroed in on one piece of voting often neglected by ‘undervoters’: ballot measures. These pieces of legislation are key sticking points for voters, and their complexity often leads to disengagement—yet they shape policies that directly impact communities. By addressing this critical gap, we aim to empower voters with the knowledge and confidence needed to navigate ballot measures effectively, recognizing that their participation in these decisions is fundamental to a truly representative democracy.
What it does
VoteSmart is an AI companion built to understand a user’s political leanings and assist in the voting process. Our mission is to increase voter awareness with a transparent and comprehensive AI that eliminates the verbose terminology often found in a Voter Handbook. By leveraging AI to cultivate a culture of deeper engagement in the democratic process, we aim to empower voters with greater autonomy while restoring trust among those disillusioned by an often needlessly complex voting system. Once their profile is saved with their political preferences, a user can immediately view their customized ballot, featuring propositions relevant to their city. Most importantly, artificial intelligence tailors ballot measure descriptions to their political leanings, offering a straightforward Yes or No voting recommendation. No more falling prey to circular language, dense jargon, or skipping votes out of frustration. VoteSmart encourages participation while giving users the autonomy to learn more about what their vote really means.
How we built it
We used TreeHacks' website starter repo as a lifting-off point, then added our own functionality and style. We recognized immediately that a website would be the most accessible manner to reach our users and create an effective tool to serve them. We used Windsurf to fill gaps in our technical skills, and develop a functional base we could build off of. We also drew inspiration from the Depolarizing GPT framework, which seeks to reduce political polarization by offering a multi-perspective approach to political issues.
Challenges we ran into
As first time hackathon attendees, building our own application (from scratch!) was extremely intimidating, and we had to teach ourselves many complex coding concepts as we built our site. Using Windsurf was also a learning curve, as we discovered how to tailor our prompts and find the most efficient ways to use the program, while still incorporating our own technical skills and stylistic choices.
What we learned
We now know how to create a website from scratch, run it locally with Flask, and iteratively improve our UI to provide the best user experience. We also learned about NLTK for language processing, as well as how to use Github to streamline our code commits.
What's next
Our plan is to expand our application to counties across the country, include political candidates in addition to propositions, and offer a wider variety of languages. We currently have a version of VoteSmart that uses OpenAI to more comprehensively offer voting recommendations to users, and would like to obtain an API key to fully implement this in the future. It’s all about inclusion, education, and engagement! And until then, we hope you VoteSmart!
VoteSmartV2
An enhanced version of VoteSmart that helps voters make informed decisions about ballot propositions using AI analysis.
Features
- User authentication and profile management
- Political stance configuration (Economic, Social, Environmental, Foreign Policy)
- AI-powered ballot proposition analysis
- Modern, responsive UI
- Enhanced security and error handling
- OpenAI GPT-4 integration
Setup
- Create a virtual environment:
python -m venv venv
- Activate the virtual environment:
- Windows:
.\venv\Scripts\activate - Unix/MacOS:
source venv/bin/activate
- Install dependencies:
pip install -r requirements.txt
- Set up environment variables in
.env:
FLASK_APP=app.py
FLASK_ENV=development
FLASK_DEBUG=1
SECRET_KEY=your-secret-key
OPENAI_API_KEY=your-openai-api-key
- Initialize the database:
flask db upgrade
- Run the application:
python app.py
Usage
- Register for an account
- Configure your political stances in your profile
- Submit ballot propositions for AI analysis
- Receive personalized voting recommendations based on your political profile
Security Note
Never commit your .env file or expose your API keys. Make sure to keep your SECRET_KEY and OPENAI_API_KEY secure.
Project Structure
/app- Main application directory/models- Database models/routes- Application routes/templates- HTML templates/static- CSS, JavaScript, and other static files
Analysis
View
Metric
- 1
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- CSSIn code
- FlaskIn code
- HTMLIn code
- JavaScriptIn code
- PythonIn code
- OpenAIClaimed
5 of 6 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
No AI coding agent signals were found in this repository.
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
135 KB
Source files
36
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
yaycobparker/VoteSmart
51 files · 862 KB · @ 9011cc2
Structure
Interface
8 files · 16%Screens, components and styles rendered to the user.
API & routing
4 files · 8%Request entry points: routes, handlers and controllers.
Application logic
18 files · 35%Domain rules, services and shared utilities.
+1 moreData & schema
15 files · 29%Schema definitions, migrations and data access.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- Python64%
- HTML27%
- CSS5%
- JavaScript3%
- Markdown1%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
requirements.txt
pypi · 11- email-validator
- flask
- flask-babel
- flask-login
- flask-migrate
- flask-sqlalchemy
- flask-wtf
- nltk
- python-dotenv
- sqlalchemy
- werkzeug
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
This project’s features have not been analysed yet.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.