Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
.jhipster
.mvn/wrapper
documents
src
.bowerrc
.editorconfig
.jshintrc
.juml
.travis.yml
.yo-rc.json
Gruntfile.js
README.md
bower.json
mvnw
mvnw.cmd
package.json
pom.xml

README.md

CWS Parent Portal

ADPQ prototype URL: CWS Parent Portal

Continuous Delivery
Monitoring
Code Quality
JIRA Please use user name: viewer, password: viewer
U.S. Digital Service Playbook compliance

User guide

Application provides several roles with different capabilities: PARENT, CASE_WORKER and ADMIN.
After registration and activation of account using email, user receives role PARENT.

To login without registration please use demo users below
Demo user with role PARENT:
- name: parent, password: parent
Demo uses with role CASE_WORKER:
- name: worker, password: worker
- name: maryjenkins, password: worker


Technical approach

1. Project Goals, Objectives, and Task Definition

EngagePoint understands the design, development, and implementation required to develop a prototype (using open source technologies) in which foster parents perform case-related functions. This prototype, an automated modern web application, scales horizontally and can be deployed to an Infrastructure as a Service (IaaS) or Platform as a Service (PaaS) provider.

2. User-centric design approach

EngagePoint applied user-centric design principles in creating the prototype by following the US Digital Services Playbook. See the responses in Playbook (Play 1 - Play 3) and Requirements C - F for information.

3. Agile Methodology

To implement the prototype, we modified our Scrum methodology to align with the user-centric design. Our approach is detailed in our response to Requirement G and US Digital Services Playbook Play 4.

4. Technical architecture

EngagePoint selected the Java Virtual Machine (JVM) platform and Java 1.8 as the prototype's programming language. The JVM platform is commonly used in high-load web applications, such as Google. However, small prototype web applications can be created quickly and then transitioned to production usage on the same technology platform without having to rewrite the application.

Using the JVM platform for prototype development is the correct choice due to scalability and maturity of Java as an industry standard.

We adhere to these factors to maximize performance:

  • Leverage a generic application platform for prototype construction
  • Use code generators rather than boilerplate code
  • Minimize time for the code-compile-test-deploy cycle

To minimize risk, we considered these factors for each system architecture component:

  • Maturity level
  • Success stories
  • Documentation quality
  • Cloud readiness
  • Performance metrics
  • Maintenance costs

4.1. Application Platform

EngagePoint used the open source code generator JHipster, which let us generate a production-ready application using Spring Boot and AnglarJS, which contain monitoring, logging, configuration, and user management functionality.

JHipster lets us choose technologies based on project requirements. For the prototype, EngagePoint chose this technology stack:

Architectural diagram

4.2. Rationale

The table below lists EngagePoint's architectural design decisions and their alignment with the functional and non-functional prototype requirements.

Application Requirements Technologies Motivation and rationale
Modern Web Application HTML5, CSS3, AngularJS AngularJS has decent documentation and an active GitHub community with lots of open components
Responsive UI Bootstrap Simplifies responsive UI implementation complexity providing CSS and JS.
Allow foster parents to communicate with the case worker via a private inbox Elasticsearch, PostgreSQL, Websockets, HibernateORM Elasticsearch implements search capabilities needed for inbox functionality like full-text search, relevancy, ranking, and fuzzy search.
- We are using the relational database for the persistence of messages in the private inbox. Prototype is database agnostic. PostgreSQL is our open source choice.
- Websockets technology is used for real-time notifications for new messages.
Allow foster parents to view children's residential facilities in their zip code Leaflet Mapzen Search - Leaflet is the leading open-source JavaScript library for mobile-friendly interactive maps.
- Mapzen Search is an open source geocoding tool used for address lookup capabilities.
Allow foster parents to establish and manage their profile JHipster Hazelcast - Generic JHipster application has built-in login, registration, and user profile functionality. EngagePoint has customized the generic implementation.
- Hazelcast is a distributed data grid used for distributed cache capabilities and performance improvement of the application. For the prototype, we are storing user sessions as well as L2 Hibernate cache.
Automated deployment to IaaS, PaaS Spring Boot, Docker, Jenkins - Spring Boot provides DevOps tools like externalized configuration, monitoring, and logging. Spring Boot eliminates the need to use external application containers, simplifying cloud deployment.
- Docker containers are used for all components of application infrastructure (application, Elasticsearch server, PostgreSQL server). Containerization helps with automated deployment and makes application environments agnostic.
- Jenkins is an open source tool used to implement continuous integration and delivery.

4.3. Development Tools

