Merge pull request #148 from labzero/develop

Production Release March 1, 2017

.babelrc

@@ -0,0 +1,3 @@
+{
+  "presets": ["es2015", "es2016", "es2017", "stage-1", "react"]
+}

.credo.exs

@@ -0,0 +1,19 @@
+# config/.credo.exs
+%{
+  configs: [
+    %{
+      name: "default",
+      files: %{
+        included: ["lib/", "src/", "web/", "apps/"],
+        excluded: []
+      },
+      checks: [
+        {Credo.Check.Consistency.TabsOrSpaces},
+        {Credo.Check.Design.TagTODO, exit_status: 0},
+        {Credo.Check.Readability.Specs, false},
+        {Credo.Check.Consistency.MultiAliasImportRequireUse, false},
+        {Credo.Check.Readability.MaxLineLength, priority: :low, max_length: 100},        
+      ]
+    }
+  ]
+}

.dockerignore

@@ -0,0 +1,4 @@
+_build
+deps
+node_modules
+test

.eslintignore

@@ -0,0 +1 @@
+/test

.eslintrc.json

@@ -0,0 +1,24 @@
+{
+    "parser": "babel-eslint",
+    "parserOptions": {
+      "sourceType": "module",
+      "allowImportExportEverywhere": false
+    },
+    "extends": "airbnb",
+    "plugins": [
+        "react"
+    ],
+    "rules": {
+      "strict": 0,
+      "react/jsx-filename-extension": "off",
+      "no-use-before-define": "off",
+      "comma-dangle": "off",
+      "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }] ,
+      "react/require-default-props": "off",
+      "react/prefer-stateless-function": "off",
+      "react/forbid-prop-types": "off",
+      "jsx-a11y/no-access-key": 2,
+      "jsx-a11y/href-no-hash": 2,
+      "jsx-a11y/img-has-alt": 2   
+    }
+}

.gitignore

@@ -22,3 +22,8 @@ erl_crash.dump
 # secrets file as long as you replace its contents by environment
 # variables.
 /config/prod.secret.exs
+
+.DS_Store
+.idea/
+
+npm-debug.log*

Dockerfile

@@ -0,0 +1,32 @@
+FROM bitwalker/alpine-elixir-phoenix:latest
+
+# Install dependencies
+RUN apk add --no-cache python=2.7.12-r0 make gcc g++
+
+# Build Environment
+ARG RDS_PASSWORD
+
+ARG MIX_ENV
+ENV MIX_ENV ${MIX_ENV:-prod}
+ARG RDS_PASSWORD
+ENV RDS_PASSWORD ${RDS_PASSWORD:-nopassword}
+
+# Set exposed ports
+EXPOSE 4000
+ENV PORT=4000
+
+# Cache elixir deps
+ADD mix.exs mix.lock ./
+RUN mix do deps.get, deps.compile
+
+# Same with npm deps
+ADD package.json package.json
+RUN npm install
+
+ADD . .
+
+# Run frontend build, compile, and digest assets
+RUN brunch build --production && \
+    mix do compile, phoenix.digest
+
+CMD ["mix", "do", "ecto.migrate,", "phoenix.server"]

PLAYBOOK_ADHERENCE.md

