Version 1.0 03/03/2017
Table of Contents
The California Alerts platform is a prototype that notifies California residents about emergencies happening near them. The platform is focused on two main users: the government administrator in charge of issuing alerts and the resident of California. The government administrator has access to features such as: a dashboard to visualize alert metrics as well as configure which alerts are made available to users. California resident features include: setting how they'd like to be alerted and selecting which alerts they'd like to receive.
Using the USDS Digital Playbook as a guide, user centered design methodology and agile development techniques, a functional prototype was developed. These practices are reflected and detailed within this README file.
How to install
You can access our GitHub repository: California Alerts
First clone the repository:
git clone firstname.lastname@example.org:shapeable/prototype-web.git
Enter the root folder for the application:
Install and update the gems:
Create the migrations of the databases:
Start rails server:
Start Redis Server
bundle exec sidekiq
Complete instructions can be found here
Each of the Technical Approach requirements outlined in Attachment B - ADPQ Vendor Pool Submission Requirements are addressed in the following document. We also followed the U.S. Digital Services playbook. The detailed notes of each play can be found here.
A. Assigned a team leader
Alan Mond, Product Owner
B. Team Members (and corresponding ADPQ labor categories)
- Product Manager: Diana D'Herrera
- Technical Architect: Rafael Cárdenas
- Interaction Designer/User Researcher: Diana D'Herrera
- Visual Designer: Sofía Moya
- Front End Developer: Isabel Anguiano
- Back End Developer: Miguel Morán
- Dev Ops Engineer: Giovanni Cortés
- Security Engineer: Rafael Cárdenas
- Agile Coach: Paulina Bustos
- Quality Assurance: Juan Pablo Escobar
C. Understood what people needed.
User research and testing was divided into three main methods following the human-centered design approach:
- Research of other platforms that offered similar solutions - Link
- Initial interviews with potential users - Link to interviews.
- Framing the design challenge - Link
- Downloading all the insights collected from interviews and online surveys.
- Team brainstorming sessions.
- Definition of an initial 'core features' list and a customer journey.
Creation of Mock-ups - Link
Initial mock ups reviewed with unassociated staff member to provide additional feedback on application behavior - Link
Final mock-ups with the implementation of user feedback - Link
Changes from former feedback were incorporated to design a final prototype design which was tested again in another focus group for validation. The design of the tests included 4 main tasks. - Link to user testing
In the absence of actual government administrator user responsibilities, access, and organization, we worked with the following assumptions:
- A government administrator doesn't have to create an account and log in to access all functionality due to the lack of authentication requirement.
- A government administrator would have access to all alerts.
- A government administrator can force alerts when needed.
The sig in tab is available for editing resident profile information, authentication is not required.
D. Used at least three “human-centered design” techniques or tools
Multiple human-centered design techniques were used in the development of the prototype. These included:
- Creative approach: Inspiration, Ideation, and Implementation.
- Creation of wireframes in Invision - Link to clickable Wireframes
- Creation of "user stories" in Github issues - Link to user stories
- Creating a Product Backlog list of prioritized "user stories" - Link to product backlog
- Design style guide. The official US digital services playbook was used as a reference https://playbook.cio.gov/ - Link to the guide
- Usability testing of wireframes - Link to user testing
- Usability testing of prototypes - Link to user testing
E. Used GitHub to document code commits
GitHub was used as the main documentation tool. User Stories were created under Issues to create a Product Backlog, a Project was generated to keep track of progress and all commits and comments were stored in the same repository. All design decision history has been documented in the repo. - Link to the master commits record .
F. Used Swagger to document the RESTful API, and provided a link to the Swagger API
Swagger was used to document the API in json format and are available in the following link: https://california-alerts.shapeable.net/api-docs.json
G. Complied with Section 508 of the Americans with Disabilities Act and WCAG 2.0
Accessibility Developer tools was used to determine the compliance for the requirements within Section 508. This Chrome extension adds an Accessibility audit, and an Accessibility sidebar pane in the Elements tab, to your Chrome Developer Tools. The audit results will appear as a list of rules which are violated by the page (if any), with one or more elements on the page shown as a result for each rule. If the inspected element has any properties relevant to accessibility, those properties will be displayed in the sidebar panel. The Section 508 website was consulted as a reference https://www.section508.gov/
Results of the accesibility audits for the application can be found under the accessibility_audit folder
H.Created or used a design style guide
A style guide was created by the UI designer with all the design elements present in the prototype. - California Alerts Styleguide
Other design elements and assets can be found here
I. Performed usability tests with people
Usability tests were performed at every step of the process.
- Testing of initial concepts - Link to interviews.
- Testing of initial wireframes - Link to user testing
- Testing of final prototype - Link to user testing tasks
J. Used an iterative approach, where feedback informed subsequent work or versions of the prototype
Our iterative approach worked as follows:
- Set up team collaboration in Slack
- Followed SCRUM methodology
- Set up of sprints and daily standups
- Regular team demos for feedback
- User testing and user feedback
- Fast iteration in the design process as feedback was given
- Review by Product Owner
K. Created a prototype that works on multiple devices and presents a responsive design
Our solution uses fluid grids that respond to most common desktop screen and devices, allowing flexible images and text resizing. We provide a clean interface which is compatible with most common web browsers and looks great on mobile devices.
The core of the responsive behavior can be observed in these sections:
- The grid - (4 tailored layouts) https://github.com/shapeable/prototype-web/blob/master/web-app/app/assets/stylesheets/base/_grid_settings.scss
- Fluid columns https://github.com/shapeable/prototype-web/blob/master/web-app/app/assets/stylesheets/base/_cols.scss
L. Used at least five modern and open-source technologies
Many open-source technologies were used to develop the prototype in alignment with recommendations from the U.S. Digital Services Playbook.
This is a list of the open-source technologies and the use given for the creation of the prototype.
- Docker - Production deployment
- Ruby on rails - Back end development
- Rspec - Test
- PostgreSQL - Database
- Redis - In-memory database
- Bourbon (for SCSS) - Style sheets
M. Deployed the prototype on PaaS
The staging prototype is deployed on a Heroku server which allows for quick deployments and all hardware updates and maintenance provided by Heroku. Additionally many services such as continuous monitoring are native add-ons that further simplify implementation and maintenance.
The production prototype is deployed on an Amazon Web Services (AWS) server. The instructions for deployment can be found here.
N. Developed automated unit tests
After creating unit tests for each feature or functionality, rspec was used as the automated unit tester. For example to test SMS (text messages) functionality, a specific unit test was created for that purpose: Send SMS Messages code
Other Unit tests can be found under: https://github.com/shapeable/prototype-web/tree/master/web-app/spec/modules
The percentage of the code base covered by automated tests was defined using Coveralls. Coveralls breaks down the test coverage on a file by file basis and allows one to see the relevant coverage, covered and missed lines, and the hits per line for each file. A higher percentage means a higher percentage of lines of code written are verified by a unit test.
The Coveralls dashboard could be found here
Code climate was also integrated for an automated code review which grades code quality. See full results here.
O. Setup or used a continuous integration system to automate the running of tests
We used Travis CI (Continuous Integration) server to run automated tests every time code was deployed to our Heroku staging instance. Travis CI is linked directly to the GitHub repo so it checks it automatically for any errors before being merged and deployed to production. The dashboard can be found here
P. Setup or used configuration management
We used Ansible as configuration management tool. Ansible is a radically simple IT automation engine that automates cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs.
Designed for multi-tier deployments since day one, Ansible models your IT infrastructure by describing how all of your systems inter-relate, rather than just managing one system at a time.
It uses no agents and no additional custom security infrastructure, so it's easy to deploy - and most importantly, it uses a very simple language (YAML, in the form of Ansible Playbooks)
Some of the advantages are
- Free and Open Source Software (FOSS)
- Integrating into Existing DevOps Workflows
- Network-Wide and Ad Hoc Changes
Q. Setup or used continuous monitoring
Rollbar was implemented as the continuous monitoring tool. Rollbar can be quickly added to any Ruby application as a gem and is also a standard add-on for Heroku deployments. It has a notification system built in that immmediately alerts the team if there are any errors.
R. Deployed their software in an open source container
The production prototype is deployed on AWS server using Docker container technology. Some of the advantages of using Docker are:
- Simplifying Configuration
- Code pipeline management
- Developer Productivity
- App Isolation
- Server Consolidation
- Debugging Capabilities
- Rapid Deployment
S. Provided sufficient documentation to install and run their prototype on another machine
The url of the docker hub is the following link https://hub.docker.com/r/shapeable/california-alerts/
T. Prototype and underlying platforms used to create and run the prototype are openly licensed and free of charge
The prototype is licensed under the MIT License. This license is permissive and free of charge.
U.S. Digital Playbook usage
Shapeable 2120 University Ave Berkeley, CA 94704 c: 510-662-6152 email@example.com
The prototype is licensed under the MIT License. This license is permissive and free of charge.
Copyright 2017 Shapeable