codeforboulder / upswyng

UpSwyng is a mobile-ready, digital directory of resources to assist the unhoused and at-risk communities of Boulder, CO

UpSwyng is a mobile-ready, digital directory of resources to assist the unhoused and at-risk communities. This is a Code For Boulder project coming soon to Boulder County, Colorado.

Getting Started

If you have any issues getting started using these directions, please see the Troubleshooting section.

Requirements

Make sure you have these tools installed before you begin.

• Node.js version 14.3

• Docker version 20.10 or above

• Yarn

Building your local dev environment

1. Clone (or fork and clone) this repository and cd into it

2. Make sure docker is running on your machine. You can check by running docker ps in your terminal

3. Run yarn start:local

Project Organization

UpSwyng is a monorepo managed with Yarn Workspaces. It consists of five packages all in the packages directory:

• common - contains common libraries and utilities used across the other packages
• types - contains the TypeScript definitions used across the project
• server - a Sapper application with two parts:
  • an API server which provides data to the UpSwyng clients
  • an admin web interface which uses the Svelte framework to create and modify data for the project
• web - contains the React web client
• native - contains a proof-of-concept React Native client

Working With Yarn Workspaces

To run a command in a specific package, use the yarn workspace command from the project root. For example, to start the web package development server run:

yarn workspace @upswyng/web start

To run the same command in all workspaces, use yarn workspaces. For instance, to run test in all packages use:

yarn workspaces run test

Typing out the full workspace name can get tedious. You can place aliases in your .bashrc or .profile to save time:

alias @uw="yarn workspace @upswyng/web "

Now you only need @uw start to start the web dev server.

Running tests

When you push a branch up to GitHub, travis will attempt to build the app with your changes and will run our entire test suite to ensure that nothing is broken. It's a good idea to run tests locally before pushing, although it is not required.

If you wish to run tests locally, you will need to ensure that redis-server is available in your path. You can check by running redis-server, and you can install it here or via brew install redis on mac.

Once Redis is installed, run our entire test suite with yarn test.

Windows 10 Installation on Windows Subsystem for Linux 2

1. First Install WSL2 choosing Ubuntu or distribution of choice.
2. Install NVM to allow for different versions of Node. This will also install NPM.
3. Install yarn globally
4. Install Docker Desktop for Windows with WSL2 support. Note that it's important to do this after installing WSL2.
5. Fork or clone the repository into a folder native to Linux and not the Windows system. This avoids problems with line ending differences between Windows and Linux. It is also much faster to access the Linux filesystem directly rather than the Windows filesystem through Linux.
6. Run yarn start:local as noted above.

Troubleshooting

The engine "node" is incompatible with this module.

When running yarn to install project dependencies, you may see a message that looks similar to:

The engine "node" is incompatible with this module. Expected version "^14.3.x". Got "11.15.0".

This just means that your machine's current version of node does not match the version required to run the UpSwyng server, 14.3.x. To fix this you'll need to install and which your current version of Node. nvm is a helpful tool, among others, you could use to easily switch between node versions.

Type Errors

The packages native, server, and web depend on common and types. If you edit common or types, or pull a new commit which contains edits to those packages, they need to be rebuilt. If you do not rebuild, you may see a type error like:

upswyng/packages/server/src/utility/slackbot.ts(76,23): semantic error TS2551:
Property 'DraftApproved' does not exist on type '{ alert_live: any; draft_approved: any;
draft_created: any; draft_deleted: any; resource_issue_reopened: any; resource_issue_resolved: any;
user_permission_changed: any; }'. Did you mean 'draft_approved'?

To fix this, run the script:

yarn build:local-packages

Connection refused to server and database when using WSL2 and Ubuntu

When setting up the environment on Ubuntu the following errors may occur when executing yarn start:local

[ioredis] Unhandled error event: Error: connect ECONNREFUSED 127.0.0.1:6380

MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017

To fix this issue make sure that you have properly installed the docker engine. steps for installation can be found at the Docker Engine installation docs.

Now install Docker Desktop. Documentation found here.

Once you have finished setting up Docker Desktop restart your computer and navigate to your upswyng folder, and run the following scripts.

yarn reset
yarn
yarn start:local

Reset

If nothing you try is fixing your issue, you can totally reset your local environment with yarn reset. After performing a reset, try yarn start:local and see if things work out.