JHipster provides tools that accelerate development and minimize custom coding. Entity Generator supports application prototyping, allowing the Technical Architect to describe the Entity Relational Diagram using JDL (domain specific language). Based on JDL, JHipster generates boilerplate code for simple CRUD operations with these entities: Liquibase scripts for database objects, Hibernate entities, repository classes, Java REST resources, AngularJS controllers, REST client services, routers, unit tests for Java and JavaScript, and sample administrative UI.

The prototype has two Maven profiles: DEV and PROD. The DEV profile is used on the local development environment and incorporates in-memory H2 and Elasticsearch engines. Spring Boot provides an embedded lightweight application container, Tomcat, which runs the prototype. We used Browsersync and Spring Boot Devtools for automated reload of front-end and back-end code. These techniques reduce development time as developers view real-time updates. The PROD profile builds the prototype's production version, which is optimized for production use.

4.4. Automated testing

These automated testing tools ensure that the prototype meets California's requirements:

4.5. Deployment Approach

We used Jenkins as a continuous integration and delivery tool. Containerization using Docker is the best approach for application delivery to target environments. Please refer to Requirements J, L-O in Reference section for information.

5. Summary

EngagePoint conducted these prototype implementation steps:

  1. Performed 1:1 interviews and documentted results
  2. Developed an interactive wireframe and performed usability testing with users
  3. Developed user interface mock-ups using U.S. Web Design Standards in compliance with ADA508
  4. Generated a generic web application using JHipster with an appropriate technology stack
  5. Configured continuous integration and automated testing using Jenkins
  6. Designed a data model and generated code artifacts using JHipster's entity generator
  7. Developed custom user interfaces according to design mockups and integrated them into a generic application
  8. Modified the front-end and back-end code to support ADPQ functionality

For each development stage, we created automated tests (and performance and acceptance tests) for Java and JavaScript code. SonarQube controlled code quality, incorporated in an automated continuous delivery workflow that was implemented in Jenkins. We also manually reviewed code to ensure quality. With this approach, we implemented a modern, mobile friendly, cloud-ready web application in only three weeks.


References

# Requirement Description
1. a. Assigned one leader and gave that person authority and responsibility and held that person accountable for the quality of the prototype submitted. Agile ADPQ Product Manager (Margreta)
2. b. Assembled a multidisciplinary and collaborative team that includes, at a minimum, five of the labor categories as identified in Attachment C - ADPQ Vendor Pool Labor Category Descriptions. - Agile ADPQ Product Manager (Margreta)
- Delivery Manager / Technical Architect (Leonid)
- Interaction Designer (Dariia)
- Business Analyst / User Researcher (Pavel)
- Security Engineer (Dmitry)
- DevOps Engineer (Dmytro)
- Front End Developer (Yevhen, Oleksander)
- Back End Web Developer (Oleg, Alexander, Alexander, Serge)
3. c. Understood what people needed, by including people in the prototype development and design process EngagePoint listened to user needs and reviews and incorporated users' perspectives in the development process. After initial review and initial scope design, the information and understanding of needis discussed with the stakeholders (users). EngagePoint identified two users (Shelly & Kacie) to function in this role for our effort. The initial interviews ( Shelly & Kacie) resulted in a high level identification and validation of needs.Additional interviews with users provided feedback on the prototype development as well as additional clarification on specific features and interactionsexpected with the system. Feedback sessions provided specific recommendations on what information is of value (examples include feedback regarding facility search features and the specifying the types of communication needs that should be supported between the parent and the caseworker). Other users were also included in reviewing the wireframes and providing feedback on how a specific action might be performed.
4. d. Used at least three "human-centered design" techniques or tools During application prototype development we used the following "human-centered design" techniques and tools.
- User Interview
- Expert Interview
- User Needs
- User Personas
- User Stories & Scenarios
- Wireframing
- Usability Testing
- Design mockups
For our team, interactive wireframes play an important part in human-centric design approach. Wireframes provide the ability to quickly prototype and validate design ideas with users. The interactive wireframe is also a useful input for the application development team. Properly organized design stage activities minimize the need to rework the actual application in later stages, when the cost of changes will be much more expensive. Additional information regarding the EngagePoint Design process can be found within the UX Design Process.
5. e. Created or used a design style guide and/or a pattern library EngagePoint used the U.S. Web Design Standards to track with industry-standard web-accessibility guidelines alongside best practices of existing style libraries and modern web design. U.S. Web Design Standards provided a guide for creating visually appealing and easy-to-use online experiences for the American people.
6. f. Performed usability tests with people With the iterative design approach, usability testing was performed iteratively. The initial usability tests asked general users to perform specific tasks, per the scenarios, within the Axure prototype. Feedback was also gathered regarding the overall interface look and feel, expected navigation behavior, and expected results of actions. Usability also addressed overall satisfaction with the design according to the overall goals identified.See artifacts within UX Design Processfor user feedback, including local users input.Within the development effort, specific tasks have been divided into particular steps. These steps are documented in JIRA for traceability. The prototype testing process is thus supported and repeated within the development process.
7. g. Used an iterative approach, where feedback informed subsequent work or versions of the prototype See the Agile Approach Overviewfor a description of the iterative process used. According to the methodology, we have used a short, two-day iteration for the Design Group and a one-week iteration for application prototype development. Three times a week we held Design Sessions to review wireframes, to review design mockups, and to gather feedback from team members on design artifacts. Examples include recorded design sessions and meeting notes.Every week we held a Sprint Demo meeting to demonstrate the application prototype in front of the Product Manager and other interested stakeholders. Notes and action items are captured in Sprint Demo meeting notes. Per our user-centric design approach, we focused on users' input and feedback. We conducted regular interviews with the people defined in item C above, as well as usability testing with other users. Interview transcripts and recordings of interviews can be found in GitHub repository. Based on user's feedback we iteratively evolved wireframes.

