Home Unite Us

Home Unite Us is a community developed web platform designed to support and scale the host homes initiative.

Host homes provide short-term housing interventions for young people, aged 18-25, who are experiencing homelessness for any variety of reasons. The process for matching youth with a temporary safe space can be challenging, but numerous organization have implemented programs tailored to the needs of their local area. These implementations can vary in their exact policies and procedures, but they are all driven by the core principles of the host homes initiative and they often share an overlapping set of technological needs.

The Home Unite Us team is working hard to create the technology that can meet those needs in a scalable fashion. Our pilot program allows guests and hosts to easily submit applications, and provides coordinators with a dashboard that makes the home matching process simpler. The stable version of Home Unite Us is at https://homeunite.us/ and our most up to date beta features can be found at https://dev.homeunite.us/.

Interested in joining our team? See our contribution guide to get started!

Project Context

This project is part of a larger initiative at Hack for LA around creating a shared housing application, that can be used by organizations across the county to help people transition to living independently and sustainably through host homes, empty bedrooms, and roommate matching for shared housing with lease signing.

Technology Overview

The HomeUniteUs project is structured as a multi-docker container application, with secret-protected access to networked resources. The project contains five containers, whose activities are coordinated using the docker compose configuration outlined in docker-compose.yml. The five containers are:

1. frontend: A frontend React app developed using TypeScript.
   • It uses Redux to manage client state, with the Redux Toolkit to simplify development.
   • It uses the Material UI component library, for access to high quality UI components designed with accessibility in mind.
   • It uses the Vite build tool, for fast dev builds and optimized production builds.
2. backend: A backend python API, hosted on AWS.
   • It uses FastAPI as its web framework.
   • It uses the SQLAlchemy SQL toolkit and Object-Relational Mapper (ORM). This serves as a developer-friendly layer between the Python app and the database.
3. db: A PostgreSQL database container.
   • The database is stored as a docker volume, db-data.
   • If the volume is not found during spin-up, then an empty database volume will be created.
4. motoserver: A development tool. It runs moto in Server Mode.
   • It allows developers to mock AWS so that AWS secrets are not needed for local development. This tool is used because HUU uses AWS Cognito as its identity and access provider. However, most local development will not need to make actual calls to AWS Cognito for HUU feature development. Using this tool will allow developers to login to HUU on their development machine.
   • It has a dashboard located at http://127.0.0.1:5000/moto-api/
5. pgadmin: An optional development tool. It is a container running pgAdmin4. pgAdmin4 is database administration and development platform for PostgreSQL.
   • This tool will allow can be used to run queries against the PostgreSQL server running in the db container.
   • It is accessed by going to http://127.0.0.1:5050

Build Instructions

Since this project is Dockerized, you can choose to either build the backend and frontend apps as Docker containers or directly onto your local machine. This guide will focus on Docker builds, but full local build and deployment instructions can be found in the api and app READMEs.

Also note that the code in this repo should build without issue on Linux, Windows, and MacOS. We do, however, utilize some Linux-only tools during deployment and primarily target the Linux platform.

Docker Build

Building with Docker is the simplest option, and debugging applications within the container is also easy with some configuration.

Requirements

• An up-to-date installation of Docker

Instructions

1. Build and run all containers by running the docker compose up -d --build shell command from the root directory:
2. Verify there are no build errors. If there are build errors, reach out to the development team.
3. Open http://localhost:4040 in any browser to use Home Unite Us.

• pgAdmin4 is available at http://localhost:5050/browser/ to query the database.
• moto server is available at http://localhost:5000/moto-api/ to view mocked AWS data.

Test Users

For local development, test users already exist when started using Docker.

The password for all test users is Test123!.

• 1 Admin: admin@email.com
• 26 Guests: guest[a-z]@email.com (e.g. guesta@email.com, guestb@email.com, ... guestz@email.com)
• 26 Coordinators: coordinator[a-z]@email.com (e.g. coordinatora@email.com, coordinatorb@email.com, ... coordinatorz@email.com)
• 26 Hosts: host[a-z]@email.com (e.g. hosta@email.com, hostb@email.com, ... hostz@email.com)

Testing Instructions

Testing instructions for each application are in the backend and frontend README files.