This is the repo for the Overwatch Challenge Open Source project.
Please check out the User Guide for visual instructions here.
This project provides an application that teams can use to gamify their learning processes.
- Users create "Activities" every time they learn something.
- Everyone comes together at the end of a week to see who scored the highest
- Admins maintain the scores
- Scores and activities are saved for future reference
This project uses Google's Firebase with the Angular Fire 2 Library for the following:
- Hosting
- Authentication
- Database Storage (Document Driven)
- Cloud Functions
This project also uses CircleCI for deployments.
The project includes a slack integration
for team members. Once you get registered, one of the admins can send you an invite to the slack channel.
The application uses Firebase Cloud Functions to emit slack notifications (1) when users are registered and (2) when activities are created
- please join the project's slack channel
- you can also login here
- create a firebase app (for free) with the console here
- register your app following the instructions here
- take the values you got from your registration and put them into the environment files in the
frontend/src/app/environment
directory - make sure to install the firebase CLI
- go to the
frontend
directory and runfirebase init
to initialize your application for hosting - from the project root run
npm run frontend-serve
and you should be good to go! - if you have further questions, please review the AngularFire2 docs
- create a firebase app (for free) with the console here
- make sure to install the firebase CLI
- create Slack webhooks for your project
- create a
.env
file in thefunctions
directory and put the values for the Slack Webhooks (note that this project uses dotenv) - go to the
functions
directory and runfirebase init
to initialize the dependencies etc. - in the
functions
directory runnpm run serve
to run them locally - in the
functions
directory runnpm run deploy
to deploy the functions to Google Cloud
This project is organized into the following folders:
docs
is where the markdown files are stored that are used in the instructions sitefrontend
is where the Angular 2+ application code residesfunctions
is where the Google Firebase Cloud Functions code residesscripts
is where all deployment scripts are located
The frontend project is organized based on feature in the following folders:
/src/app/activity
all components that are used to work with displaying and storing activity in the application/src/app/static
all static pages that show users or activity in the application/src/app/users
all components that are used to work with user accounts in the application/src/app/models
any models used in the applicationsrc/app/services
any services used in the application
npm run frontend-serve
runs the frontend angular application locallynpm run frontend-build
builds the frontend angular application locallynpm run frontend-deploy
deploys the frontend application to firebasenpm run functions-serve
runs the firebase cloud functions locallynpm run functions-deploy
deploys the firebase cloud functionsnpm run cypress-local
runs the cypress tests locally with a test runnernpm run cupress-ci
runs the cypress tests headless for CI deployments
Currently the application uses NgRx for the view-activity
and create-activity
pages. One of the items for improvement is to move some of the database calls into their own actions and improving the applications state management.
The application includes a Firebase Cloud Function that sends emails using Nodemailer. This automates sending an email to everyone with the week's high scores.
- The frontend application uses Cypress for e2e testing
- To run tests from the project root run
npm run frontend-cypress-test
- Note that you'll need to run the npm script for environment variables first with
npm run environment-variables
because the values used in testing are Cypress environment variables (see docs for more info) - When the project is deployed with CircleCI, Cypress is run in the pipeline with
npm run frontend-cypress-run
- When running the cypress tests for the frontend application, the npm module start-server-and-test is used
- The use of
http-get
was necessary withstart-server-and-test
because the frontend is an Angular Webpack project (see special note here) - Cypress environment variables are loaded in from the
cypress.json
file - Please checkout my blog post on Cypress Testing
- User guide code is in the
docs
folder - User guide is built with MkDocs
- In order to deploy a new copy of the user guide, you'll need to have MkDocs installed on your computer by following the directions here
- Once you have MkDocs installed, build the site by running (from the project root)
npm run docs-build
- When you're ready to deploy the site, deploy the site to be hosted on GitHub pages with
npm run docs-deploy
- Note that the message for the commit includes "[ci skip]", this is so that CircleCI will not run a build on the gh-pages branch
- Please consult the Firebase documentation for how to set this up
- Please also consult my blog post here
- Please also consult my blog post on how this project implements the JAMstack architecture here
- Please also consult my blog post on how Firebase Cloud Functions work here
Future improvements on the horizon (PR's Welcome!):
- Build out more tests for code coverage (potentially may be using Cypress for this in the future)
- Increase use of NgRx for state management (currently only used in
view-activity
andcreate-activity
components) - make application more responsive
- Add more details to the instructions (docs) site