drkchn/mosa-upenn-soc-2023

Civics-Themed Winner @ MOSA Summer of Code | Get Out The Vote: Civics Central | Promoting democracy by educating voters about upcoming elections

Project Title: Civic Central

Overview

Project summary

In the United States, the voting-age population turnout has been historically lower and lags behind many other peer countries. We believe our project can help increase civic engagement by educating users. Our application aims to encourage users to participate in democracy by making it easier to access election information.

When a user inputs their residential address, we query the Google Civics API and present comprehensive information about on any upcoming U.S. elections. We also offer the user the ability to see information about representatives across all levels of government based on the users input.

Check out our Devpost here! Devpost Civic Central

Authors (by last name alphabetical order)

• Derek Chen - @drkchn – derche [at] seas[dot]upenn[dot]edu – GitHub
• Connor Fech - @cfech – cfech [at] seas[dot]upenn[dot]edu – GitHub
• Gunjan Jhaveri - @gjhaveri98 – gjhaveri [at] seas[dot]upenn[dot]edu – GitHub
• Prinsa Patel - @prinsaa – prinsa [at] seas[dot]upenn[dot]edu – GitHub

Usage

Prerequisites

• Node Version Manager Install to manage multiple Node.js versions (Optional)
• Node.js (version 18.16.0)
• Google Cloud Account
• Google Civic Information API key

Installation

1. Clone the repository to your intended directory

git clone https://github.com/drkchn/mosa-upenn-SoC-2023.git

2. Run the command npm install to install all dependencies

3. create a file in the root directory called .env

   • Add the following environment variable: VITE_CIVICS_API_KEY=[Your Key Here]

4. Run the command npm run start to locally launch the project

5. Check out our codebase!

Getting the Google Civic Information API key

• API Documentation

1. Navigate to Google Cloud console
2. Go to Navigation menu --> APIs & Services --> Credentials
3. Click Create Credentials --> API Key
4. Go to Navigation menu --> APIs & Services --> Enabled APIs & Services --> Click on Enable APIs and Services button
5. Search for Civic Information API and click Enable

Restrict your API key to prevent unauthorized access (Optional)

1. Go to APIs & Services --> Credentials
2. Under API restrictions, click on Restrict key
3. Search for Google Civic Information API and check the box
4. Click Save button

Working with ENVs in React with Vite

• Vite ENV docs

1. create a .env file in the root directory
2. Add the following line

VITE_CIVICS_API_KEY=[Your API key goes here]

3. Never expose or git push your API key!

   • Environment variables must be prepended with VITE, or it will not be picked up during the application build.

4. Use it in the application

Deployment & Features

Using the Homepage Search Bar

1. Navigate to the search bar on the homepage.
2. Enter a U.S. residential address, then click on the FIND MY ELECTIONS INFO! button.
3. You will be redirected to a new page.
4. Check out any upcoming elections in your area, or view your representatives in government!
5. You can click on the Election name button or Officials' name button for more information.

Navigating the Why Vote? Page

1. Navigate to the Why Vote? page.
2. Each of the buttons is hyperlinked to reputable sources where you can learn more about the importance of voting.
3. You can see historical voting data from 1990-2022, based on sex and race at the bottom of the page.

Changing the Website Theme

1. Click on the icon with the symbol of a sun.
2. You can toggle between a light theme and a dark theme.
3. The purple light theme represents the shared bipartisan goal of educating voters and encouraging voters to participate in democracy!

Reviewing the Request History

1. Click on the icon with the symbol of a magnifying glass and upwards line graph.
2. You can review all prior API requests and see if an API call was successful (200 OK) or unsuccessful (400 Bad Request).
3. You can click on CLEAR button to clear your request history.

Learn More:

1. Click on the About page to learn more about the developers
2. Click on the Learn More button to see a detailed technical explanation of the application
3. You can also click on any of the technologies to learn more about them individually

Responsive Design

1. All pages in the app are completely responsive
2. The app can be viewed on any screen size without compromising the user experience

See Our Code:

1. Click on the <> icon
2. The GitHub repo will open in a new page

Additional information

Application Design

Civics Central is developed using React, Typescript and Vite. Typescript is utilized to enforce strict static typing. Axios is used to query multiple different API's from the Google Cloud Suite from which the reposes are memoized in order to limit overuse of Google Civics API and hitting our rate limit. Our application using React Router to handle rendering different pages as well as React Context and State to share data between components. Material UI component library is leveraged for pre-built components, implementing custom application themes and applying principals of responsive design.

Local Development Environment

Our local development configuration is focused on enforcing frontend development best practices. We utilized prettier and eslint to enforce code format standards as well as build and push scripts that run linters and tests and the Vite build tool to package code for production. Our application also has React Testing Library and Jest for unit testing and code coverage reports. Environment variables are used to pass various run time arguments to the application, such as API keys.

Team Collaboration

Our team practiced a trunk based development methodology to effectively and efficiently collaborate on on this project. We utilized git branches and github issues in order to collaborate together and mitigate potential merge conflicts. In a trunk based development model the main branch acts as the single source of truth and one off branches are checked out on a per issue basis then merged back into the main branch after the issue is complete.