@@ -0,0 +1,55 @@
+# US Digital Services Playbook Adherence
+
+Lab Zero’s existing product design and development approach aligns closely with the US Digital Services Playbook. Our prioritized [Prototype Design](https://github.com/labzero/adpq/projects/2) and [Prototype Dev](https://github.com/labzero/adpq/projects/1) backlogs within GitHub show how the activities in our iterative and collaborative process from discovery to delivery and deployment. We make reference within many Product Design cards to the Playbook activity, as well (noted as “PB”).
+
+In addition, below are key activities and artifacts relative to the Digital Service Plays:
+
+## Play 1: Understand what people need
+* Drafted open-ended discovery interview scripts for key personas [Requester Interview Script](https://github.com/labzero/adpq/blob/develop/docs/interviews/00TemplateOpen-endedInterviewScriptforRequester.pdf), [Admin Interview Script](TBD)
+* Interviewed representative users, documented & shared learnings [Dennis Baker](https://github.com/labzero/adpq/blob/develop/docs/interviews/Interview1.1DennisBaker-StateAssemblyReprographicsManager.pdf), [Robert Lee](https://github.com/labzero/adpq/blob/develop/docs/interviews/Interview2.1RobertLee-StartupOfficeManager.pdf), [Ned holets](https://github.com/labzero/adpq/blob/develop/docs/interviews/Interview3.1NedHolets-CMSDeveloper.pdf)
+* Utilize existing large scale quantitative eCommerce research through the Baymard Institute [Ecommerce Usability Guidelines](https://github.com/labzero/adpq/blob/develop/docs/research/RelevanteCommerceUsabilityGuidelines.pdf), [Shopping & Procurement Research](https://github.com/labzero/adpq/blob/develop/docs/research/ShoppingandProcurementResearch.pdf) 
+* Outline Full Persona List to note all roles likely involved in the full experience [Link](https://github.com/labzero/adpq/blob/develop/docs/personas/00FullPersonasList.pdf)
+* Focus on and define State Agency Requester as primary persona [Link](https://github.com/labzero/adpq/blob/develop/docs/personas/01StateAgencyRequesterPersona.pdf)
+* Focus on and define Lead Purchasing Org web admin as secondary persona [Link](https://github.com/labzero/adpq/blob/develop/docs/personas/02DataAdminPersona.pdf)
+* Capture & prioritize needs as user stories [Link](https://github.com/labzero/adpq/projects/1)
+* Regularly test to validate problem/solution fit [Robert Lee](https://github.com/labzero/adpq/blob/develop/docs/interviews/Interview2.2RobertLeeConceptTest.pdf), [Tracey Thompson](TBD)
+
+## Play 2: Address the whole experience, from start to finish
+* Illustrated on- & off-line touch points and align team on key points of impact & focus
+* Stated project summary, goals, & metrics to ensure the effort meets needs [Product Speclet](https://github.com/labzero/adpq/blob/develop/docs/Product%20Speclet.pdf)
+
+## Play 3: Make it simple and intuitive
+* Consistently utilized US Web Design Standards
+* Followed accessibility best practices [Readme, G](https://github.com/labzero/adpq/blob/develop/README.md)
+* Leveraged login to provide users with a way to exit and return later to complete process
+* Improved readability by re-formatting and adjusting sample data [Data Spreadsheet](TBD)
+
+## Play 4: Build the service using agile and iterative practices
+* Shipped a functioning MVP
+* Frequently ran usability tests to identify improvements [Interviews](https://github.com/labzero/adpq/tree/develop/docs/interviews)
+* Facilitated team alignment & communication through daily standups, [weekly demos/retros](https://github.com/labzero/adpq/tree/develop/docs/retrospective), & [Slack channel](https://github.com/labzero/adpq/blob/develop/docs/Collaboration%20work%20sample%20-%20Slack%20conversation.jpeg)
+* Kept the delivery team flat & focused [Kickoff deck](https://github.com/labzero/adpq/blob/develop/docs/Prototype%20A%20Kickoff%20deck.pdf)
+* Drafted a prioritized features backlog and review with team [Link](https://github.com/labzero/adpq/projects/1)
+
+## Play 6: Assign on leader and hold that person accountable
+* Assigned experienced Product Owner accountable for project [Readme, A](https://github.com/labzero/adpq/blob/develop/README.md)
+
+## Play 7: Bring in experienced teams
+* Assembled a team experienced building similar applications in a modern fashion [Readme, B](https://github.com/labzero/adpq/blob/develop/README.md)
+
+## Play 8: Choose a modern technology stack
+* Modern technology stack chosen [Readme, L](https://github.com/labzero/adpq/blob/develop/README.md)
+
+## Play 9: Deploy in a flexible hosting environment
+* Deployed in a flexible hosting environment [Readme, M](https://github.com/labzero/adpq/blob/develop/README.md)
+
+## Play 10: Automate testing and deployments
+* Testing & deploys automated [Readme, O](https://github.com/labzero/adpq/blob/develop/README.md)
+
+## Play 12: User data to drive 
+* Monitoring system performance [Readme, Q](https://github.com/labzero/adpq/blob/develop/README.md)
+
+## Play 13: Default to open
+* Utilized open source 
+
+

README.md

@@ -1,3 +1,10 @@
 # Adpq
 
 [Setup Instructions](SETUP.md)
+
+[Technical Approach](TECHNICAL_APPROACH.md)
+
+[Requirements List](REQUIREMENTS_LIST.md)
+
+[Playbook Adherence](PLAYBOOK_ADHERENCE.md)
+

REQUIREMENTS_LIST.md

@@ -0,0 +1,102 @@
+Requirements List
+
+**a. Assigned one (1) leader and gave that person authority and responsibility and held that person accountable for the quality of the prototype submitted**
+> Aaron Cripps, Product Owner
+
+**b. Assembled a multidisciplinary and collaborative team that includes, at a minimum, five (5) of the labor categories as identified in Attachment B: PQVP DS-AD Labor Category Descriptions**
+> The majority of the team is based in the San Francisco Bay Area. One member is in Tucson AZ, one member in Little Rock AR. Our team collaborates using tools like Slack, Google Hangouts, Screen Hero, GoToMeeting, and Google Docs. 
+* Product Manager - Aaron Cripps
+* Technical Architect - Sasha Voynow, Matt Wilson
+* Interaction Designer - Dean Baker, Clayton Hopkins
+* Visual Designer - Jim Ochsenreiter
+* Front End Web Developer - Adam Ducker, Jeffrey Carl Faden
+* Backend Web Developer - Sasha Voynow
+* DevOps Engineer - Brien Wankel, Dave O’Dell
+
+**c. Understood what people needed, by including people in the prototype development and design process**
+> Informed by our initial persona attributes, we found three individuals whose job activities aligned with or related to the Lead Purchasing Organization Administration and State Agency IT Requester roles. 
+* [Dennis Baker](https://github.com/labzero/adpq/blob/develop/docs/interviews/Interview1.1DennisBaker-StateAssemblyReprographicsManager.pdf), State of California Assembly Reprographics Manager
+* [Robert Lee](https://github.com/labzero/adpq/blob/develop/docs/interviews/Interview2.1RobertLee-StartupOfficeManager.pdf), Startup Office Manager
+* [Ned Holets](https://github.com/labzero/adpq/blob/develop/docs/interviews/Interview3.1NedHolets-CMSDeveloper.pdf), Lead Software Engineer who has worked on CMS projects
+
+**d. Used at least a minimum of three (3) “user-centric design” techniques and/or tools**
+> Human-centered design is a core aspect of our process. You can find a richer explanation of our processes here. Key examples listed below:
+* Customer Development activities
+  * Stating and prioritizing learning goals (hypotheses)
+  * Open-ended interviews with people who met our target personas to understand their needs and goals
+* In-person usability testing to validate solution ideas/hypotheses
+  * Clickable prototypes to support usability testing
+  * ‘Think aloud’ qualitative user test of prototype
+  * Accessibility test
+* Leveraging existing usability research 
+  * Baymard Institute, an ecommerce usability research firm whose methodology includes qualitative ‘Think aloud’ protocol and large scale eye-tracking study.
+
+**e. Used GitHub to document code commits**
+> Yes, we’ve used Github fully for peer-review and as our sole code repository.
+
+**f. Used Swagger to document the RESTful API, and provided a link to the Swagger API**
+> Yes, we’ve have implemented Swagger, you can view it [here](http://petstore.swagger.io/?url=http://staging.adpq.labzero.com/api/swagger_docs)
+
+**g. Complied with Section 508 of the Americans with Disabilities Act and WCAG 2.0**
+> Yes, we have used HTML and CSS in a manner that complies with the ADA and WCAG 2.0
+
+**h. Created or used a design style guide and/or a pattern library**
+* We utilized the US Web Design Standards for user experience, visual design and responsive guidelines and patterns.
+* We leveraged the Baymard Institute’s research-based user interaction guidelines for eCommerce product lists, homepages and checkout.
+
+**i. Performed usability tests with people**
+> We showed functional prototypes to the following individuals facilitated by a “Think Aloud” qualitative user test.
+* Robert Lee
+* Tracey Thompson
+
+**j. Used an iterative approach, where feedback informed subsequent work or versions of the prototype**
+> We began by clarifying the business case and target outcomes without proposing solutions. This empowers each team member to bring their expertise and creativity into the solutions which are iteratively built and tested. Learnings from test are fed back into subsequent iterations.
+* Product Owner led goal-oriented kickoff and drafted a first version of the “Speclet” to align and hold the team accountable to high-level key outcomes and measurements. 
+* Key learnings from user interviews informed the project summary, goals, and measurements and allowed us to apply improvements to our designs and development.
+* Team story time for formal technical review of prioritized backlog. Development feedback assisted in clarifying prototype behavior and story decomposition.
+* Validated design concepts through clickable prototypes with people outside the team. User feedback informed backlog grooming (through prioritization) and design iterations. 
+* Presented design, development, and product ideas to the full team frequently to inform final deliverables through daily standups and conversations.
+* Utilized Scrum framework for frequent and agile inspection and adaptation
+  * Product Owner managed a prioritized backlog of tasks for Design & Development
+  * Daily standup
+  * Weekly sprints: team performed demos and retrospectives
+
+**k. Created a prototype that works on multiple devices, and presents a responsive design**
+> Our prototype has been designed, developed and tested to work on desktop browsers, iOS and Android phones as well as screen readers.
+
+## l. Used at least five (5) modern and open-source technologies, regardless of architectural layer (frontend, backend, etc.)
+>We utilized many modern open-source technologies:
+* Elixir
+* Phoenix Framework 
+* Ecto (data layer)
+* React.js
+* Docker
+* SASS
+* Javascript/ES6
+* REST
+
+**m. Deployed the prototype on an Infrastructure as a Service (IaaS) or Platform as Service (PaaS) provider, and indicated which provider they used**
+> Our prototype has been deployed to AWS as a Docker container running in ECS using RDS for it’s datastore. 
+
+**n. Developed automated unit tests for their code**
+> The Engineering Team delivered stories with working code and some level of automated testing. All tests are run in the continuous integration loop with each. 
+* Javascript we wrote Jest tests (link)
+* Elixir we wrote ExUnit tests (link)
+
+**o. Setup or used a continuous integration system to automate the running of tests and continuously deployed their code to their IaaS or PaaS provider**
+> Our use of a CI server drives automated tests and our deployment pipeline. All new pull requests are tested. We used CircleCI to automate our CI and CD automation. 
+
+**p. Setup or used configuration management**
+> We generate CloudFormation templates and build Docker containers, adhering to a https://12factor.net/ approach.
+
+**q. Setup or used continuous monitoring**
+> We setup Honeybadger.io for error reporting and Pingdom for uptime monitoring. 
+
+**r. Deployed their software in an open source container, such as Docker (i.e., utilized operating-system-level virtualization)**
+> We build Docker containers in our CI/CD process and deploy them to ECR/ECS in AWS.
+
+**s. Provided sufficient documentation to install and run their prototype on another machine**
+> Please see the SETUP.md file in root directory of this repository. All engineers used these steps to set up their development environments. 
+
+**t. Prototype and underlying platforms used to create and run the prototype are openly licensed and free of charge**
+> All systems used to create and run the prototype are open source and free of charge for use. Our prototype carries an MIT license as well.

SETUP.md

@@ -5,23 +5,28 @@
 ### Software Versions
 
   * Elixir 1.4.1 (Erlang/OTP 19 [erts-8.2])
+  * Phoenix Framework 1.2.1
   * postgres (PostgreSQL) 9.6.2
+  * Node.js 7.5.0
+  * React 15.4.2
 
 ### MacOS
   1. Install Homebrew if not already installed `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
   1. Update Homebrew `brew update`
   1. Install postgresql `brew install postgresql`
+  1. Install node `brew install node`
   1. Install elixir `brew install elixir`
   1. Install mix `mix local.hex`
+  1. Create PostgreSQL role `createuser -d adpq`
+  1. Create and migrate schema `mix ecto.create && mix ecto.migrate`
+  1. To add seed data to your database: `mix run priv/repo/seeds.exs`
 
 ### Linux
 
 ## Starting the application
 
   1. Install dependencies with `mix deps.get`
-  1. Create and migrate your database with `mix ecto.create && mix ecto.migrate`
   1. Install Node.js dependencies with `npm install`
   1. Start Phoenix endpoint with `mix phoenix.server`
 
 Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
-

TECHNICAL_APPROACH.md

@@ -0,0 +1,36 @@
+# Technical Approach
+## Development Process
+We use the GitFlow branching model and create feature branches off of the develop branch for all new changes. All 
+commits should adhere to the guidelines described in our [commit guide](https://github.com/labzero/guides/blob/master/process/commit_guide.md). 
+Each feature branch is pushed to Github and a pull request is created, built and tested in CircleCI before peer-review 
+is performed by other developers on the team. Upon final approval by the dev lead, the branch will be squash-merged back 
+into develop.
+
+## CI Process
+PR phase looks for success for all of these steps:
+* Compilation and Docker container build
+* Credo (code quality/style analyser)
+* Unit tests
+
+## Continuous Delivery
+* Commits to develop trigger deployment to our Test environment
+* Upon deployment post-deploy automated testing it performed
+
+## Release Process
+Using GitFlow tooling, we create a release branch and tag. The tag is then used to create a new container image. A job 
+in Circle CI is used to deploy the tagged container to ECS in AWS.
+
+## Architectural Approach
+This web application will be built as a modern React.js app (Single Page Application) that consumes a JSON API backend 
+written in Elixir using the Phoenix framework and talking to a Postgres database. We considered using Shopify or Spree 
+but ultimately decided to build the prototype from scratch so that we could demonstrate our ability to write good custom
+ software with usable user interfaces that was designed after speaking with real users.
+
+![Cloud Architecture](docs/ADPQ-PrototypeA-Architecture.png)
+
+## Infrastructure Approach
+This application will be built in a cloud-first manner on AWS, but will be deployed as a Docker container in order to 
+allow cloud portability. However, if AWS offers a managed service for something we need, we will prefer the managed 
+service to rolling our own infrastructure. I.e. Postgres via RDS instead of running our own Postgres servers in EC2. 
+
+Our VPC and security blueprints will be maintained as CloudFormation templates and checked into Git.

brunch-config.js

@@ -22,7 +22,8 @@ exports.config = {
     stylesheets: {
       joinTo: "css/app.css",
       order: {
-        after: ["web/static/css/app.css"] // concat app.css last
+        before: ["node_modules/uswds/dist/css/uswds.css", "web/static/css/uswds-bugfixes.css"],
+        after: ["web/static/css/app.scss"] // concat app.css last
       }
     },
     templates: {
@@ -34,13 +35,16 @@ exports.config = {
     // This option sets where we should place non-css and non-js assets in.
     // By default, we set this to "/web/static/assets". Files in this directory
     // will be copied to `paths.public`, which is "priv/static" by default.
-    assets: /^(web\/static\/assets)/
+    assets: /^(web\/static\/assets)/,
+    // Ignore uswds.min.css
+    ignored: /\.min.css$/
   },
 
   // Phoenix paths configuration
   paths: {
     // Dependencies and current project directories to watch
     watched: [
+      "node_modules/uswds/dist/css/",
       "web/static",
       "test/static"
     ],
@@ -52,8 +56,15 @@ exports.config = {
   // Configure your plugins
   plugins: {
     babel: {
+      presets: ['es2015', 'es2016', 'es2017', 'stage-1', 'react'],
       // Do not use ES6 compiler in vendor code
       ignore: [/web\/static\/vendor/]
+    },
+    replacement: {
+      replacements: [{
+        files: [/\.css$/],
+        match: {find: '../img/', replace: '/images/'}
+      }]
     }
   },