Contributing

Pull requests are welcome and encouraged! Please review and follow our guidelines.

upswyng's Issues

Create Google Map component

Google Maps are used in two separate areas:

A. in the "map view" when viewing a list of services of a certain category on a resource list page #28
B. on a specific resource page detailing the the location of the resource as well as showing a bus route to the resource #29

Based on the two separate use cases, this will need to be able to meet the following conditions:

• accept input of one or more locations to create pins on a map
• accept a way of showing/hiding directions to an individual location based on the user's current location (if provided)

Move test files to the __tests__ folder

We'll be keeping our test files in the src/components/__tests__/ folder.

Any test files, those ending in .spec.tsx, .spec.ts, .spec.jsx, or .spec.js will need to be moved there.

[Temperature Feature] As a person in Boulder experiencing homelessness, I'd like to know the current temperature

Below, boxed in red, is an example of the temperature in the header of the application.

For our data source, we can use Open Weather.

Severe Weather Shelter Notifications

Part of this application will need to include a notification that goes out to all users about the opening of Severe Weather shelters during the winter.

Since this feature is crucial for the user's well-being, we need to ensure that we have great confidence that it appears when it should.

** MINIMUM MID SEPTEMBER **

Issues to Address

• How do we consume and record this data?
• How will this data appear on the application?
  • How long does it persist?

Find and implement a linter we like

Prettier is great for formatting. Typescript is great for typing. Add a linter to enforce style issues like Upper/Lower case for vars, etc.

Remove legacy references to data sources once migrated

• Remove data dumps in data_pipeline
• Remove download scripts in package.json (or update them to point at our own data)
• Revert isolatedModules change
• Remove types which reference Strapped data
• Rename ...Upswyng... types to not specify Upswyng, since they're now canonical
• Remove conversion utilities/scripts

[Listing Page] As a person experiencing homelessness, when I hear about a service I need to know some basic information so that I can determine if using the resource is feasible for me.

Info Displayed on a Listing Page

• existing information:
  • Resource Name
  • Address
  • who it is for
  • what they offer
  • Full description
  • website
  • phone number
  • whether they are open or closed
  • whether user has favorited it or not
  • hours of operation
• missing information
  • image of the resource (optional)
• sub-components to be built
  • carousel for multiple images
  • map embed with #40

Update Instances of "Soup Kitchen" to "Meal"

Within our admin interface, we'll want to ensure that any listed resources that use the word "soup kitchen" are updated to use "meal" or "meals" instead.

[Resource List Page] As a person experiencing homelessness, I need to view listings by categories so that I can easily find what I am looking for.

This page is dependent on issues #38 and #39. The map view, shown below, is a lower priority and dependent on #40.

• Resource List Page should have a header that says what category user is in

• Resource List Page should have subcategories in tabs that help the user further navigate the category

• Information to be included on each resource preview in the list:

  • Resource Name
  • Address
  • Short description
  • who it is for
  • what they offer
  • whether they are open or closed
  • whether user has favorited it or not
  • link to full listing (with hours and description)

• Resource List Page should have a toggle so that users can view the resource list in a map view

• Resources are listed in order of distance from user (if provided)

Acceptance Criteria

[ ] the main resource header at the top of the listing page should have a background equal to the tile of the resource type on the home page
[ ] the bars located at the bottom of each image should correspond with the color of resource tile on the home page.

Add linting via prettier

Implement search feature

We'll need to determine how we'll search the data. Firebase recommends using a third-party service for full-text search.

TODO

• complete dependent issue, #28
• determine how we will implement search
• create final designs for the search feature
• implement the search feature

Design

Currently, the wireframe for the location of search can be found on the home page, #26, and will list out services in a resource list page, #28.

While we build the infrastructure, we'll need final mocks for the search module.

Algolia

Algolia could be a good contender that has directions on implementing with Firebase and has a discounted plan for non-profits. Part them allowing to use Algolia for free will include having something like "Search by Algolia" placed near or on our search feature.

Update README with Algolia Keys

Organize project management for tasks

It would be nice to have a simple Kanban setup so we can easily see a backlog of issues to address. I'm hoping to have a workflow something like:

