TimothyLe / gov-agenda-notifier

Agenda notifications for local government meetings

gov-agenda-notifier

It's common for city council, planning and commision meetings to only list one start time. The agenda items aren't scheduled for specific times because they do not know how long it will take to discuss each item. This leaves attendees wondering when they'll be able to comment on the agenda item they're interested in.

This problem has become a growing issue in the era of COVID-19 since virtual meetings are becoming more common. This web app allows meeting participants to "subscribe" to meeting items for notifications via text or email. Participants will benefit greatly from a notification system rather than be on stand-by for an undetermined length of time.

The City of San Jose is interested in this service, but this is a project that can scale to other cities as well.

Tech Stack

• Currently migrating deployed version to AWS
• Frontend
  • React.js + hooks
  • SASS
• Backend
  • Node.js and npm
  • Docker
  • Postgres
  • GraphQL
  • Apollo
  • Twilio
  • AWS Lambda
  • AWS API Gateway
  • AWS RDS
  • AWS S3
  • AWS Amplify
  • Terraform

Resources

• Slack Channel: #csj-city-meeting-participation
• Google Drive
• Links to Visual Design Mocks
• List of TODO items

Local Development

There are two ways to setup for local developemnt, with docker-compose (option 1) or directly (option 2).

Option 1

When running with docker-compose, a separate persistent volume is created for PostgreSQL. Also, changes made from your local text editor is synced to the respective containers for auto restart.

1. Go to the issues page to find something to work on:

   • https://github.com/codeforsanjose/gov-agenda-notifier/issues

2. Install Docker: https://www.docker.com/products/docker-desktop

3. Create a .env file in the /backend/graphql_api/lambda directory

4. Make sure the file includes these keys:

   NODE_ENV=development
   
   PGHOST=gov-agenda-notifier_backend_pg_1
   PGUSER=docker
   PGPASSWORD=docker
   PGDATABASE=devdb
   PGPORT=5432
   
   TWILIO_ACCOUNT_SID=AC-THIS-IS-TOP-SECRET-AND-NEEDS-TO-START-WITH-AC
   TWILIO_AUTH_TOKEN=THIS-IS-TOP-SECRET
   TWILIO_PHONE_NUMBER=THIS-IS-TOP-SECRET
   SEND_TEXT=false
   
   AWS_ACCESS_KEY_ID=
   AWS_SECRET_ACCESS_KEY=
   AWS_DEFAULT_REGION=
   FROM_ADDRESS=
   SEND_EMAIL=false
   
   JWT_SECRET = NEED-TO_CREATE-SECRET-KEY
   JWT_ISSUER = ADD-ISSUER-DOMAIN
   JWT_AUDIENCE = ADD-AUDIENCE
   
   GOOGLE_CLIENT_ID = NEED-TO-REGISTER-APP
   GOOGLE_CLIENT_SECRET = NEED-TO-REGISTER-APP
   

   • This file is NOT to be included in version control. We don't want secret keys publicly accessible.
   • Message Trace Ohrt on Slack if you need secret keys

5. Create a .env file in the backend/agenda_upload_service/lambda/ directory

6. Make sure the file includes these keys:

   NODE_ENV=development
   
   PGHOST=gov-agenda-notifier_backend_pg_1
   PGUSER=docker
   PGPASSWORD=docker
   PGDATABASE=devdb
   PGPORT=5432
   
   

7. Run docker-compose command to bring up the apps:

   docker-compose -p gov-agenda-notifier up --build

8. View the GraphQL API playground at http://localhost:3000/graphql

9. View the app at http://localhost:3001

10. Run command to remove (most) of build artifacts:

    docker-compose -p gov-agenda-notifier down --remove-orphans

Option 2

To Begin Work on the Frontend / Serve Frontend

1. Go to the issues page to find something to work on:
   • https://github.com/codeforsanjose/gov-agenda-notifier/issues
2. Install Node.js and npm
3. Install project dependencies:
   1. Please disable any linting or formatting solutions you have running globally. We enforce the Airbnb style guide with ESLint.
   2. Navigate to the /frontend directory
   3. Run command:

      npm install

   4. ESLint should be running as soon as you open a file with VS Code.
4. Make modifications to the codebase to address the issue your working on
5. See your changes:
   1. Navigate to the /frontend directory
   2. Run command:

      npm start