Over the course of three weeks, the development team has implemented three versions of application prototype: 0.1, 0.2, and 1.0.
8. h. Created a prototype that works on multiple devices, and presents a responsive design Along with wireframes for the desktop version, we also maintained a wireframe for a mobile version http://zfsh7d.axshare.com/inbox.html, http://ive2qq.axshare.com/home.html (Password: 123654789). Based on the wireframes, we produced design mockups for a mobile version. Both wireframe and design mockups became requirements for the final application.To implement a responsive UI in the application prototype, we used the Bootstrap framework. Bootstrap is an HTML, CSS, and JS framework for developing responsive, mobile first projects on the web. It provides the mechanisms necessary to implement application user interfaces that vary according to device resolution. See the list of Axure mockups within UX Design Process.
9. i. Used at least five modern (see Note #2) and open-source technologies, regardless of architecturallayer(frontend, backend, etc.) EngagePoint used the following open-source technologies in creating this prototype application. The list includes the named technologies, their versions, and links to the website with release notes or proof of date of release.Frontend (files package.json for NPM packages and bower.json for Bower packages)
- Bootstrap 3.3.5: release 06/15/2015
- UI Bootstrap 1.2.5: release 03/20/2016
- AngularJS 1.4.8: release date 11/20/2015
- Bower1.7.9: released 04/05/2016
- Grunt0.4.5: released 05/12/2014
- Karma JS 0.13.19: release 02/12/2016
Backend (dependencies and versions are in Maven pom.xml file)
- Spring Boot 1.3.1: release 12/18/2015
- Elasticsearch 1.5.2: release 04/27/2015
- Hazelcast 3.5.4: release 11/25/2015
- Liquibase 3.4.2: release 11/24/2015
10. j. Deployed the prototype on an Infrastructure as a Service (Iaas) or Platform as Service (Paas) provider, and indicated which provider they used. Amazon cloud is the deployment target for the prototype application.Two types of environment were implemented:
1. Traditional EC2 based environment with Linux based instance.
In this case we created a Virtual Machine (VM) based on any Linux image which supports Docker engine. After creating the VM we install Docker Engine and Docker compose. The Prototype is deployed based on the Docker Compose file, which creates, configures, and runs the application itself; all necessary requirements; and the Load Balancer. We can scale the Prototype's container count, which will be handled by Load Balancer automatically.
2. Clustered environment based on EC2 Container Service (ECS)
In this case for the Prototype, we create ECS cluster based on Auto Scaling Group (ESG) of EC2 instances with Elastic Load Balancer (ELB). We can configure various rules in ESG to add and remove EC2 instances based on the current workload or defined schedule.
11. k. Developed automated unit tests for their code To eliminate functional regression and ensure that the application remains in compliance with requirements, we used different levels of automated testing:
- Java unit tests using JUnit - Jenkins job
- Java integration tests using Spring Boot integration testing tools - Jenkins job
- JavaScript unit tests using Karma JS - Jenkins job
- Load testing using Gatling - Jenkins job
- Acceptance testing using BDD framework Cucumber - Jenkins job
12. l. Setup or used a continuous integration system to automate the running of tests and continuously deployed their code to their IaaS or PaaS provider. Continuous integration framework tools: Jenkins, Sonar. Configured instance of Jenkins is available for review. Instance of Sonar with history and current project status available for review.High-level description of the Jenkins jobs workflow:
- Build source code
- Run series of tests:
- Java unit tests
- JavaScript unit tests
- Sonar code analyze
- When all the previous tests pass, deploy to Development environment in Amazon Web Service
- Run acceptance tests based on Cucumber
- Run load tests based on Gatling
- When all tests pass, deploy into high availability production environment in Amazon Web Services
13. m. Setup or used configuration management Prototype configuration was implemented based on Spring Boot, giving us the ability to change parameters in different ways such as with Environment variables, command line parameters, and so on. Since we deliver the Application using Docker containers, we use Environment variables as the configuration method.To restrict access to a private information like links to required dependencies, credentials, and so on, we distinguish configuration in separate Git repository. Deployment jobs check out the necessary configuration files and configure the Prototype for the target environment.
14. n. Setup or used continuous monitoring Continuous monitoring was implemented by the synergy of built-in AWS containers tools for hardware items and Zabbix for application specific parameters.In addition to built-in AWS monitored items like CPU, memory, etc. following Application-specific parameters monitored by Zabbix for every container:
- JVM memory details (Heap, Non-Heap)
- Datasource connection parameters (Active, Idle connections)
- REST services statistic
- Threads statistic (Deadlock, Waiting)
15. o. Deployed their software in a container (i.e., utilized operating-system-level virtualization) The Prototype is delivered as Docker container image. It requires PostgreSQL DB and Elasticsearch as external dependencies. The Prototype can be configured to use dependencies as external services or as linked Docker containers.
16. p. Provided sufficient documentation to install and run their prototype on another machine To install and run the prototype on another machine, we provide several available options such as a Docker-based deployment and a compilation of the prototype from source code.

Start application using Docker

We have published a Docker image with the application prototype to the Docker Hub. To run the Docker image on another machine, complete the following steps:
1. Install Docker Toolbox on your machine
2. Start Docker Quickstart Terminal or use graphical tool Kitematic(Alpha)
3. Download docker compose file for standlone ( chhs-apqd -full.yml ) or high availability ( chhs-apqd-ha.yml) solution.
4. Change spring_mail_host parameter in yml file to your e-mail server. Without email server, the application will not be able to send account activation emails so user registration will be not functional. In order to test the application capabilities without email server shall use system users.
Role Parent: username: parent, password: parent
Role Case Worker: username: worker, password: worker
Role Administrator: username: admin, password: admin
5. In Docker Terminal run the following command line: docker-compose f <full-path-to-file>/chhs-apqd-<ha or full>.yml up -d
Please wait 1 to 5 minutes for application start depends on network connection.
6. If you have Windows environment, you can open Kitematic (Alpha) and click on Web Preview to open application in the browser. In the Linux, application will be available by default URL http://127.0.0.1:8080/#/ (for Full) or http://127.0.0.1:24080 (for HA)
7. For high availability (HA) configuration (chhs-apqd-ha.yml) you can scale application. For this in Docker terminal run command line: docker-compose scale chhs-apqd-ha=n
, where n is desired quantity of Application's containers.

Compile application from source code and start (any operation system)

To compile the application from source code, you will need to setup and configure a development environment using the steps below:
1. 1.Install Java Development Kit (JDK) version 8 from the Oracle website.
2. Install Java dependency management tool Maven from official Maven website
3. Install Git from git-scm.com
4. Clone the project source code from the GitHub repository https://github.com/engagepoint/chhs-apqd
5. Install Node.js from the Node.js website. This will also install npm, which is the node package manager we are using in the next commands.
6. Navigate to the Git repository folder chhs-apqd
7. Install Yeoman using the command line: npm install -g yo
8. Install Bower using the command line: npm install -g bower
9. Install Grunt using the command line: npm install -g grunt-cli
10. Install JHipster using the command line: npm install -g generator-jhipster

When the development environment is configured, you can compile and run the prototype application by following the steps below:
1. From Git repository folder chhs-apqd, run Maven command: mvn spring-boot:run
2. The application will be automatically started on http://127.0.0.1:8080/#/ in 2-10 minutes dependse on performance of your machine
17. q. Prototype and underlying platforms used to create and run the prototype are openly licensed and free of charge EngagePoint has used only open source technologies and platforms for prototype creation. Key technologies with links to source code and license type are described below:
1. Client side:

- Bootstrap 3.3.5: source code , MIT License
- UI Bootstrap : source code , MIT License
- AngularJS: source code, MIT License
- Leaflet: source code, BSD 2-Clause License
- Mapzen: source code, MIT License

2. Server Side:
- Spring Boot: source code, Apache License Version 2
- Spring Framework: source code, Apache License Version 2
- Spring Security: source code, Apache License Version 2
- Spring Data JPA: source code, Apache License Version 2
- Spring Data Elasticsearch: source code, Apache License Version 2
- Hibernate ORM : source code , LGPL V2.1
- Elasticsearch: source code, Apache License Version 2
- PostgreSQL: source code, PostgreSQL Licence open license similar to BSD or MIT
- Hazelcast: source code, Apache License Version 2