1. Apply Status: Pending label adds the issue to the "backlog" column.
2. Apply Status: In Progress label adds the issue to "in progress" column.
3. Apply Status: Needs Reviewed label adds the issue to "needs reviewed" column.
4. Closing the issue or apply Status: Completed label adds the issue to "completed" column.

I looked into using GitHub projects, but I wasn't able to find a way to tie automation to labels.

[Landing Page] As a person experiencing homelessness, I need to land on a main page so that I can orient myself in the application.

• menu should say 'menu'
• logo should be ever present inline with the menu
• search should be prominent on the main page
• coordinated entry button must stay
• more important content (food, shelter) should be more prominent than less important (education, pets)
• Icons could be laid out in blocks instead of circles in order to use space better

[Provider Onboarding] As a provider, I need a way to claim my listing so that I can update and manage it going forward.

• Providers should get an alert that they need to claim their listing
• Providers should have an authentication process to go through so they can prove that they are who they say they are.
• Providers should have an option to claim multiple listings
• Providers should be prompted to edit their listing the first time that they log in
• Providers should be prompted to configure a regular alert so that they can be reminded to update their listings.

Individual Service Page: Display Associated Resource Image

this is blocked by part #45

When an image is for a resource is available, it should be displayed on the provider page.

Category Page "Opens at" or "Closes at" Label

Each listing on a category page needs to contain an "Opens at" or "Closes at" label.

the text needing replaced is "schedule placeholder"

Conditions

• if it is open 24/7, it should contain "Open 24/7"
• if it is open on a weekly basis
  • if the resource is currently open, it should contain "open (closes at [closing time here])"
  • if the resource is currently closed
    • if it opens tomorrow, it should contain "opens tomorrow at [next opening time here]"
    • if it opens again in the same week, it should contain "opens [next opening day here]"
    • if it opens again next week, it should contain "opens next [next opening day here]"
    • if it opens further in the future, it should contain "opens [next opening date here, e.g., Sept. 30]"
• if it is open on monthly basis, i.e., "the first Sunday of every month"
  • if the resource is currently open, it should contain "closes at [closing time here]"
  • it should contain "opens [next opening date here, e.g., Sept. 30]"

Individual Service Page: Google Map Fixes

Transit Types

We'll need to provide handling of more than bus directions:

• directions by car
• directions by bike
• directions by foot

Fixes

• We'll need to handle when directions are not available (in the case of some bus transit)
• Make the directions more prominent

update <Resource/> to use <useResource/>

We'll want to replace withResource HOC in <Resource/> with the useResource component.

An example use can be found in the useResource component.

Easier Setup for Local Development

Currently the data for the application lives in Firebase, and it is difficult for any newcomers to get up and running without involvement with project admins.

We need to setup our project to be easier for local development, starting with reading data. Perhaps the easiest update would be to place a JSON file within the project itself that is used as the data source. Local environment variables could then be updated if the user has setup a Firebase application to work with.

Separate service types and categories in DB schema

In the current DB, service types and categories exist comma-separated in a single string.

Example servicetype entry:
Food Pantry, Clothing, Houselhold Items, Computer & ESL Classes, and mor

Some items currently found in the servicetype entry could also be reclassified as either a category or service due to the new layout.

Option 1: Define our own categories & service types that service providers can choose from.

Pros:

• more easily indexed data
• prevent over-tagging

Cons:

• could possibly limit service provider's tagging too much

Option 2: allow the user to specify their own, or both?

Pros:

• more power to local service providers that may know their local population's searching habits
• catches extra, unforeseen service types

Cons:

• risk over tagging
• would need to implement way to handle misspellings

Option 3: Have some preset categories & service types but allow additional, custom input

Pros:

• more easily indexed data
• more power to local service providers that may know their local population's searching habits
• catches extra, unforeseen service types

Cons:

• risk over tagging
• would need to implement way to handle misspellings

Main Menu (Placeholder)

The main menu drawer, opened by the top-left hamburger will need implemented.

More details on the contents pending.

Add Material UI as dependency

We'll be using Material UI to assist in building and styling components.

rename ENV variables

In #77, we updated our environment variables to no longer start with REACT_APP; however, it turns out that it is required by Create React App.

We'll need to reverse what was done in #77 to ensure that these environment variables are properly implemented upon build.

Create category filtering bar component

Create a filtering bar component used to filter a list of services by sub-categories.

It should accept the following properties:

