CA Alerts (https://alerts-ca.herokuapp.com), submitted by Very Little Gravitas LLC for the California Department of Technology Digital Services Agile Development Prequalified Vendor Pool Refresh for CDT RFI # CDT-ADPQ-0117.
CA Alerts is a faster, clearer, simpler way for California residents and visitors to be notified of emergencies affecting them and for State emergency workers to assess and inform the public about emergencies.
Ths prototype is based on our experience delivering digital services that meet user needs and are simple and intuitive enough so users succeed first time.
A screenshot walkthrough shows the flow of the production application on our wiki.
Where appropriate, we've applied the plays from the US Digital Services Playbook.
- sign up quickly and easily, by only requiring a phone number and zipcode
- receive timely emergency and non-emergency alerts to keep themselves, their loved ones and the people they're responsible for safe
- choose a location (a zipcode) to receive emergency and non-emergency alerts for
- receive alerts by SMS or email (with forthcoming push notification functionality)
- publish automatic fire alert emergency notifications to registered users whose location is within a 50 mile geofence of a fire, so the public are notified about nearby fire emergencies
- visualize up-to-date data on fire, river gauge, weather hazard, earthquake, tsunami and other natural hazards from the U.S. Geological Survey, National Oceanic and Atmospheric Administration and the U.S. Department of Interior in California or may affect California, so they can assess and make decisions about publishing emergency or non-emergency notifications
- publish manual emergency and non-emergency notifications, so the public can be informed about emergency and non-emergency situations
- track and analyze data about published notifications and public users
- Request the prototype Authorized User username and password by sending an email to: ca-alerts-support@verylittlegravitas.com with the subject "CA Alerts Admin Request".
The Product Manager, Dan Hon, also served as Product Owner in the agile delivery process. We assigned him the leader of the project, with full responsibility and authority to build the prototype. He had full accountability for the quality of the prototype.
We assembled our multidisciplinary team based on our experience and GSA 18F Agile Labor Categories:
- Product Manager: Dan Hon, @danhon and LinkedIn
- Technical Architect: Michal Migurski, @migurski and LinkedIn
- Interaction Designer / User Researcher / Usability Tester: Frances Berriman, @phae and LinkedIn
- Backend Web Developer: Erica Kwan, @pui and LinkedIn
- Delivery Manager: Kay Chung, @kerrching and LinkedIn
A photograph of our team doing a remote standup in Sprint 2:
The agile delivery process used at Very Little Gravitas is based on the open standards Scrum framework, with input and iterative feedback from user-centered design techniques.
Our wiki documents our full agile delivery process.
For this RFI, we implemented a simplified process, appropriate to scope and available time. The following describes the work delivered in each of the four 1 week sprints completed in building the prototype.
- Defined usecases & personas
- Discussed and clarified requirements
- User research journal
- Design exploration
- Technical exploration
- Set up a Slack group for team communication
- Set up a kanban board in the team’s repository as a lightweight product backlog and sprint task board
- User interface and user flow visualizations
- Set up page templates
- User profile creation and management
- Emergency notification send and receive - test
- Set up step-through templates for admin view
- Notification signup
- Edit geo-location criteria for notifications
- Selection of delivery format - SMS and email
- Implemented Google Analytics
- Reassess issue priorities and assign stretch label to stories out of prototype scope
- Finalized prototype documentation
- Finalized copy for the prototype application
- Customer support contact and issue reporting for user
- Administrator user research
- Implemented email delivery
- Implemented stories for tracking, analyzing, visualizing data
- Reassessed issue priorities and assign stretch label to stories out of prototype scope
- Implemented administrator map UI improvements (stretch)
We used these user-centered design techniques:
- User surveys, to better understand the expectations of a wide number of potential users of our system (quantitative research)
- Personas, to create representative archetypes of our users
- Interviews, to ask in more detail focussed questions about user expectations (qualitative research)
- Interactive user testing, to see if real users could successfully use our service
CA Alerts is a Python 3 web application built using the Flask micro web framework. Users use the application via a web front-end that uses the U.S. Web Design Standards pattern library.
On the CA Alerts homepage, users can:
- register
- sign in
- sign in as an administrator
The application router __init__.py defines the addresses/routes and HTTP methods implementing the application's functionality. HTTP methods (GETs, POSTs etc) on routes result in running the appropriate code. Routes are rendered in HTML by the Jinja templating engine. The Python module Psycopg is used to connect to the application database. The application database is a PostgreSQL database with the PostGIS extension for geolocation support.
Following the separation of concerns pattern, certain application functionality imported through Python modules in the application's data directory:
- users.py (create, read, update, delete (CRUD) user methods on the application database, verify user identity via appropriate Twilio and Mailgun APIs, managing user profile information etc.)
- zipcodes.py (return a zipcode for a given latitude and longitude)
- wildfires.py (wildfire data parsing, storing wildfire information in the application database, returning a list of current fires, returning individual fires)
- notify.py (notification functions, setting up third party API credentials, returning a list of geofenced users to notify, send notifications via third party APIs, notification logging)
Public users register by entering a phone number and a zipcode in an HTML form. The zipcode is entered manually or retrieved using the HTML geolocation API.
Submitting the form as an HTTP POST to the application web server calls the appropriate route to
- create an (unregistered) user in the application database
- generates a PIN confirmation code
- send the PIN confirmation code via the Twilio SMS API to the user phone number
- redirect the user browser to a confirmation URL
The user enters their confirmation code at a unique confirmation URL to verify their phone number.
Verified public users (who have entered the correct PIN code) may edit their profile and add an email address. If they choose to receive notifications by email, the Mailgun API is used to deliver email notifications.
Public user login is two-factor authentication. Users log in by supplying something they know (a confirmation code sent by email or SMS) and something they have (access to a phone number or email address).
Admin users manually publish notifications using an HTML form. An emergency notification HTML form is HTTP POSTed to the appropriate route creating a notification object, calling the required functions to send notifications using the appropriate APIs and logs the notification in the application database.
Emergency and related data is displayed using a Leaflet.js map interface on the CA Alerts homepage and in the Admin interface. The application uses a Python object representing emergency data, generated from emergency data stored in the application database. The object is serialized to JSON and delivered inline in the HTML response by the application server when a browser requests a page containing the map template.
On the backend, a scheduled task provided by our PaaS (Heroku) runs a collection script (collect.py) every hour to
- GET the data at the provided URLs from the prototype data source ESRI feature servers
- store returned data in the application database
- identify users within 50 miles of fire points within California
- send emergency notification to those users
- log sent notifications
- Project wiki
- Design exploration
- Research journal
- US Digital Services Playbook approach
- Product Backlog and Sprint Taskboard
The RFI explicitly identifies 20 requirements (a-t) for the prototype submission. Without duplicating the headings, we provide evidence below of how we have met each criteria:
a. We appointed Dan Hon as both Product Manager and leader of the project. He helped the team understand the requirements, was responsible for prioritizing work, and is ultimately accountable for the quality of the submitted prototype
b. Section 2 (above) identifies each member of our multidisciplinary team and their labor category.
c. We surveyed over 30 potential users of the service, and conducted detailed interviews with a number of individuals. Insights from these exercises were used directly in design exploration and reflected in the implementation of requirements. See our research journal.
d. We used 4 user-centered design techniques in Section 4 (above).
e. The project commit history is in Github.
f. Swagger documentation for our RESTful API.
g. Commit history shows how user-facing templates were implemented using standards compliant, accessible, semantic HTML using Progressive Enhancement. The U.S. Web Design Standards were used, which are fully compliant with ADA and WCAG 2.0
h. We used the U.S. Web Design Standards as style guide and/or pattern library. Pull Request 13 shows implementation.
i. Our research journal documents usability testing videos and notes from interviews.
j. The lightweight scrum process we used provided a review point at the end of each sprint, enabling us to reflect users' feedback in the planning session of the next sprint. We iteratively produced features reflecting real users' requirements. See Section 3 (above) for further detail.
k. Using the U.S. Web Design Standards with no custom HTML or CSS ensures a responsive design on multiple devices.
l. We are using the following modern, open-source technologies:
- Python 3.
- Flask, a micro web framework for Python based on Werkzeug, the WSGI toolkit, and Jinja 2, a templating language based on Django's templating approach. The framework features integrated support for unit testing and RESTful request dispatching.
- PIP for ensuring the correct Python packages are installed to support the application
- PostgreSQL 9, an enterprise-grade database.
- psycopg as the PostgreSQL adapter for Python.
- Swagger to document APIs
- PostGIS, a spatial database extender for the Postgres database with support for geographic objects, allowing for SQL location queries.
- Leaflet.js, an open-source JavaScript library for interactive maps.
- The U.S. Web Design Standards, which provides design guidelines and code to quickly create trustworthy, accessible and consistent digital government service, meeting Web Content Accessibility Guidelines.
- Heroku as production PaaS.
- Travis CI, for continuous integration and testing.
- Twilio for sending SMS notifications.
- Mailgun for sending email notifications.
- Slack for team collaboration and chat.
- Docker for containerization.
- Pingdom for continuous monitoring of the production website.
m. The production application is deployed on the Heroku PaaS. Issue 3 shows setup of the Heroku deployment pipeline. The master branch is automatically deployed to https://alerts-ca.herokuapp.com.
n. We have a master list of unit tests, automated tests are run by Travis CI, build and test results are public
o. Travis CI provides continuous integration, automatically and continuously deploying the master branch to https://alerts-ca.herokuapp.com. Issue 3 documents initial setup.
p. Configuration management is implemented in an env-vars file that is used in production on Heroku, in development and for running the Docker image
q. CA Alerts is continuously monitored using Pingdom with a public uptime report.
r. CA Alerts has been built with Docker: a single Docker image includes PostgreSQL, the CA Alerts web application and required dependencies. The production application is deployed on the Heroku PaaS. Learn how to use the Docker image.
s. Learn how to install and run the prototype.
t. Our work and code for this prototype is licensed under the MIT License.