Tools used

Which frameworks, libraries, or other tools did you use to create your project?

• React.js - Web framework
• TypeScript - Programming language to enforce static typing
• Node.js - JavaScript runtime environment
• Google Cloud - Google Civic Information API, monitor API usage, and prevent API overuse
• Google Firebase - To host the application
• Vite.js - As a local development and build tool
• Material UI - Pre-build components, for consistent UI/UX, and responsive design
• Git/GitHub - Version control system, trunk based development
• Prettier - Enforce code formatting
• EsLint - Enforce Javascript best practices

Future Features

In the future we would like to add user accounts and a search history for each account. This would allow the user to see all of their previously queried data without having to search again. We would also like to integrate a map into the Civic Info page that shows the address/location fo the election. 0

mosa-upenn-soc-2023's Issues

Update README and document how to set up and activate API key

Display Representative information in a grid layout

Add a page that describes what tech we are using

Write detailed technical explanation on about page

MVP Query Google Election API and display data in the console

Disable query button when searching

we do not want to user clicking the button multiple times and making a bunch of successive api calls.

MVP Homepage/landing page for app that contains text box for users to input address

The landing page will be the first page users see when visiting our website. It will contain a text box where users input their residential address. The page will query Google's Civic Information API to get a list of upcoming election dates.

• display text box on screen
• #30

Add pre push git hook that runs linting and tests if pushing to master

Want a git hook that will prevent any breaking changes being pushed to master

Create a loading state

Remove console.logs from production code

We do not want items to be printed to the console in the production application. This is a bad practice and cause various security vulnerabilities. Can keep these logs in development mode but remove them in production by following this example.
vitejs/vite#7920 (comment)

Add wiring and examples for creating a custom MUI theme

Setup mui create theme method and get it ready to add custom colors

MVP Secondary webpage that displays the relevant elections information to users

After querying Google's Civic Information API, this webpage will display the upcoming list of elections to the user, along with details about future elections. Relevant information includes but is not limited to date, location, address, county/district, link to Google Maps/directions, and more.

Add a testing library

• Have to add react testing library to the application so we can test our code.
• install library
• add debug root functionality
• add to pre-push script

Display Representative data

Add error handling to api search using mui snack bar

Can use a snackbar to alert the user their query has failed

https://mui.com/material-ui/react-snackbar/

General responsiveness

Create a favicon

https://www.seoptimer.com/blog/what-is-a-favicon/

Make WhyVote page responsive

create a responsive WhyVote page by using grid.

Look into MUI responsive design

Design a wireframe of the home page

• What is our color scheme?
• What is our home page?
• What is our design
• can review material ui docs

Query google civics api for representative data

Steps:

• create api key
• take in user data
• encode address
• make and handle request
• dump in the console.

Allow for overides in the test factory

Fix Footer

Make sure the footer is always on the foot of the page, both in phone and computer view

Display Election responses

Create environment variable example

• Will need an api key to query google api, have to be able to handle env vars in react axios calls

Fix styling in CivicInfo Page

Add local storage example

Create responsive navbar

Completed: Used mui components to create a responsive navbar

Create a persistent store of requests

Show more representative data in a modal

Be able to click on a representative and show more data about them in a modal

Display available elections after querying API

Deploy template to firebase

• guide

Firebase Account Required

Steps taken:

1. Created a firebase project
2. sudo npm install -g firebase-tools
3. firebase login
4. In the root of the project firebase init
5. Configured firebase.json to run build script before a deploy would happen
6. ran firebase deploy

Store address in context and propagate it to the 2nd api call

look into react context

https://www.youtube.com/watch?v=5LrDIWkK_Bc

• This may help us remove prop drilling

Ensure build script fails on linting error

We don't want to be able to build and deploy the app with linting errors. Want the build script to fail on linting error

Add dark and light mode toggle

Add a toggle to the navbar for dark and light mode

mui docs: https://mui.com/material-ui/customization/dark-mode/

Create theme

Generate A React Template

• React template generated and added to the repository
• Added support for material UI
• Added prettier linting
• Added some documentation to the readme

MVP Webpage that explains reasons it's important to vote

The webpage will contain information about the importance of elections, democracy, and civic duty to motivate users to vote in their elections. Webpage should be visually appealing while informative for users. Overall, it should provide educational aspects to voting.

Upgrading the navbar & updated footer

Working on updating the navbar to add more features like buttons, website icon/logo, and setting the theme for the navbar

Add informative links when hovering over button

create an interactive button for the fun facts and when clicked on, open to external informative link

Add react router

We will need react router to handle different pages at different URLS.

Learn more at geeks for geeks

Query elections address API based on the list item that has been clicked

Convert to index based exports

Updating package-lock.json

Added a line "hasInstallScript": true,

Create a footer

• Footers usually have information about the creators of a website, any legal notices erc.

example:

make second election api call

MVP Secondary webpage that displays elected representative information to users

The webpage will query Google's Civic Information API and display the representative information to users. This webpage will be used in conjunction with the landing page where users can find information about their upcoming elections.

Make search bar work on enter key

Configure react context for elections query