• an array of strings with each containing an individual category name.

Starter Material UI Theme

We need to come up with a material UI theme that we can start with, and then once Purdue is done with the branding and style guide we can update it.

Add Extra Inputs to DB Schema

There are some extra inputs we're requesting from our providers that the current DB schema doesn't account for. We'll need to come up with a structure for these additional items.

Categories and Sub-Categories (completed)

Categories are not specifically listed in the current schema. We should create a structure for labeling resources that belong to them.

Contact Person Information

We are requesting a point of contact that can be separate from the contact information placed in the app. This would be for Upswyng to reach out about a particular resource. Items include:

• name
• email
• phone

Images (completed)

Images are not currently part of the DB structure. We need to determine what the structure for the images will be. I"m good with it being something as simple as below.

{
"images":[
    {
        "id":"123yvu1231bv23",
        "url":"https://lkwaefoweif.com/image1.jpg",
        "description":"brief description of the image"
     },
    {
        "id":"09nhgfnbdv212j",
        "url":"https://lkwaefoweif.com/image2.jpg",
        "description":"brief description of the image"
     }
]
}

This structure would exist in each resource node (where images are provided).

We would also want to determine where these images will live, but this won"t necessarily stop dev from using placeholders.

What should the client know before using your service?

Occasionally a service may have some tips helpful to using their service successfully. Some examples include:

• You must have a valid ID in order to use our service .
• To qualify, you must be of some age group.
• Etc.

[Provider Flow] As a provider, I need to create and edit a profile for my organization, so that I can publish information to Upswyng and offer help to people experiencing homelessness.

• There should be a provider login within the main menu
• The login should take the provider to all listings that they manage
• The provider should be able to create listings
• The provider should be able to edit listings
• The provider should be able to delete listings
• The information should convey that the edits go through approval and take some time to propogate.
• A forgot password flow needs to be considered down the road.

Add firebase

Settings in ENV variables with env.local.example that should be copied to env.local and completed for local development.

determine how to keep packages, used in different workspaces, in-sync

We ran into an issue where two versions of react-dom were present in the repo, which led to failures after build.

To account for this, we pinned those packages; however, this was only a temporary fix to get the web package functioning again.

A solution would include:

• ensuring that package versions stay in-sync
• packages could be un-pinned to allow updating

Create a current IA Diagram

We need to document the current structure of the categories and subcategories, since it has been tested and validated with Boulder users. This will serve as documentation of our alignment on the way data will be displayed. Any changes should be re-tested and validated.

Individual Service Page: Google Map List View

A list view needs to be created so that user's can navigate more efficiently.

example of directions listed beneath the map

Create an initial header

Create the main navigation for the site:

The component most suitable for this item would be Material UI's App Bar.

Add contribution notes to README

We'll need documentation about contributing to the project for newcomers:

• directions for Code for Boulder team members
• directions for outside contributors
• branching model info
• branch naming conventions?

Category Page Placeholder Images

We'll need some placeholders applied to service images when an image is not available.

example of placeholder image for a shelter

The icons on the placeholder can match the corresponding icon of the category found on the home page.

Create PR template

For automatic issue tracking with our Waffle.io board, we'll need to make sure users include references to issue numbers in pull requests. We can make this easier by creating a PR template.

CamelCase keys in types

TResouce and TSchedule in particular have all lowercase keys where there are two words. Update the types and their uses to camel case. If, for some reason, we can't get this information from the data layer in the right format we'll convert it at the boundary.

Fix Casing of "Upswyng" throughout the application

Throughout the application, any use of "UpSwyng" should match the case as shown before and below:

UpSwyng

Note: the capital "U" and "S"

Create robots.txt

More information

Install step missing from Readme

The command "npm i" needs to be added to Readme.md before "npm start" to install project dependencies.

implement ability for users to add favorite services

We want to enable users to add listings to a favorites list for easy future access.

Technical Considerations

• we don't provide any type of user-login, so favorites will need to be stored via local storage
• an endpoint will need created that accepts a list of resource IDs

Tasks

Add to Favorites

On an individual listing, display a floating action button that adds/removes an item from the user's favorites.