To Begin Work on the Backend / Serve Backend

Frontend specific development doesn't require these steps. Setting up the DB is only necessary if you'll be wanting to interact with the entire web app, including the backend API.

1. Visit the issues page to find something to work on:

   • https://github.com/codeforsanjose/gov-agenda-notifier/issues

2. Initialize the local DB

   • This step requires the make utility.
     • Additional configuration for this is required on Windows
   1. Install Docker
   2. Create the Docker image for the local DB
      • This only needs to be done once unless modifcations have been made to /backend/docker_for_local_dev_db/init.sql. See notes below.
      1. Navigate to /backend/docker_for_local_dev_db
      2. Run command:

         make image

   3. Spin up a corresponding Docker container ("Turn it on")
      1. Navigate to /backend/docker_for_local_dev_db
      2. Run command:

         make container

3. Initialize the GraphQL API Lambda server locally

   1. Create a .env file in the /backend/graphql_api/lambda directory

      1. Make sure the file includes these keys:

         NODE_ENV=development
         
         PGHOST=127.0.0.1
         PGUSER=docker
         PGPASSWORD=docker
         PGDATABASE=devdb
         PGPORT=8888
         
         TWILIO_ACCOUNT_SID=AC-THIS-IS-TOP-SECRET-AND-NEEDS-TO-START-WITH-AC
         TWILIO_AUTH_TOKEN=THIS-IS-TOP-SECRET
         TWILIO_PHONE_NUMBER=THIS-IS-TOP-SECRET
         SEND_TEXT=false
         
         AWS_ACCESS_KEY_ID=
         AWS_SECRET_ACCESS_KEY=
         AWS_DEFAULT_REGION=
         FROM_ADDRESS=
         SEND_EMAIL=false
         
         JWT_SECRET = NEED-TO_CREATE-SECRET-KEY
         JWT_ISSUER = ADD-ISSUER-DOMAIN
         JWT_AUDIENCE = ADD-AUDIENCE
         
         GOOGLE_CLIENT_ID = NEED-TO-REGISTER-APP
         GOOGLE_CLIENT_SECRET = NEED-TO-REGISTER-APP
         

         • This file is NOT to be included in version control. We don't want secret keys publicly accessible.
         • Message Trace Ohrt on Slack if you need secret keys

   2. Install project dependencies:

      1. Navigate to the /backend/graphql_api/lambda directory
      2. Run command:

         npm install

   3. Start server:

      1. Navigate to the /backend/graphql_api/lambda directory
      2. Run command:

         npm start

   4. View the GraphQL API playground at http://localhost:3000/graphql

4. Make modifications to the codebase to address the issue you're working on

Local Dev Notes:

If changes are made to /backend/docker_for_local_dev_db/init.sql, the old docker image must be deleted, regenerated and containerized for the changes to take place.

The command for deleting the previous image is:

make rm-image

After deleting the image with that command, follow steps "2. Initialize the local DB" again for your local DB to be back up and running.

Migrations

postgres-migrations library is used to manage migrations. backend/graphql_api/lambda/migrations/ contains all the migrations with the exception of creating the database which still exists in backend/docker_for_local_dev_db/init.sql.

Migrations are run on each request in backend/graphql_api/lambda/db/dbClient.js.

To create a new migration:

1. Create a new file in backend/graphql_api/lambda/migrations/ with incrementing integer prefix and few words describing the change, for example 002-add-link-to-meeting.sql.
2. Add your migration in that file.
3. Migrations will be automatically run on next request to the backend.

Workflow

1. Go to the issues page to find something to work on: https://github.com/codeforsanjose/gov-agenda-notifier/issues. If you're not sure, ping #proj-happening-atm-eng in slack for help.
2. Create a branch off develop and make your commits.
3. Open a PR to develop branch. Once merged, it'll autodeploy to the staging environment.
4. To deploy to production, open a PR from develop to main branch. Once merged, it'll autodeploy to the production environment.

NOTE: Do NOT open PRs directly to main branch without merging it in develop. If you want to deploy a specific commit to branch, you can do so, but open another PR to the develop branch so the two branches don't diverge.

Help

If you run into issues getting the above app to work, please post to Slack #proj-happening-atm-eng with a detailed bug report. If you have trouble running docker/docker-compose, please paste the results of docker-compose -p gov-agenda-notifier down --remove-orphans with your bug report.