• when favorited, display a primary orange favorite icon import FavoriteIcon from '@material-ui/icons/Favorite';
• when not favorited, display a primary orange favorite border icon import FavoriteBorderIcon from '@material-ui/icons/FavoriteBorder';
• when pressing the button, it toggles whether the resource is favorited or unfavorited
• when the user has favorited an item for the first time, display an info snackbar that displays the following message for five seconds "Favorites are only saved to this device."

Favorites Page

• create a new API endpoint that accepts a list of resource IDs and returns the info needed to display favorites in a view similar to a category/subcategory list
• create a favorites page of a similar design to a category/subcategory list
  • no filtering of resources beyond favorites is needed
  • use the primary orange color for the banner which contains the text "Favorites"
  • below the banner but above the favorites list, display an info alert with the following text: "Favorites are only saved to this device. They will not be saved if you are using a public computer, or when you have a private session enabled in your browser (incognito mode)."
  • when no items are favorited, display the following text instead of the favorites list: "You haven't added any favorites yet!"

Main Menu Link

• add a "Favorites" link to the favorites page in the main menu using the favorite icon import FavoriteIcon from '@material-ui/icons/Favorite';

Implement 3rd party authentication for service providers

Allow service providers to use separate logins to manager their service(s):

• Facebook
• Twitter
• etc.

Temp does not change as the temp changes

Temp doesn't update live/ stays the same until you refresh the app
It doesn't change even if you click on a link to another page

Create Individual Service Card Component

Create a functional component that displays a brief overview of an individual service used on a page that lists the various services available.

It should accept the following properties:

• image thumbnail (use a placeholder for now)
• resource name
• category
• physical address
• audience
• offered services
• hours

Create Initial Routes

We'll want to create some initial routes so developers can work on specific features separately:

• / : the main home page
• /shelters : all shelters page
• /hygiene : all hygiene page
• /hotlines : all hotlines page
• /food : all food providers page
• /transit : all transit provider page

Fix types for Map Component

PR #49 added the map component, but the typing for the file is incomplete (see discussion in PR).

Add type params for the component, then fix the errors that pop up.

Implement multi-language support

Having additional languages, especially Spanish, would be a bonus.

• How could we translate what data already exists?
• How could we translate new services?
• How could we implement translated data into the current DB?

[Report Data] As a person experiencing homelessness, I need to be able to report a piece of data as inaccurate so that I can keep myself and friends from seeing incorrect data.

• There should be an option on each listing page to report inaccuracies in a listing
• There should also be an option from the main menu to contact upswyng directly about an issue with the information

UPDATE:

#276 added a new endpoint resources/issues/user-report that allows submitting issues into the DB:
more info

Requirements

• a "Report a Problem" button is added at the bottom of resource page that takes them to a form to report an issue
• a new "report and issue" form contains the following items
  • a non-modifiable "Resource Name" text input containing the name of the resource that led them to reporting a problem
  • a checkbox for each label
    • the address is wrong
    • the phone number is wrong
    • the website is wrong
    • the schedule is wrong
    • the directions are wrong
  • a checkbox with a label of "other" exists
    • when the "other" checkbox is checked, a text input appears to allow submitting a custom issue
  • an optional "Comments" multi-line text input is located at the bottom of the form
  • a "Send" button is located at the bottom of the form
    • when the "Send" button is created, it submits the data mapping the following request body properties of the API call
      • the checkboxes map to the reportedIssues string[]
      • the "Comments" text body maps to detailExplanation string
      • the resourceId of the resource that has an issue (this is determined by the resource that led them to the "report an issue" form
  • when the form is successfully submitted
    • a message appears stating "The problem has been submitted and will be reviewed. Thank you for your feedback!"
    • a button appears stating "Back to Resources" that will take the user back to the home page
  • when the form fails to submit, a message appears stating "There was a problem sending your feedback. Please try again."

Create script to populate DB from Google Sheet

this depends on #45

While we work on creating a better UI for updating resource information, we'll be using a Google Form that will populate info into a Google Sheet.

A script will need generated to take the information in that sheet and transfer it to our local DB.

Tech Notes

• In the form, we do not request the latitude or longitude of physical location of the resource. This will need to be generated via the address provided in the form.
• Some inputs requested in the form are not part of our current DB model. We'll need to some up with a schema for these additional items .

More notes to come.

Implement individual job postings into schema

When searching for job help, users should be able to find services that assisting in finding jobs as well as specific jobs to apply for.